HomeGuidesAPI ReferenceStatus Page
Guides

Wallet payments

Learn how to start receiving wallet payments.

Suggest Edits

Wallet payments (WALLET) require the user to log in to their wallet provider through a redirect and approve the payment.

Once the first payment is successful with tokenized wallets, a token is returned which can be used to make recurring payments without the need of a redirect or to avoid authenticate again.

Payment flow

See the characteristics of the different flows to use. You can follow one of them:

FlowDescription
One time payment wallets
REDIRECT		In this flow, the customer is always redirected to the wallet's website to authenticate and complete the payment. Once that's done, will be redirected back to the merchant site.
Tokenized wallets
REDIRECT
DIRECT		In this flow, the customer is redirected to the wallet's website to authenticate and authorize future payments. If wallet.save = TRUE in the request, the asynchronous notification will include a wallet.token, which can be used for further payments without the need to authenticate again.

One time payment wallets

In this flow, the customer is always redirected to the wallet's website to authenticate and complete the payment. Once that's done, will be redirected back to the merchant site.

Available wallets

To integrate wallet payments, you must identify and complete the payment_method_id field of each one you want to use.

📘

Payment method list

You can get the payment method list or view all the available wallets by country in the Payment method section.

Verify flow

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/payments
   
{
    "amount": 26,
    "currency": "BRL",
    "country": "BR",
    "payment_method_id": "MP",
    "payment_method_flow": "REDIRECT",
    "payer": {
        "name": "Thiago Gabriel",
        "email": "[email protected]",
        "document": "53033315550"
    },
    "order_id": "5346523564",
    "notification_url": "http://merchantsite.com/notifications",
    "callback_url": "http://merchantsite.com/callback"
}

{
    "id": "R-4-41f8628f-b6ec-4c02-96d5-c5b03cac7cb0",
    "amount": 26,
    "currency": "BRL",
    "payment_method_id": "MP",
    "payment_method_type": "WALLET",
    "payment_method_flow": "REDIRECT",
    "country": "BR",
    "created_date": "2018-12-26T20:37:20.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://sandbox.dlocal.com/collect/pay/pay/M-0aa0cc00-094e-11e9-9f92-dbdad3ad0963?xtid=CATH-ST-1545856640-602791137"
}

Tokenized wallets

In this flow, the customer is redirected to the wallet's website to authenticate and authorize future payments. If wallet.save = TRUE in the request, the asynchronous notification will include a wallet.token, which can be used for further payments without the need to authenticate again.

Available wallets

To integrate wallet payments, you must identify and complete the payment_method_id field of each one you want to use.

📘

Payment method list

You can get the payment method list or view all the available wallets by country in the Payment method section.

Pay with a wallet token

⚠️

Recurring wallet payments

For recurring wallet payments in Philippines and Indonesia, the mobile number needs to be included as a parameter in the payer object of the payment request.

Example request

{
    "amount": 10,
    "currency": "BRL",
    "country": "BR",
    "payment_method_id": "MP",
    "payment_method_flow": "DIRECT",
    "payer": {
        "name": "EZXXVqiw sUbRyjAJ",
        "email": "[email protected]",
        "phone": "4832696773",
        "address": {
            "country": "BR",
            "state": "Santa Catarina",
            "city": "Florianopolis",
            "zip_code": "88058",
            "street": "Rodovia Armando Calil Bulos",
            "number": "5940"
        },
        "document": 91862865604
    },
    "wallet": {
        "username": "Test",
        "token": "xxxxx-xxxxx-xxxxx-xxxxx",
        "capture": true,
        "email": "[email protected]"
    },
    "order_id": "fe32a6ef-3954-4b5f-8712-d1c1079beba3",
    "description": "test-wallet",
    "notification_url": "http://conductor.sandbox.internal/robot-server/rest/generic/notification/new"
}

{
  "id": "F-4-b302affe-e590-4b29-98cc-57ec2dd10592",
  "amount": 10,
  "currency": "BRL",
  "payment_method_id": "MP",
  "payment_method_type": "WALLET",
  "payment_method_flow": "DIRECT",
  "country": "BR",
  "created_date": "2022-09-29T06:52:48.000+0000",
  "expiration_date": "2022-10-04T06:52:48.000+0000",
  "status": "Paid",
  "status_detail": "The payment was Paid.",
  "status_code": "200",
  "order_id": "fe32a6ef",
  "description": "test-wallet",
  "notification_url": "https://notifications.merchant.com"
}

