Payments

OUR SOLUTION COUNTRIES CUSTOMERS CONTACT US
Search…
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​
post
https://api.dlocal.com
/payments
Create a Payment
The Payer Object
Payer Object
Example Payer Object
Property
Type
Description
name
String
User's full name. Required. 
​
Length: 100.
email
String
User’s email address. Required. 
​
Length: 100.
birth_date
String
User’s birthdate (DD-MM-YYYY). Optional. 
​
Length: 10.
phone
String
User’s phone. Mandatory for Wallets in India. Also required for fraud prevention (see Fraud Prevention). 
​
Length: 20.
document
String
User’s personal identification number. Click here for more details. Required. 
​
Length: 30.
document2
String
Additional personal identification. Optional.
user_reference
String
Unique user id at the merchant side. Required for fraud prevention. 
​
Length: 125.
address
​Address Object ​
User’s address. Required in India and South Africa for fraud prevention. 
ip
String
User's IP address. Required for fraud prevention.
​
Length: 20.
device_id
String
User's unique device identifier, for information on how to obtain the device_id see the Device ID documentation. Required for fraud prevention. 
​
Length: 25.
1
{
2
"name" : "Thiago Gabriel",
3
"email" : "[email protected]",
4
"document" : "53033315550",
5
"user_reference": "12345",
6
"address": {
7
    "state"  : "Rio de Janeiro",
8
    "city" : "Volta Redonda",
9
    "zip_code" : "27275-595",
10
    "street" : "Servidão B-1",
11
    "number" : "1106"
12
},
13
"ip" : "179.27.83.210",
14
"device_id" : "2fg3d4gf234"
15
}
Copied!
The Address Object
Address Object
Example Address Object
Property
Type
Description
state
String
User's address state. Required in South Africa. 
​
Length: 10.
city
String
User’s address city. Required in India and South Africa. 
​
Length: 100.
zip_code
String
User’s address zip_code. Required in South Africa. 
​
Length: 10.
street
String
User’s address street. Required in India and South Africa. 
​
Length: 100.
number
String
User’s address number. Required in India and South Africa. 
​
Length: 20.
1
{
2
"state"  : "Rio de Janeiro",
3
"city" : "Volta Redonda",
4
"zip_code" : "27275-595",
5
"street" : "Servidão B-1",
6
"number" : "1106"
7
}
Copied!
The Card Object
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
Card Object
Example Card Object
Property
Type
Description
holder_name
String
Cardholder's full name. Required if token or card_id not present
expiration_month
Integer
Two digit number representing the card's expiration month. Required if token or card_id not present
expiration_year
Integer
Four digit number representing the card's expiration year. Required if token or card_id not present
number
String
The card number, as a string without any separators.  Required ifencrypted_data ,token or card_id not present
cvv
String
Credit card verification value. Optional. Required for India.
encrypted_data
String
​JWE encrypted params. Optional.
token
String
Temporary credit card token securely created using Smart Fields. Optional.
cvv_token
String
Temporary CVV token securely created using the CVV-only Smart Field.
card_id
String
Credit card id returned by the Create a Card call. Optional.
installments
String
Number of installments. Default 1. Optional.
installments_id
String
Installments id of a installments plan. Optional.
descriptor
String
Dynamic Descriptor.  Optional.
capture
Boolean
Whether or not to immediately capture the charge. When false, the charge issues an authorization, and will need to be captured later. Default TRUE. Optional.
save
Boolean
Whether or not to save the card for future payments. Response will include a card_id. Learn more.​
Example with raw credit card information:
1
{
2
        "holder_name": "Thiago Gabriel",
3
        "expiration_month": 10,
4
        "expiration_year": 2040,
5
        "number": "4111111111111111",
6
        "cvv": "123"
7
 }
Copied!
Example with Smart Fields token:
1
{
2
    "token":"CV-124c18a5-874d-4982-89d7-b9c256e647b5"
3
}
Copied!
Example with card_id from Create a Card method:
1
{    
2
    "card_id":"CV-hgv23jh4g-n23n-kj3k-bkhb3-kj3hj3gjh3k3"
3
}
Copied!
The Direct Debit Object
Property
Type
Description
holder_name
String
Name of the owner of the bank account. Required.
email
String
Email of the owner of the bank account. Required.
document
String
Document of the owner of the bank account. Required.
cbu
String
CBU of the owner of the bank account.. Required only for Argentina.
Example Request
Payment with Credit Card Information 
Payment with Credit Card Token
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.
Example Request
1
curl -X POST \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'Content-Type: application/json' \
6
    -H 'X-Version: 2.1' \
7
    -H 'User-Agent: MerchantTest / 1.0 ' \
8
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
    -d '{body}'
10
    https://api.dlocal.com/secure_payments
Copied!
Example Request Body
1
{
2
    "amount": 120.00,
3
    "currency" : "USD",
4
    "country": "BR",
5
    "payment_method_id" : "VD",
6
    "payment_method_flow" : "DIRECT",
7
    "payer":{
8
        "name" : "Thiago Gabriel",
9
        "email" : "[email protected]",
10
        "document" : "53033315550",
11
        "user_reference": "12345",
12
        "address": {
13
            "state"  : "Rio de Janeiro",
14
            "city" : "Volta Redonda",
15
            "zip_code" : "27275-595",
16
            "street" : "Servidao B-1",
17
            "number" : "1106"
18
        }
19
    },
20
    "card":{
21
        "holder_name" : "Thiago Gabriel",
22
        "number" : "4111111111111111",
23
        "cvv" : "123",
24
        "expiration_month" : 10,
25
        "expiration_year" : 2040
26
    },
27
    "order_id": "657434343",
28
    "notification_url": "http://merchant.com/notifications"
29
}
Copied!
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.
Example Request
1
curl -X POST \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'Content-Type: application/json' \
6
    -H 'X-Version: 2.1' \
