Credit Card Payments

For credit card payments you can use the card information only if you business is Full PCI DSS compliant. Otherwise you need to securely collect the card information using Smart Fields. 
For recurring payments, first save the card, and then use the card_id to charge the card.
Important: If you are making a payment with credit card information, you need to use the following endpoint: 
https://api.dlocal.com/secure_payments
Card payments with a card_id or token should use the endpoint: https://api.dlocal.com/payments
post
Create a Card Payment
https://api.dlocal.com/payments
Creates a new payment using any of the available payment methods.
Request
Response
Request
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
required
string
Always send CARD for card payments.
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 DIRECT payment_method_flow.
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.
Response
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
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.
Example Payer Object
{
"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
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.
Example Address Object
{
"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
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 Card Object
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"
}
​
Pay with Card information 
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
Example Response
Example Request
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"
        },
        "ip" : "179.27.83.210",
        "device_id" : "2fg3d4gf234"
    },
    "card":{
        "holder_name" : "Thiago Gabriel",
        "number" : "4111111111111111",
        "cvv" : "123",
        "expiration_month" : 10,
        "expiration_year" : 2040
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
Example Response
Example Response
{
    "id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
    "amount": 120,
    "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-12-26T20:26:09.000+0000",
    "approved_date": "2018-12-26T20:26:09.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid",
    "status_code": "200",
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
Pay with  Smart Fields​
The following example applies for credit card payments using a Smart Fields token.
Example Request
Example Response
Example Request
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"
        },
        "ip" : "179.27.83.210",
        "device_id" : "2fg3d4gf234"
    },
    "card":{
        "token": "CV-124c18a5-874d-4982-89d7-b9c256e647b5"
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
Example Response
Example Response
{
    "id": "D-4-80ca7fbd-67ad-444a-aa88-791ca4a0c2b2",
    "amount": 120,
    "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-12-26T20:28:47.000+0000",
    "approved_date": "2018-12-26T20:28:47.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid",
    "status_code": "200",
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
Pay with Saved Card
The following example applies for credit card payments using a the card_id gotten in the Create a Card method.​​
Example Request
Example Response
Example Request
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"
        },
        "ip" : "179.27.83.210",
        "device_id" : "2fg3d4gf234"
    },
    "card":{
        "card_id": "CID-124c18a5-874d-4982-89d7-b9c256e647b5"
    },
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
Example Response
Example Response​
{
    "id": "D-4-80ca7fbd-67ad-444a-aa88-791ca4a0c2b2",
    "amount": 120,
    "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-12-26T20:28:47.000+0000",
    "approved_date": "2018-12-26T20:28:47.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid",
    "status_code": "200",
    "order_id": "657434343",
    "notification_url": "http://merchant.com/notifications"
}
Other Card Payment Operations
​Authorization and Capture​
​Chargebacks​
​3D-Secure​
​Save Card on a Payment​
​Installments​

Payments

Authorization and Capture

Last updated 8 months ago

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.

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.

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 if`encrypted_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.

Credit Card Payments

post
Create a Card Payment

The Payer Object

The Address Object

The Card Object

Example with raw credit card information:

Example with Smart Fields `token`:

Example with `card_id` from Create a Card method:

Pay with Card information

Example Request

Example Request Body

Example Response

Pay with Smart Fields

Example Request

Example Request Body

Example Response

Pay with Saved Card

Example Request

Example Request Body

Example Response

Other Card Payment Operations

Credit Card Payments

postCreate a Card Payment

The Payer Object

The Address Object

The Card Object

Example with raw credit card information:

Example with Smart Fields token:

Example with card_id from Create a Card method:

Pay with Card information

Example Request

Example Request Body

Example Response

Pay with Smart Fields​

Example Request

Example Request Body

Example Response

Pay with Saved Card

Example Request

Example Request Body

Example Response​

Other Card Payment Operations

post
Create a Card Payment

Example with Smart Fields `token`:

Example with `card_id` from Create a Card method:

Pay with Smart Fields

Example Response