Wallet payments
Learn how to start receiving wallet payments.
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:
Flow | Description |
---|---|
One time payment walletsREDIRECT | 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 walletsREDIRECT 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 2 months ago