---
title: "Create enrollment"
method: POST
path: "/enrollments"
tags: ["Enrollments"]
---

# Create enrollment

`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`

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

## Request body

- object
  - `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` '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).
  - `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` '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.
  - `payer` object, required: Payer information.
    - `name` string, required: Payer's full name. Max length: 100.
    - `document` string, required: Payer's personal identification number (e.g., CPF or CNPJ for Brazil). See country reference for document requirements per country.
    - `email` string, required: Payer's email address. Max length: 100.
    - `phone` string: Payer's phone number. Length: 20.
  - `subscription` object: Subscription settings. Required for `MERCHANT_SUBSCRIPTION` type. Not applicable for `ON_DEMAND`.
    - `start_date` string: Subscription start date (YYYY-MM-DD). Defaults to the current date if not provided.
    - `end_date` string: Subscription expiration date (YYYY-MM-DD). If not provided, the subscription does not expire.
    - `frequency` 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'SEMI_ANNUAL' | 'ANNUAL', required: Charge frequency. Possible values depend on the payment method: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, `ANNUAL`.
    - `amount` object: Subscription amount settings.
      - `type` 'FIXED' | 'VARIABLE', required: Amount type: `FIXED` (same amount each period) or `VARIABLE` (amount varies per charge within defined limits).
      - `value` number: Fixed charge amount in local currency. Required when `type` is `FIXED`. Length: 10,2.
      - `min_value` number: Minimum enrollment limit in local currency. This is the minimum the payer authorizes, **not** the minimum charge amount. Required when `type` is `VARIABLE` for applicable payment methods.
      - `max_value` number: Maximum allowed amount per charge. Required when `type` is `VARIABLE` for applicable payment methods.
  - `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.
    - `type` 'WEB' | 'MOBILE_APP': Device type. Possible values: `WEB`, `MOBILE_APP`.

## Response `200`

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**
```json
{
  "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**
```json
{
  "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. |

- object
  - `id` string: Enrollment ID provided by dLocal. Use this to create future recurring payments.
  - `external_id` string: Merchant-defined enrollment identifier.
  - `created_date` string: Enrollment creation timestamp (ISO 8601).
  - `status` string
  - `status_code` string: See enrollment status codes. Initial response is always `100` (PENDING).
  - `status_detail` string
  - `redirect_url` string: URL to redirect the user to complete the enrollment. Present only for `REDIRECT` flow.
  - `ticket` object: QR code or ticket for the user to authorize the enrollment. Present only for `DIRECT` flow on applicable payment methods (e.g., Pix Automático).
    - `type` string
    - `number` string: QR code string or copy-paste code the user scans in their banking app.
    - `expiration_date` string
    - `id` string
    - `image_url` string: URL to render the QR code image.
    - `provider_name` string
    - `provider_logo` string
  - `payment_method_type` string: Payment method type returned by dLocal. Possible values: `TICKET`, `WALLET`, `BANK_TRANSFER`.

## Other responses

- `400`: Bad request.

## Changes

- **2026-11-03** `e31ec9de4008`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dlocal/apis/payins/changes/enrollments/post.md)

---

[API](https://skmtc.dev/dlocal/apis/payins.md) - [All operations](https://skmtc.dev/dlocal/apis/payins/llms.txt) - [OpenAPI document](https://skmtc.dev/dlocal/apis/payins/revisions/e31ec9de4008?raw)