7
    -H 'User-Agent: MerchantTest / 1.0 ' \
8
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
9
    -d '{body}'
10
    https://api.dlocal.com/payments
Copied!
Example Request Body
1
{
2
    "amount": 120.00,
3
    "currency" : "USD",
4
    "country": "BR",
5
    "payment_method_id" : "VD",
6
    "payment_method_flow" : "DIRECT",
7
    "payer":{
8
        "name" : "Thiago Gabriel",
9
        "email" : "[email protected]",
10
        "document" : "53033315550",
11
        "user_reference": "12345",
12
        "address": {
13
            "state"  : "Rio de Janeiro",
14
            "city" : "Volta Redonda",
15
            "zip_code" : "27275-595",
16
            "street" : "Servidao B-1",
17
            "number" : "1106"
18
        }
19
    },
20
    "card":{
21
        "token": "CV-124c18a5-874d-4982-89d7-b9c256e647b5"
22
    },
23
    "order_id": "657434343",
24
    "notification_url": "http://merchant.com/notifications"
25
}
Copied!
get
 https://api.dlocal.com/payments/
{payment_id}
Retrieve a Payment
Example Request
1
$ curl \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'X-Version: 2.1' \
6
    -H 'User-Agent: MerchantTest / 1.0 ' \
7
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
8
    https://api.dlocal.com/payments/PAY4334346343
Copied!
get
https://api.dlocal.com/payments/
{payment_id}/status
Retrieve a Payment Status
Example Request
1
$ curl \
2
    -H 'X-Date: 2018-02-20T15:44:42.310Z' \
3
    -H 'X-Login: sak223k2wdksdl2' \
4
    -H 'X-Trans-Key: fm12O7G9' \
5
    -H 'X-Version: 2.1' \
6
    -H 'User-Agent: MerchantTest / 1.0 ' \
7
    -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1686a6bdad5940e7bb6aa596c96e0a6ec' \
8
    https://api.dlocal.com/payments/PAY4334346343/status
Copied!
Payment Status Codes
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
PENDING
100
The payment is pending.
PAID
200
The payment was paid.
REJECTED
300
The payment was rejected.
CANCELLED
400
The payment was cancelled.
EXPIRED
500
The payment was expired.
AUTHORIZED
600
The payment was authorized.
VERIFIED
700
The payment was verified.
Rejection Status
Status
Status code
Description
REJECTED
300
The payment was rejected.
REJECTED
301
Rejected by bank.
REJECTED
302
Insufficient amount.
REJECTED
303
Card blacklisted.
REJECTED
304
Score validation.
REJECTED
305
Max attempts reached.
REJECTED
306
Call bank for authorize.
REJECTED
307
Duplicated payment.
REJECTED
308
Credit card disabled.
REJECTED
309
Card expired.
REJECTED
310
Card reported lost.
REJECTED
311
Card requested by the bank.
REJECTED
312
Card restricted by the bank.
REJECTED
313
Card reported stolen.
REJECTED
314
Invalid card number.
REJECTED
315
Invalid security code.
REJECTED
316
Unsupported operation.
REJECTED
317
Rejected due to high risk.
REJECTED
318
Invalid transaction.
Pending Status
Status
Status code
Description
PENDING
100
The payment is pending.
PENDING
101
The payment is pending 3D Secure authentication.
Errors
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
code
Integer
Error code.
message
String
Human readable message.
param
String
In case one parameter is wrong.
Example error
1
{
2
    "code": 5005,
3
    "message": "User unauthorized due to cadastral situation"
4
}
Copied!
Http Errors
HTTP Status Code
Error Code
Error Detail
403 Forbidden
3001
Invalid Credentials.
​
3002
Unregistered IP address.
​
3003
Merchant has no authorization to use this API.
404 Not Found
4000
Payment not found.
400 Bad Request
5000
Invalid request.
​
5001
Missing 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.
Notifications
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 once an hour for 7 days.
Example Notification POST
POST: {payment.notification_url}
1
{
2
    "id": "D-4-be8eda8c-5fe7-49dd-8058-4ddaac00611b",
3
    "amount": 72.00,
4
    "status": "PAID",
5
    "status_detail": "The payment was paid.",
6
    "status_code": "200",
7
    "currency": "USD",
8
    "country": "AR",
9
    "payment_method_id": "RP",
10
    "payment_method_type": "TICKET",
11
    "payment_method_flow": "REDIRECT",
12
    "payer": {
13
        "name": "Nino Deicas",
14
        "user_reference": "US-jmh3gb4kj5h34",
15
        "email": "[email protected]",
16
    },
17
    "order_id": "4m1OdghPUQtg",
18
    "notification_url": "http://www.merchant.com/notifications",
19
    "created_date": "2019-06-26T15:17:31.000+0000"
20
}
Copied!
Signature of Notifications
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.