Credit Card Payments

OUR SOLUTION COUNTRIES CUSTOMERS CONTACT US
Search…
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 or a Google Pay™ token, 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
https://api.dlocal.com
/payments
Create a Card Payment
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. Required for fraud prevention (see Fraud Prevention).
document
String
User’s personal identification number. Click here for more details. Required.
user_reference
String
Unique user id at the merchant side. Required for fraud prevention.
address
​Address Object ​
User’s address. Required in India and for fraud prevention.
ip
String
User's IP address. Required for fraud prevention.
device_id
String
User's unique device identifier. Required for fraud prevention.
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. Optional. Required in South Africa.
city
String
User’s address city. Only required in India & South Africa.
zip_code
String
User’s address zip_code. Optional. Required in South Africa.
street
String
User’s address street. Only required in India & South Africa.
number
String
User’s address number. Only required in India & South Africa.
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!
​
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
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
        "ip" : "179.27.83.210",
20
        "device_id" : "2fg3d4gf234"
21
    },
22
    "card":{
23
        "holder_name" : "Thiago Gabriel",
24
        "number" : "4111111111111111",
25
        "cvv" : "123",
26
        "expiration_month" : 10,
27
        "expiration_year" : 2040
28
    },
29
    "order_id": "657434343",
30
    "notification_url": "http://merchant.com/notifications"
31
}
Copied!
Example Response
1
{
2
    "id": "D-4-cf8eef6b-52d5-4320-b5ea-f5e0bbe4343f",
3
    "amount": 120,
4
    "currency": "USD",
5
    "payment_method_id": "CARD",
6
    "payment_method_type": "CARD",
7
    "payment_method_flow": "DIRECT",
8
    "country": "BR",
9
    "card": {
10
        "holder_name": "Thiago Gabriel",
11
        "expiration_month": 10,
12
        "expiration_year": 2040,
13
        "brand": "VI",
14
        "last4": "1111"
15
    },
16
    "created_date": "2018-12-26T20:26:09.000+0000",
17
    "approved_date": "2018-12-26T20:26:09.000+0000",
18
    "status": "PAID",
19
    "status_detail": "The payment was paid",
20
    "status_code": "200",
21
    "order_id": "657434343",
22
    "notification_url": "http://merchant.com/notifications"
23
}
Copied!
Pay with  Smart Fields​
The following example applies for credit card payments using a Smart Fields token.
Example Request
Example Response
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
        "ip" : "179.27.83.210",
20
        "device_id" : "2fg3d4gf234"
21
    },
22
    "card":{
23
        "token": "CV-124c18a5-874d-4982-89d7-b9c256e647b5"
24
    },
25
    "order_id": "657434343",
26
    "notification_url": "http://merchant.com/notifications"
27
}
Copied!
Example Response
1
{
2
    "id": "D-4-80ca7fbd-67ad-444a-aa88-791ca4a0c2b2",
3
    "amount": 120,
4
    "currency": "USD",
5
    "payment_method_id": "CARD",
6
    "payment_method_type": "CARD",
7
    "payment_method_flow": "DIRECT",
8
    "country": "BR",
9
    "card": {
10
        "holder_name": "Thiago Gabriel",
11
        "expiration_month": 10,
12
        "expiration_year": 2040,
13
        "brand": "VI",
14
        "last4": "1111"
15
    },
16
    "created_date": "2018-12-26T20:28:47.000+0000",
17
    "approved_date": "2018-12-26T20:28:47.000+0000",
18
    "status": "PAID",
19
    "status_detail": "The payment was paid",
20
    "status_code": "200",
21
    "order_id": "657434343",
22
    "notification_url": "http://merchant.com/notifications"
23
}
Copied!
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
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
        "ip" : "179.27.83.210",
20
        "device_id" : "2fg3d4gf234"
21
    },
22
    "card":{
23
        "card_id": "CID-124c18a5-874d-4982-89d7-b9c256e647b5"
24
    },
25
    "order_id": "657434343",
26
    "notification_url": "http://merchant.com/notifications"
27
}
Copied!
Example Response​
1
{
2
    "id": "D-4-80ca7fbd-67ad-444a-aa88-791ca4a0c2b2",
3
    "amount": 120,
4
    "currency": "USD",
5
    "payment_method_id": "CARD",
6
    "payment_method_type": "CARD",
7
    "payment_method_flow": "DIRECT",
8
    "country": "BR",
9
    "card": {
10
        "holder_name": "Thiago Gabriel",
11
        "expiration_month": 10,
12
        "expiration_year": 2040,
13
        "brand": "VI",
14
        "last4": "1111"
15
    },
16
    "created_date": "2018-12-26T20:28:47.000+0000",
17
    "approved_date": "2018-12-26T20:28:47.000+0000",
18
    "status": "PAID",
19
    "status_detail": "The payment was paid",
20
    "status_code": "200",
21
    "order_id": "657434343",
22
    "notification_url": "http://merchant.com/notifications"
23
}
Copied!
Other Card Payment Operations
​Authorization and Capture​
​Chargebacks​
​3D-Secure​
​Save Card on a Payment​
​Installments​