HomeGuidesAPI ReferenceStatus Page
Guides

Recurring flow / one-time user enrollment

Learn how to enroll users for making subsequent frictionless payments for subscriptions and on-demand payments.

Enrollment with no initial payment

Use this flow when you want to register consent only and charge later (e.g., free trial, future-dated subscriptions).

User flow

URL Selector with Opacity
Post

Request params

FieldTypeDescriptionRequired
currencyStringCOP

Transaction currency in ISO 4217.		Yes
countryStringCO

Transaction country in ISO 3166.		Yes
payment_method_idStringQF

ID of the selected payment method.		Yes
typeStringON_DEMAND: For future recurring payments initiated by the customer or merchant on demand, rather than on a fixed schedule.Yes
payment_method_flowStringREDIRECTYes
descriptionStringEnrollment description.No
Payer Object
payer.nameStringName of the payer.Yes
payer.emailStringEmail of the payer.No
payer.phoneStringPhone of the payer.No
payer.document_typeStringCC: Cédula de ciudadanía → Citizenship ID card / National ID card
CE: Cédula de Extranjería → Foreigner ID card
NUIP: Número único de identificación → Unique identification number
PPT: Permiso de Protección Temporal → Temporary Protection Permit
NIT: Número de Identificación Tributaria, sin dígito de verificación → Tax Identification Number, without check digit
PEP: Permiso Especial de Permanencia → Special Permit of Permanence
PAS: Número de Pasaporte → Passport number
TDI: Tarjeta de identidad → Identity card (for minors)

No

If not detailed, it will be required to the user in the redirect flow.

payer.documentNumberDocument number of the payer

No

If not detailed, it will be required to the user in the redirect flow.

external_idStringAn identifier used by the merchant to identify the enrollment in their system.Yes
order_idNumberID of the capture given by the merchant in their system. Think of it as an external ID of the capture.No
descriptionStringEnrollment description.No
notification_urlString (max. 200)Notifications will be sent on every change of status to the notification_url specified by the merchant.Yes
callback_urlStringURL where the user will be redirected after approval of the transaction.No

Sample request

{
  "currency": "COP",
  "country": "CO",
  "type": "ON_DEMAND",
  "payment_method_id": "QF",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Juan Pérez",
    "document": "123456789",
    "document_type": "CC",
    "email": "[email protected]",
    "phone": "3001112233"
  },
  "external_id": "12345678",
  "notification_url": "https://merchant.com/enrollment_notifications",
  "callback_url": "https://merchant.com/breb/callback"
}
{
  "id": "E-4-3a8bcc85-d86e-4c9a-bbc4-8393b5fb488e",
  "external_id": "12345678",
  "currency": "COP",
  "country": "CO",
  "payment_method_id": "QF",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2025-09-10T20:37:20.000+0000",
  "status": "PENDING",
  "status_detail": "The enrollment is pending.",
  "status_code": "100",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments/E-4-3a8bcc85-d86e-4c9a-bbc4-8393b5fb488e",
  "notification_url": "https://merchant.com/enrollment_notifications"
}
{
  "id": "E-4-3a8bcc85-d86e-4c9a-bbc4-8393b5fb488e",
  "external_id": "12345678",
  "currency": "COP",
  "country": "CO",
  "payment_method_id": "QF",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2025-09-10T20:37:20.000+0000",
  "status": "ACTIVE",
  "status_detail": "The enrollment is active.",
  "status_code": "200",
  "notification_url": "https://merchant.com/enrollment_notifications"
}

Response params

FieldTypeDescription
idStringEnrollment ID provided by dLocal, which must be used for future biometric payments.

Enrollment with initial payment

Use this when you want to create the enrollment and charge the first payment in a single call.

URL Selector with Opacity
Post

FieldTypeDescriptionRequired
amountNumberAmount to be charged.Yes
currencyStringCOP

Transaction currency in ISO 4217.		Yes
countryStringCO

Transaction country in ISO 3166.		Yes
payment_method_idStringQF

