HomeGuidesAPI ReferenceStatus Page
Guides

One-time user enrollment

Learn how to enroll users for Pix payments, with or without an initial transaction.

Suggest Edits

The one-time authorization requires the merchant to define the subscription settings (frequency, amounts, and other parameters) to be sent via API to dLocal.

The user will be redirected to their home banking to authorize recurring payments via Pix. Once authorized, dLocal will provide a token via API that uniquely identifies the approved subscription, enabling future recurring payments without requiring further action from the user.

Enrollment with no initial payment

This flow must be used to perform a single authorization without an associated payment for both fixed-amount subscriptions and variable-amount subscriptions based on limits.

User flow

Once the user selects their subscription details at checkout, they will receive a QR code, which will be displayed along with a copy-and-paste transaction ID (local name) that they can use in their home banking to authorize the subscription.

The merchant will then receive a notification from dLocal via API with the authorization confirmation and the token associated with the approved subscription

Example request

URL Selector with Opacity
Post
curl -X POST \
   -H 'X-Date: {X-Date}' \
   -H 'X-Login: {X-Login}' \
   -H 'X-Trans-Key: {X-Trans-Key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \
   -d '{body}'
   https://api.dlocal.com/enrollments

{
    "external_id": "31231jj223",
    "currency": "BRL",
    "country": "BR",
    "type": "MERCHANT_SUBSCRIPTION",
    "description": "Pix Automatico - Annual subscription - Fixed amount",  
    "payment_method_id": "XA",
    "payment_method_flow": "DIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "document": "53033315550",
        "email": "user@mail.com"
    },
    "subscription":{
        "start_date": "2024-12-01",
        "end_date": "2028-12-01",
        "frequency": "ANNUAL",
        "amount":{
            "type": "FIXED",
            "value": "588"
        },
     },
     "notification_url": "http://merchantsite.com/notifications",
     "callback_url": "http://merchantsite.com/callback"
}

{
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca3",
    "external_id": "31231jj223",
    "created_date": "2024-07-26T20:37:20.000+0000",
    "ticket": {
        "type": "CUSTOM",
        "number": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/e268f040-7248-4677-ac42-0a510a1e038c52040000530398654045.005802BR5925DEMERGE BRASIL FACILITADO6009SAO PAULO62070503***630405CC",
        "expiration_date": "2024-11-30T02:59:00.000+0000",
        "id": "Ts4ME3E05fFl8PhkNhkcIt4hIE",
        "barcode": "iVBORw0KGgoAAAANSUhEUgAAAJMAAACTCAIAAAAFh7xCAAAOHUlEQVR4XQXLkSBID5/+f",
        "company_name": "",
        "provider_name": "apm-bb-pix",
        "provider_logo": "https://static.dlocal.com/images/providers/pix.jpg",
        "image_url": "https://pay.dlocal.com/gmf-apm/payments/E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca3",
        "amount": "",
        "currency": "BRL"
    },
    "status": "PENDING",
    "status_detail": "The enrollment is pending.",
    "status_code": "100"
}

{
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca3",
    "external_id": "31231jj223",
    "currency": "BRL",
    "country": "BR",
    "type": "MERCHANT_SUBSCRIPTION",
    "payment_method_id": "XA",
    "payment_method_flow": "DIRECT",
    "payment_method_type": "TICKET",
    "created_date": "2024-07-26T20:37:20.000+0000",
    "status": "ACTIVE",
    "status_detail": "The enrollment is active.",
    "status_code": "200",
    "notification_url": "http://merchantsite.com/notifications"
}

Request params

FieldTypeDescriptionRequired
external_idStringAn identifier used by the merchant to identify the enrollment in their system.Yes
currencyStringBRL
Transaction currency in ISO 4217 .		Yes
countryISO 3166-1 alpha-2 codeBR
Transaction country in ISO 3166 .		Yes
typeStringPossible options include:
MERCHANT_SUBSCRIPTION: For subscriptions with future recurring payments initiated by the merchant.
SCHEDULED_SUBSCRIPTION: For subscriptions with future recurring payments initiated by dlocal.		Yes
descriptionStringEnrollment description.No
payment_method_idStringXA
ID of the selected payment method.		Yes
payment_method_flowStringIndicates whether the flow is DIRECT or REDIRECT.Yes
Payer Object
payer.nameString (max. 100)Name of the payer.Yes
payer.documentNumber (between 7 to 9 or 11 digits)Document of the payer. (CPF or CNPJ).Yes
payer.emailString (max. 100)Email of the payer.No
Subscription Object
subscription.start_dateString (YYYY-MM-DD)Subscription start date. The default is the current date. To be used only for subscriptions.No
subscription.end_dateString (YYYY-MM-DD)Subscription expiration date. If not provided, the subscription will not expire. To be used only for subscriptions.No
subscription.frequencyStringPossible values depending on the payment method: WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUAL, ANNUAL.Yes
Subscription Amount Object
subscription.
subscription.amount.
type		StringPossible values depending on the subscription:
FIXED: For fixed amount subscription;
VARIABLE: For variable amount subscriptions.		Yes
subscription.
subscription.amount.
value		Number (10,2)Fixed subscription amount in local currency. Required only for fixed amount subscriptions depending on the payment method.Conditional
subscription.
subscription.amount.
min_value		Number (10,2)Minimum allowed amount in local currency for each charge.Yes
order_idString (max. 125)ID given by the merchant in their system.No
notification_urlString (max. 200)Notifications will be sent in every change of status to the notification_url specified by the merchant.No

