Payments
This service allows you to create, modify or read payments. For more details on specific types of payments, you can look at the following pages:
​Credit Card Payments​
​Cash (Ticket) Payments​
​Bank Transfer Payments​
postCreate a Payment
currency)CARD
Required for DIRECT payment method flow.DIRECT or REDIRECTCARD payment type.DIRECT_DEBIT payment typeREDIRECT payment flow.{"id": "PAY2323243343543","amount": 120.00,"currency" : "USD","country": "BR","payment_method_id" : "CARD","payment_method_type" : "CARD","payment_method_flow" : "DIRECT","card":{"holder_name": "Thiago Gabriel","expiration_month": 10,"expiration_year": 2040,"last4": "1111","brand": "VI"},"created_date" : "2018-02-15T15:14:52-00:00","approved_date" : "2018-02-15T15:14:52-00:00","status" : "PAID","status_code" : "200","status_detail" : "The payment was paid.","order_id": "657434343","notification_url": "http://merchant.com/notifications"}
Property | Type | Description |
| String | User's full name. Required. |
| String | User’s email address. Required. |
| String | User’s birthdate (DD-MM-YYYY). Optional. |
| String | User’s phone. Required for fraud prevention (see Fraud Prevention). |
| String | User’s personal identification number. Click here for more details. Required. |
| String | Additional personal identification. Optional. |
| String | Unique user id at the merchant side. Required for fraud prevention. |
| ​Address Object ​ | User’s address. Required in India and for fraud prevention. |
| String | User's IP address. Required for fraud prevention. |
| String | User's unique device identifier, for information on how to obtain the |
{"name" : "Thiago Gabriel","email" : "[email protected]","document" : "53033315550","user_reference": "12345","address": {"state" : "Rio de Janeiro","city" : "Volta Redonda","zip_code" : "27275-595","street" : "Servidão B-1","number" : "1106"},"ip" : "179.27.83.210","device_id" : "2fg3d4gf234"}
Property | Type | Description |
| String | User's address state. Optional. |
| String | User’s address city. Only required in India. |
| String | User’s address zip_code. Optional. |
| String | User’s address street. Only required in India. |
| String | User’s address number. Only required in India. |
{"state" : "Rio de Janeiro","city" : "Volta Redonda","zip_code" : "27275-595","street" : "Servidão B-1","number" : "1106"}
For credit card payments you can use the card information only if you business is Full PCI DSS compliant. Otherwise you need to collect the card information using Smart Fields. For recurring payments, make a payment with "save": true and use the card_id from the response for future payments.
Important: If you are making a payment with credit card information, you need to use the following endpoint instead: https://api.dlocal.com/secure_payments
Card payments with a card_id or token should use the endpoint: https://api.dlocal.com/payments
Property | Type | Description |
| String | Cardholder's full name. Required if |
| Integer | Two digit number representing the card's expiration month. Required if |
| Integer | Four digit number representing the card's expiration year. Required if |
| String | The card number, as a string without any separators. Required if |
| String | Credit card verification value. Optional. Required for India. |
| String | ​JWE encrypted params. Optional. |
| String | Temporary credit card token securely created using Smart Fields. Optional. |
| String | Temporary CVV token securely created using the CVV-only Smart Field. |
| String | Credit card id returned by the Create a Card call. Optional. |
| String | Number of installments. Default 1. Optional. |
| String | Installments id of a installments plan. Optional. |
| String | Dynamic Descriptor. Optional. |
| Boolean | Whether or not to immediately capture the charge. When false, the charge issues an authorization, and will need to be captured later. Default |
| Boolean | Whether or not to save the card for future payments. Response will include a |
{"holder_name": "Thiago Gabriel","expiration_month": 10,"expiration_year": 2040,"number": "4111111111111111","cvv": "123"}
{"token":"CV-124c18a5-874d-4982-89d7-b9c256e647b5"}
{"card_id":"CV-hgv23jh4g-n23n-kj3k-bkhb3-kj3hj3gjh3k3"}
Property | Type | Description |
| String | Name of the owner of the bank account. Required. |
| String | Email of the owner of the bank account. Required. |
| String | Document of the owner of the bank account. Required. |
| String | CBU of the owner of the bank account.. Required only for Argentina. |
The following example applies for credit card payments using the plain credit card information (only for Full PCI DSS merchants). To make payments using encrypted card information, simply replace the numberand cvvparameters with encrypted_data.
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/secure_payments
{"amount": 120.00,"currency" : "USD","country": "BR","payment_method_id" : "CARD","payment_method_flow" : "DIRECT","payer":{"name" : "Thiago Gabriel","email" : "[email protected]","document" : "53033315550","user_reference": "12345","address": {"state" : "Rio de Janeiro","city" : "Volta Redonda","zip_code" : "27275-595","street" : "Servidao B-1","number" : "1106"}},"card":{"holder_name" : "Thiago Gabriel","number" : "4111111111111111","cvv" : "123","expiration_month" : 10,"expiration_year" : 2040},"order_id": "657434343","notification_url": "http://merchant.com/notifications"}
The following example applies for credit card payments using a Smart Fields token. To make a payment with a card_idobtained from the Create a Card method, simply replace the tokenparameter with card_id.
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": 120.00,"currency" : "USD","country": "BR","payment_method_id" : "CARD","payment_method_flow" : "DIRECT","payer":{"name" : "Thiago Gabriel","email" : "[email protected]","document" : "53033315550","user_reference": "12345","address": {"state" : "Rio de Janeiro","city" : "Volta Redonda","zip_code" : "27275-595","street" : "Servidao B-1","number" : "1106"}},"card":{"token": "CV-124c18a5-874d-4982-89d7-b9c256e647b5"},"order_id": "657434343","notification_url": "http://merchant.com/notifications"}
getRetrieve a Payment
{"id" : "D-4-16112abb-b2c6-4799-86db-497c6bd321ac","amount" : 120.00,"currency" : "USD","payment_method_id" : "CARD","payment_method_type" : "CARD","payment_method_flow" : "DIRECT","country" : "BR","card" : {"holder_name" : "Thiago Gabriel","expiration_month" : 10,"expiration_year" : 2040,"brand" : "VI","last4" : "1111"},"created_date" : "2018-07-012T21:42:27.000+0000","approved_date" : "2018-07-012T21:42:28.000+0000","status" : "AUTHORIZED","status_detail" : "The payment was authorized","status_code" : "600","order_id" : "657434343","notification_url" : "http://merchant.com/notifications","refunds" : []}
$ curl \-H 'X-Date: 2018-02-20T15:44:42.310Z' \-H 'X-Login: sak223k2wdksdl2' \-H 'X-Trans-Key: fm12O7G9' \-H 'X-Version: 2.1' \-H 'User-Agent: MerchantTest / 1.0 ' \-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \https://api.dlocal.com/payments/PAY4334346343
getRetrieve a Payment Status
{"id": "PAY4334346343","status" : "PAID","status_detail" : "The payment was paid.","status_code" : "200"}
$ curl \-H 'X-Date: 2018-02-20T15:44:42.310Z' \-H 'X-Login: sak223k2wdksdl2' \-H 'X-Trans-Key: fm12O7G9' \-H 'X-Version: 2.1' \-H 'User-Agent: MerchantTest / 1.0 ' \-H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \https://api.dlocal.com/payments/PAY4334346343/status
Tip: You can test different status codes in Sandbox by sending the desired status code in the description field. Learn more here.​
Status | Status code | Description |
| 100 | The payment is pending. |
| 200 | The payment was paid. |
| 300 | The payment was rejected. |
| 400 | The payment was cancelled. |
| 500 | The payment was expired. |
| 600 | The payment was authorized. |
Status | Status code | Description |
| 300 | The payment was rejected. |
| 301 | Rejected by bank. |
| 302 | Insufficient amount. |
| 303 | Card blacklisted. |
| 304 | Score validation. |
| 305 | Max attempts reached. |
| 306 | Call bank for authorize. |
| 307 | Duplicated payment. |
| 308 | Credit card disabled. |
| 309 | Card expired. |
| 310 | Card reported lost. |
| 311 | Card requested by the bank. |
| 312 | Card restricted by the bank. |
| 313 | Card reported stolen. |
| 314 | Invalid card number. |
| 315 | Invalid security code. |
| 316 | Unsupported operation. |
| 317 | Rejected due to high risk. |
| 318 | Invalid transaction. |
| 319 | Amount exceeded. |
| 320 | 3D-Secure is required. |
| 321 | Error in acquirer. |
Status | Status code | Description |
| 100 | The payment is pending. |
| 101 | The payment is pending 3D Secure authentication. |
Below you can find an example of a Credit Card payment. For more examples visit this page.
For examples of Cash (ticket) payments, visit this page.
For examples of Bank Transfer payments, visit this page.
All the errors are returned with appropriate HTTP status code, 4XX or 5XX. The format of all errors is:
Property | Type | Description |
| Integer | Error code. |
| String | Human readable message. |
| String | In case one parameter is wrong. |
Example error
{"code": 5005,"message": "User unauthorized due to cadastral situation"}
HTTP Status Code | Error Code | Error Detail |
| 3001 | Invalid Credentials. |
​ | 3002 | Unregistered IP address. |
​ | 3003 | Merchant has no authorization to use this API. |
| 4000 | Payment not found. |
| 5000 | Invalid request. |
​ | 5001 | Invalid parameter: [parameter_name] |
​ | 5002 | Invalid transaction status. |
​ | 5003 | Country not supported. |
​ | 5004 | Currency not allowed for this country. |
​ | 5005 | User unauthorized due to cadastral situation. |
​ | 5006 | User limit exceeded. |
​ | 5007 | Amount exceeded. |
​ | 5008 | Token not found or inactive. |
​ | 5009 | Order id is duplicated. |
​ | 5010 | Method not available. |
​ | 5013 | Unsupported operation. |
​ | 5014 | User blacklisted. |
​ | 5016 | Amount too low. |
​ | 5017 | Invalid API Version. |
​ | 5018 | Chargeback in place for this transaction. |
| 6000 | Too many requests to the API. |
| 7000 | Failed to process the request. |
Notifications will be sent in every change of status of a payment to the notification URL specified by the merchant. This URL is taken from the notification_url field of the payment, if it differs from the one specified in the merchant panel. The body of the request will always be the payment object.
Until dLocal receives a 200 status code confirmation on these notifications, it will retry every 10 minutes for 30 days.
POST: {payment.notification_url}
{"id": "D-4-be8eda8c-5fe7-49dd-8058-4ddaac00611b","amount": 72.00,"status": "PAID","status_detail": "The payment was paid.","status_code": "200","currency": "USD","country": "AR","payment_method_id": "RP","payment_method_type": "TICKET","payment_method_flow": "REDIRECT","payer": {"name": "Nino Deicas","user_reference": "US-jmh3gb4kj5h34","email": "[email protected]",},"order_id": "4m1OdghPUQtg","notification_url": "http://www.merchant.com/notifications","created_date": "2019-06-26T15:17:31.000+0000"}
An HMAC signature is calculated using a request's key-value pairs and a secret key, which is known only to you and dLocal. By verifying this signature, you'll confirm that the notification was not modified during transmission.
dLocal will be signing each POST notification using the same method described on the Security section our the documentation (HMAC-SHA256 hash function).
Simply take the Authorization HTTP header from the notification, and compare it with the one generated by you using your X-Login and secretKey, and the X-Dateand Request body of the notification received. If the signature generated by you matched the one received on the Authorization HTTP header, then it is safe to assume that this is a valid message from dLocal.
