DLdlocal
Enrollments

Create enrollment

Changed on

Creates a new enrollment to enable recurring payments for a payer. Use this endpoint for enrollments without an initial payment.

post/enrollments

Request

  • Base URL
    https://api.dlocal.com
  • URL
    https://api.dlocal.com/enrollments
  • Auth
    API key in header X-Date and API key in header X-Login and API key in header X-Trans-Key and API key in header Content-Type and API key in header X-Version and API key in header User-Agent and API key in header Authorization

Request body

external_idstring required

Merchant-defined identifier used to reference the enrollment in their system.

currencystring required

Three-letter ISO-4217 currency code, in uppercase. Example: BRL, ARS.

countrystring required

Payment processing country code. ISO 3166-1 alpha-2 code. Example: BR, AR.

type'ON_DEMAND' | 'MERCHANT_SUBSCRIPTION' required

Enrollment type. Possible values:

  • ON_DEMAND: Recurring payments initiated by merchant at any time, with no frequency or amount restrictions.
  • MERCHANT_SUBSCRIPTION: Recurring payments initiated by merchant based on defined subscription settings (frequency, amount, dates).
descriptionstring

Enrollment description. Max length: 200.

payment_method_idstring required

Payment method code. Example: XA (Pix Automático). Length: 2.

payment_method_flow'DIRECT' | 'REDIRECT' required

Payment method flow.

  • DIRECT: Merchant manages the enrollment UI. dLocal returns all parameters via API.
  • REDIRECT: dLocal returns a redirect_url to send the user to an external page to complete enrollment.
notification_urlstring

URL where dLocal sends webhook notifications on every enrollment status change. Max length: 500.

callback_urlstring

URL where the user is redirected after completing the enrollment. Applicable for REDIRECT flow only. Max length: 500.

Response

Enrollment created. The response structure varies by payment_method_flow:

  • REDIRECT: returns a redirect_url.
  • DIRECT: returns a ticket object (QR code/copy-paste code) for applicable payment methods.

Webhook notifications

Once the enrollment is processed, dLocal sends an asynchronous notification to the notification_url provided in the request. Enrollment approved

{
  "id": "E-664388-3bcb6f88-9e71-4d90-a0e3-751971a5e5d8",
  "external_id": "31231jj224",
  "currency": "BRL",
  "country": "BR",
  "type": "MERCHANT_SUBSCRIPTION",
  "payment_method_id": "XA",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2024-07-26T20:37:20.000+0000",
  "approved_date": "2024-07-26T20:38:10.000+0000",
  "status": "ACTIVE",
  "status_detail": "The enrollment is active.",
  "status_code": "200",
  "notification_url": "http://merchantsite.com/notifications"
}

Enrollment rejected

{
  "id": "E-664388-3bcb6f88-9e71-4d90-a0e3-751971a5e5d8",
  "external_id": "31231jj224",
  "currency": "BRL",
  "country": "BR",
  "type": "MERCHANT_SUBSCRIPTION",
  "payment_method_id": "XA",
  "payment_method_flow": "REDIRECT",
  "payment_method_type": "TICKET",
  "created_date": "2024-07-26T20:37:20.000+0000",
  "status": "REJECTED",
  "status_detail": "The enrollment is rejected.",
  "status_code": "300",
  "notification_url": "http://merchantsite.com/notifications"
}

Enrollment statuses

StatusStatus codeDescription
PENDING100The enrollment is awaiting user authorization, or a cancellation is being processed by the bank.
ACTIVE200The enrollment is active and ready for recurring payments.
REJECTED300The enrollment was not authorized or was rejected.
CANCELLED400The enrollment was cancelled by the merchant.
CANCELLED401The enrollment was cancelled by the user directly through their home banking.
idstring

Enrollment ID provided by dLocal. Use this to create future recurring payments.

external_idstring

Merchant-defined enrollment identifier.

created_datestring

Enrollment creation timestamp (ISO 8601).

statusstring
status_codestring

See enrollment status codes. Initial response is always 100 (PENDING).

status_detailstring
redirect_urlstring

URL to redirect the user to complete the enrollment. Present only for REDIRECT flow.

payment_method_typestring

Payment method type returned by dLocal. Possible values: TICKET, WALLET, BANK_TRANSFER.

Example response

{
  "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca3",
  "external_id": "31231jj223",
  "created_date": "2024-07-26T20:37:20.000+0000",
  "status": "PENDING",
  "status_code": "100",
  "status_detail": "The enrollment is pending.",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments-redirect/E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca1",
  "ticket": {
    "type": "CUSTOM",
    "number": "00020101021226850014br.gov.bcb.pix...",
    "expiration_date": "2024-11-30T02:59:00.000+0000",
    "id": "Ts4ME3E05fFl8PhkNhkcIt4hIE",
    "image_url": "https://pay.dlocal.com/gmf-apm/payments/E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca3",
    "provider_name": "apm-bb-pix",
    "provider_logo": "https://static.dlocal.com/images/providers/pix.jpg"
  },
  "payment_method_type": "TICKET"
}

Changes