The SmartPix offloads the full process to dLocal, including enrollment setup and Open Finance authorization. This option is fast to implement and ensures regulatory compliance.

Once authorized, dLocal returns a token that enables recurring payments without additional user input.

Need more control over the flow? Check out Authorization checkout managed by merchant to manage the enrollment setup directly via API.

Overall flow

This flow must be used to perform a single authorization without an associated payment.

User flow

Required User Experience

Transaction limits

When using SmartPix, merchants can choose between three configuration options for setting transaction limits on buyer authorizations.

Each option impacts the buyer experience and the validation behavior at the moment of payment:
There are 3 possible configurations regarding the transaction limits:

The buyer can optionally define the limits. The buyer can optionally access the limit editing screen and define all transaction limits. It is also possible for the buyer to proceed without setting any limits. In this case, payments of any amount will be accepted and will not be blocked by limit validation.
The Merchant defines a limit_per_payment. The merchant sets a fixed maximum amount per transaction limit_per_payment. The buyer cannot access the limit editing screen, but the defined limit will be displayed along with the following mandatory regulatory messages:
1. “Os próximos débitos serão no valor de produtos e serviços contratados por mim, com limite máximo de [R$ XXX,XX] por transação.”
2. “Não é possível definir um limite para essa autorização.”
No limits defined, and the merchant does not allow the payer to define them. No limits are defined by either the buyer or the merchant. The buyer cannot access the limit editing screen, and the interface must display that no limits have been set. The following regulatory messages will be shown:
1. “Os limites são indefinidos para permitir que o valor de sua assinatura ou compra seja debitado.”
2. “Não é possível definir um limite para essa autorização.”

Here are examples of the screens for the three possible configurations.

Authorization period

The expiration date must always be editable by the payer.

How to configure your most suitable option

Please contact your Technical Account Manager in order to set your default configuration for SmartPix limits.

One-time user authorization

The one-time authorization requires the user to select their preferred bank at the dLocal’s checkout, being redirected to their online banking to authorize the use of their bank account for future payments. Dlocal will provide a token via API that links the user to their account for subsequent payments.

Authorization with or without charge (verify)

Once the user has selected their bank at the merchant's checkout, this service must be used if the merchant wants to perform a single authorization with or without a related payment. The user will be redirected to their online banking to authorize the use of their account for payments, for which Dlocal will return a valid token.

If the authorization has a related first payment, amount should be >0 and verify should be false. If the authorization has no first payment, amount should be 0 and verify should be true.

Example request

URL Selector with Opacity

Post

Production URL Sandbox URL

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

{
    "amount": 0,
    "currency": "BRL",
    "country": "BR",
    "payment_method_id": "OS",
    "payment_method_flow": "REDIRECT",
    "order_id": "5346523564",
    "notification_url": "http://merchantsite.com/notifications",
    "callback_url": "http://merchantsite.com/callback",
    "payer": {
        "name": "Luiz Silva",
        "document": "12345678901"
     },
     "wallet": {
         "save": true, 
         "verify": true
     },
}

{
  "id": "R-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb0",
  "amount": 0,
  "currency": "BRL",
  "payment_method_id": "OS",
  "payment_method_type": "WALLET",
  "payment_method_flow": "REDIRECT",
  "country": "BR",
  "created_date": "2025-05-09T09:07:59.000+0000",
  "status": "PENDING",
  "status_detail": "The payment is pending.",
  "status_code": "100",
  "order_id": "5346523564",
  "notification_url": "http://merchantsite.com/notifications",
  "redirect_url": "https://pay.dlocal.com/gmf-apm/payments-redirect/M-fd77f5b7-ca28-7u54-9ed8-ef89d374a80c"
}

Asynchronous notification (webhook)

{
  "id": "R-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb0",
  "amount": 0,
  "status": "VERIFIED",
  "status_detail": "The wallet was verified",
  "status_code": "700",
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "OS",
  "payment_method_type": "WALLET",
  "payment_method_flow": "REDIRECT",
  "payer": {
    "name": "Luiz Silva",
    "document": "12345678901"
  },
  "wallet": {
    "token": "979d887a-2c63-4719-ba65-0b20b50f1cab"
  },
  "order_id": "5346523564",
  "notification_url": "http://www.merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback",
  "created_date": "2025-05-09T09:08:58.000+0000"
}

{
  "id": "R-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb0",
  "amount": 100,
  "status": "PAID",
  "status_detail": "The payment was paid.",
  "status_code": "200",
  "currency": "BRL",
  "country": "BR",
  "payment_method_id": "OS",
  "payment_method_type": "WALLET",
  "payment_method_flow": "DIRECT",
  "payer": {
    "name": "Luiz Silva",
    "document": "12345678901"
  },
  "wallet": {
    "token": "979d887a-2c63-4719-ba65-0b20b50f1cab"
  },
  "order_id": "5346523566",
  "notification_url": "http://www.merchantsite.com/notifications",
  "callback_url": "http://merchantsite.com/callback",
  "created_date": "2025-05-09T09:41:04.000+0000"
}

Request params

Field	Required	Type & Length	Description
`amount`	Yes	Number Length: 10.2	Set `amount=0` to execute an authorization with no charge.
`currency`	Yes	Three-letter ISO-4217 code	Transaction currency: `BRL`
`country`	Yes	ISO 3166-1 alpha-2 code	Payment processing country: `BR`
`payment_method_id`	Yes	String	ID of the selected payment method: `OS`
`payment_method_flow`	Yes	String	`REDIRECT` for one time auth `DIRECT` for Tokenized Payments
`order_id`	No	String (max. 125)	ID given by the merchant in their system
`notification_url`	No	String (max. 200)	Notifications will be sent in every change of status of a payment.
`callback_url`	No	String (max. 200)	URL where the user is going to be redirected after completing the flow.
`payer.name`	Yes	String (max. 100)	Payer’s name.
`payer.document`	Yes	Number (7 to 11 digits)	Payer’s document.
`wallet.save`	No	Boolean	Set `wallet.save=true` to enable wallet token for further payments. Default: `false`
`wallet.verify`	No	Boolean	Set `wallet.verify=true` to execute an authorization with no charge.

Response params

Field	Type	Description
`wallet.token`	String	Token generated for future payments of the user based on the authorization made in their online banking.