ID of the selected payment method.		Yes
payment_method_flowStringREDIRECTYes
Payer Object
payer.nameStringName of the payer.Yes
payer.emailStringEmail of the payer.No
payer.phoneStringPhone of the payer.No
payer.document_typeStringCC: Cédula de ciudadanía → Citizenship ID card / National ID card
CE: Cédula de Extranjería → Foreigner ID card
NUIP: Número único de identificación → Unique identification number
PPT: Permiso de Protección Temporal → Temporary Protection Permit
NIT: Número de Identificación Tributaria, sin dígito de verificación → Tax Identification Number, without check digit
PEP: Permiso Especial de Permanencia → Special Permit of Permanence
PAS: Número de Pasaporte → Passport number
TDI: Tarjeta de identidad → Identity card (for minors)

No

If not detailed, it will be required to the user in the redirect flow.

payer.documentNumberDocument number of the payer

No

If not detailed, it will be required to the user in the redirect flow.

Enrollment Object
enrollment.external_idStringAn identifier used by the merchant to identify the enrollment in their system.Yes
enrollment.typeStringON_DEMAND: For future recurring payments initiated by the customer or merchant on demand, rather than on a fixed schedule.Yes
enrollment.descriptionStringEnrollment description.No
order_idNumberID of the capture given by the merchant in their system. Think of it as an external ID of the capture.No
descriptionStringEnrollment description.No
notification_urlString (max. 200)Notifications will be sent on every change of status to the notification_url specified by the merchant.Yes
callback_urlStringURL where the user will be redirected after approval of the transaction.Yes

Sample request

{
  "amount": 30000,
  "currency": "COP",
  "country": "CO",
  "type": "ON_DEMAND",
  "payment_method_id": "QF",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Juan Pérez",
    "email": "[email protected]",
    "phone": "3001112233",
    "document_type": "CC",
    "document": "123456789"
  },
  "enrollment": {
    "external_id": "12345678",
    "notification_url": "https://merchant.com/en_notifications",
    "callback_url": "https://merchant.com/breb/callback"
  },
  "order_id": "breb-pay-001",
  "notification_url": "https://merchant.com/payment_notifications",
  "callback_url": "https://merchant.com/breb/payment_callback"
}
{
  "id": "D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb4",
  "amount": 30000,
  "currency": "COP",
  "payment_method_id": "QF",
  "payment_method_type": "TICKET",
  "payment_method_flow": "REDIRECT",
  "country": "CO",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments/D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb4",
  "created_date": "2025-09-10T20:37:20.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "breb-pay-001",
  "notification_url": "https://merchant.com/payment_notifications",
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
    "external_id": "12345678",
    "created_date": "2025-09-10T20:37:20.000+0000",
    "status": "PENDING",
    "status_detail": "The enrollment is pending.",
    "status_code": "100"
  }
}
{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
  "external_id": "12345678",
  "currency": "COP",
  "country": "CO",
  "type": "ON_DEMAND",
  "payment_method_id": "QF",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2025-09-10T20:37:20.000+0000",
  "status": "ACTIVE",
  "status_detail": "The enrollment is active.",
  "status_code": "200",
  "notification_url": "https://merchant.com/enrollment_notifications"
}
{
  "id": "D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb4",
  "amount": 30000,
  "status": "PAID",
  "status_detail": "The payment is paid.",
  "status_code": "200",
  "currency": "COP",
  "country": "CO",
  "payment_method_id": "QF",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "payer": {
    "name": "Juan Pérez",
    "email": "[email protected]",
    "phone": "+573001112233"
  },
  "enrollment": {
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
    "external_id": "12345678"
  },
  "order_id": "breb-pay-001",
  "notification_url": "https://merchant.com/payment_notifications",
  "created_date": "2025-09-10T20:37:20.000+0000"
}

Response params

FieldTypeDescription
idStringEnrollment ID provided by dLocal, which must be used for future biometric payments.

Updated 2 days ago

Did this page help you?
Terms and conditions Regulatory Disclosure Privacy Hub Politicas aplicáveis no Brasil

© 2025 DLOCAL. ALL RIGHTS RESERVED

Dlocal LLP (Company Number UK OC413287) is a limited liability partnership incorporated in England and Wales. DLocal Limited (Company Registration Number C77538) is authorised by the Malta Financial Services Authority under the Financial Institutions Act for the issuance of electronic money and the provision of payment services. Dlocal Corp LLP (Company Number UK OC 424987) is registered as a Money Service Business (MSB) with Financial Crime Enforcement Network in United States of America (USA) under MSB Registration Numbers 31000193620515. Dlocal Corp LLP acts as agent of e-commerce merchants based in the USA, and collects payments from end users based in emerging markets, on behalf of the merchants.