Documentation
Documentation
OUR SOLUTION
COUNTRIES
CUSTOMERS
CONTACT US
dLocal Documentation
Solutions
Payins
Payouts
API Documentation
Payins API Reference
Security
Payment Methods
Payments
Credit Card Payments
Cash (Ticket) Payments
Bank Transfer Payments
Refunds
Orders
Currency Exchange
Country Reference
Payouts API Reference
Products
Smart Fields
GUIDES
API integration guide
PCI Compliance
Other
Changelog
Chinese 中文文档
Powered by GitBook

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:

post
Create a Payment

https://api.dlocal.com/payments
Creates a new payment using any of the available payment methods.
Request
Response
Body Parameters
amount
required
number
Transaction amount (in the currency entered in the field currency)
currency
required
string
Three-letter ISO-4217 currency code, in uppercase.
payment_method_id
optional
string
Payment method code chosen to make the payment, or the keyword CARD Required for DIRECT payment method flow.
payment_method_flow
required
string
Payment method flow, can be DIRECT or REDIRECT
country
required
string
User's country code. ISO 3166-1 alpha-2 code.
payer
required
object
Payer Object
card
optional
object
Card Object Required only for CARD payment type.
direct_debit
optional
object
Direct Debit Object Required only for DIRECT_DEBIT payment type.
order_id
required
string
ID given by the merchant in their system.
description
optional
string
Payment description.
notification_url
optional
string
URL where dlocal will send notifications associated to changes to this payment.
callback_url
optional
string
URL where dlocal does the final redirect. Required only for REDIRECT payment method flow.
200: OK
Example Response
{
    "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"
}

The Payer Object

Payer Object
Example Payer Object

Property

Type

Description

name

String

User's full name. Required.

email

String

User’s email address. Required.

birth_date

String

User’s birthdate (DD-MM-YYYY). Optional.

phone

String

User’s phone. Optional.

document

String

User’s personal identification number. Click here for more details. Required.

user_reference

String

Unique user id at the merchant side. Optional.

address

​Address Object ​

User’s address. Only required in India.

ip

String

User's IP address.

device_id

String

User's unique device identifier.

{
"name" : "Thiago Gabriel",
"email" : "thiago@example.com",
"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"
}

The Address Object

Address Object
Example Address Object

Property

Type

Description

state

String

User's address state. Optional.

city

String

User’s address city. Only required in India.

zip_code

String

User’s address zip_code. Optional.

street

String

User’s address street. Only required in India.

number

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"
}

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:

{
        "holder_name": "Thiago Gabriel",
        "expiration_month": 10,
        "expiration_year": 2040,
        "number": "4111111111111111",
        "cvv": "123"
 }

Example with Smart Fields token:

{
    "token":"CV-124c18a5-874d-4982-89d7-b9c256e647b5"
}

Example with card_id from Create a Card method:

{    
    "card_id":"CV-hgv23jh4g-n23n-kj3k-bkhb3-kj3hj3gjh3k3"
}

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

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

Example Request Body

{
    "amount": 120.00,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "thiago@example.com",
        "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.

Example 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

Example Request Body

{
    "amount": 120.00,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "thiago@example.com",
        "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"
}

get
Retrieve a Payment

https://api.dlocal.com/payments/{payment_id}
Retrieve information about an existing payment.
Request
Response
Path Parameters
payment_id
required
string
The payment id
200: OK
{
   "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" : []
}

Example Request

$ 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

get
Retrieve a Payment Status

https://api.dlocal.com/payments/{payment_id}/status
Retrieve information about the status of an existing payment.
Request
Response
Path Parameters
payment_id
required
string
The payment id
200: OK
Example Response
{
    "id": "PAY4334346343",
    "status" : "PAID",
    "status_detail" : "The payment was paid.",
    "status_code" : "200"
}

Example Request

$ 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

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.

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.

REJECTED

319

Amount exceeded.

REJECTED

320

3D-Secure is required.

REJECTED

321

Error in acquirer.

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

{
    "code": 5005,
    "message": "User unauthorized due to cadastral situation"
}

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

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

Request timeout.

​

5013

Unsupported operation.

​

5014

User blacklisted.

​

5016

Amount too low.

​

5017

Invalid API Version.

​

5018

Chargeback in place for this transaction.

429 Too many requests

6000

Too many requests to the API.

500 Internal Server Error

7000

Failed to process the request.

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 every 10 minutes for 30 days.

Example Notification POST

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": "buyer@gmail.com",
    },
    "order_id": "4m1OdghPUQtg",
    "notification_url": "http://www.merchant.com/notifications",
    "created_date": "2019-06-26T15:17:31.000+0000"
}

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 (SHA256 HMAC 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.

Previous
Uruguay
Next
Credit Card Payments
Last updated 1 month ago
Contents
post
Create a Payment
Example Request
get
Retrieve a Payment
Example Request
get
Retrieve a Payment Status
Example Request
Payment Status Codes
Rejection Status
Pending Status
Errors
Notifications
Signature of Notifications