Response params

FieldTypeDescription
idStringEnrollment ID provided by dlocal, which must be used for future recurring payments.

Enrollment with an initial payment

This variant of the service allows the merchant to invoke user authorization for a fixed or variable amount subscription and execute a payment at the same time.

User flow

Example request

URL Selector with Opacity
Post
curl -X POST \
   -H 'X-Date: {X-Date}' \
   -H 'X-Login: {X-Login}' \
   -H 'X-Trans-Key: {X-Trans-Key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \
   -d '{body}'
   https://api.dlocal.com/payments

{
  "enrollment": {
    "external_id": "31231jj224",
    "type": "MERCHANT_SUBSCRIPTION",
    "description": "Pix Automatico - Monthly subscription - Variable amount",
    "notification_url": "http://merchantsite.com/enrollment_notifications",
    "callback_url": "http://merchantsite.com/enrollment_callback",
    "subscription": {
      "start_date": "2024-12-01",
      "end_date": "2025-12-01",
      "frequency": "MONTHLY",
      "amount": {
        "type": "VARIABLE",
        "min_value": "300"
      }
    }
  },
  "amount": 285,
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "XA",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Thiago Gabriel",
    "document": "53033315550",
    "email": "53033315550"
  },
  "order_id": "payment-221124442ab",
  "notification_url": "http://merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback"
}

{
    "enrollment": {
        "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
        "external_id": "31231jj224",
        "created_date": "2024-07-26T20:37:20.000+0000",
        "status": "PENDING",
        "status_detail": "The enrollment is pending.",
        "status_code": "100"
    },
    "id": "D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb4",
    "currency": "BRL",
    "country": "BR",
    "payment_method_id": "XA",
    "payment_method_flow": "DIRECT",
    "payment_method_type": "TICKET",
    "ticket": {
            "type": "CUSTOM",
            "number": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/e268f040-7248-4677-ac42-0a510a1e038c52040000530398654045.005802BR5925DEMERGE BRASIL FACILITADO6009SAO PAULO62070503***630405CD",
            "expiration_date": "2024-11-30T02:59:00.000+0000",
            "id": "Ts4ME3E05fFl8PhkNhkcIt4hID",
            "barcode": "iVBORw0KGgoAAAAgAAAJMAAACTCAIAAAAFh7xCAAAOHUlEQVR4XQXLkSBIDD/+f",
            "company_name": "",
            "provider_name": "apm-bb-pix",
            "provider_logo": "https://static.dlocal.com/images/providers/pix.jpg",
            "image_url": "https://pay.dlocal.com/gmf-apm/payments/E-4-32e1218f-b6ec-3f21-13d5-50v12ere2cD3",
            "amount": 285,
            "currency": "BRL"
    },
    "created_date": "2024-07-26T20:37:20.000+0000",
    "order_id": "payment-221124442ab",
    "amount": 285,
    "status": "PENDING",
    "status_detail": "The payment is pending.",
    "status_code": "100",
    "notification_url": "http://merchantsite.com/notifications"
}

{
    "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
    "external_id": "31231jj224",
    "currency": "BRL",
    "country": "BR",
    "type": "MERCHANT_SUBSCRIPTION",
    "payment_method_id": "XA",
    "payment_method_flow": "DIRECT",
    "payment_method_type": "TICKET",
    "created_date": "2024-07-26T20:37:20.000+0000",
    "status": "ACTIVE",
    "status_detail": "The enrollment is active.",
    "status_code": "200",
    "notification_url": "http://merchantsite.com/notifications"
}


{
  "id": "D-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb4",
  "amount": 285,
  "status": "PAID",
  "status_detail": "The payment is paid",
  "status_code": "200",
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "XA",
  "payment_method_flow": "DIRECT",
  "payment_method_type": "TICKET",
  "payer": {
     "name": "Thiago Gabriel",
     "email": "thiago@example.com",
     "document": "53033315550"
  },
  "enrollment": {
     "id": "E-4-32e1218f-b6ec-3f21-13d5-50v12ere2ca4",
     "external_id": "31231jj224"
  },
  "order_id": "payment-221124442ab",
  "notification_url": "http://www.merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback",
  "created_date": "2024-07-26T20:37:20.000+0000"
}

Enrollment status codes

Status CodeStatusStatus detailsDescription
100PENDINGThe enrollment is pendingThe enrollment was created and it's awaiting further action or confirmation
200ACTIVEThe enrollment is activeThe enrollment was approved and is active to process payments
300REJECTEDThe enrollment is rejectedThe enrollment was rejected and payments cannot be processed
400CANCELLEDThe enrollment is cancelledThe enrollment was cancelled and payments cannot be processed
800EXPIREDThe enrollment is expiredThe enrollment has expired, and payments cannot be processed

Updated about 2 hours ago

© 2024 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.