Create enrollment

post

https://api.dlocal.com/enrollments

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

Enrollment with an initial payment: Use POST /payments and include an enrollment object in the request body.

Enrollment types:

ON_DEMAND: Merchant initiates recurring payments at any time, with no frequency or amount restrictions.
MERCHANT_SUBSCRIPTION: Merchant initiates recurring payments based on defined subscription settings (frequency, amount, dates).

Body Params

external_id

string

required

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

currency

string

required

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

country

string

required

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

type

string

enum

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).

Allowed:

description

string

Enrollment description. Max length: 200.

payment_method_id

string

required

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

payment_method_flow

string

enum

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.

Allowed:

payer

object

required

Payer information.

subscription

object

Subscription settings. Required for MERCHANT_SUBSCRIPTION type. Not applicable for ON_DEMAND.

notification_url

string

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

callback_url

string

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

device

object

Device information.

Responses

{
  "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

Status	Status code	Description
`PENDING`	`100`	The enrollment is awaiting user authorization, or a cancellation is being processed by the bank.
`ACTIVE`	`200`	The enrollment is active and ready for recurring payments.
`REJECTED`	`300`	The enrollment was not authorized or was rejected.
`CANCELLED`	`400`	The enrollment was cancelled by the merchant.
`CANCELLED`	`401`	The enrollment was cancelled by the user directly through their home banking.

Webhook notifications

Enrollment statuses

400Bad request.