Verify flow

⚠️

Recurring wallet payments

For recurring wallet payments in Philippines and Indonesia, the mobile number needs to be included as a parameter in the payer object of the payment request)

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/payments
   
{
   "amount": 0,
   "currency": "BRL",
   "country": "BR",
   "payment_method_id": "MP",
   "payment_method_flow": "REDIRECT",
   "payer": {
       "name": "Thiago Gabriel",
       "email": "[email protected]",
       "document": "53033315550"
   },
   "wallet": {
       "save": true,
       "verify": true,
       "capture": false,
       "label": "New subscription for merchant service"
   },
   "description": "Exclusive contents with this service",   
   "order_id": "5346523564",
   "notification_url": "http://merchantsite.com/notifications",
   "callback_url": "http://merchantsite.com/callback"
}

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 0,
   "currency": "BRL",
   "payment_method_id": "MP",
   "payment_method_type": "WALLET",
   "payment_method_flow": "REDIRECT",
   "country": "BR",
   "created_date": "2018-12-26T20:37:20.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://sandbox.dlocal.com/collect/pay/pay/M-0aa0cc00-094e-11e9-9f92-dbdad3ad0963?xtid=CATH-ST-1545856640-602791137"
}

Asynchronous notification

If wallet.save = TRUE, the notification will include a wallet.token as long as the user authenticated successfully (regardless of if the payment was approved or not).

Example asynchronous notification

POST: {payment.notification_url}

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 0.00,
   "status": "VERIFIED",
   "status_detail": "The wallet was verified.",
   "status_code": "700",
   "currency": "USD",
   "country": "BR",
   "payment_method_id": "MP",
   "payment_method_type": "WALLET",
   "payment_method_flow": "REDIRECT",
   "payer": {
       "name": "Thiago Gabriel",
       "email": "[email protected]",
       "document": "53033315550"
   },
   "wallet": {
       "token": "W-yu23y4ibnyiu23y4",
       "userid": "45696493593"
   },
   "order_id": "5346523564",
   "notification_url": "http://www.merchantsite.com/notifications",
   "created_date": "2018-12-26T20:37:20.000+0000"
}

Sale plus verify flow

In this flow the user is going to be charged with the amount indicated in the request. In case merchant send the "save"=true parameter in the wallet object. it will also generate a wallet token for future payments.

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: sak223k2wdksdl2' \
   -H 'X-Trans-Key: fm12O7G9' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
   -d '{body}'
   https://api.dlocal.com/payments
   
{
   "amount": 10.00,
   "currency": "BRL",
   "country": "BR",
   "payment_method_id": "MP",
   "payment_method_flow": "REDIRECT",
   "payer": {
       "name": "Thiago Gabriel",
       "email": "[email protected]",
       "document": "53033315550"
   },
   "wallet": {
       "save": true,
       "verify": false
   },  
   "order_id": "5346523564",
   "notification_url": "http://merchantsite.com/notifications",
   "callback_url": "http://merchantsite.com/callback"
}

{
   "id": "D-4-75c7473a-ab86-4e43-bd39-c840268747d3",
   "amount": 10.00,
   "currency": "BRL",
   "payment_method_id": "MP",
   "payment_method_type": "WALLET",
   "payment_method_flow": "REDIRECT",
   "country": "BR",
   "created_date": "2018-02-20T15:44:42.320Z",
   "status": "PENDING",
   "status_detail": "The payment is pending",
   "status_code": "100",
   "order_id": "5346523564",
   "notification_url": "http://merchant.com/notifications",
   "redirect_url": "https://sandbox.dlocal.com/collect/pay/pay/M-0aa0cc00-094e-11e9-9f92-dbdad3ad0963?xtid=CATH-ST-1545856640-602791137"
}

📘

DeviceId Object (for Mercado Pago only)

Find information on how to add the Device ID in the The DeviceId Object (for Mercado Pago only) page.

Updated 6 months 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.