Saving Cards

post
Create a Card

https://api.dlocal.com/secure_cards
Stores a card's information on dLocal's servers, and returns a card_id, that can be used to make payments later on.
Request
Response
Body Parameters
country
required
string
Card's country
card
required
object
The Card Object
payer
required
object
The Payer Object
200: OK
Example Response
{
"card_id": "CV-af85ddba-f5f4-4644-b3fa-3c922e0687e9",
"holder_name": "Thiago Gabriel",
"expiration_month": 10,
"expiration_year": 2040,
"last4": "1111",
"brand": "VI"
}
400: Bad Request
Example Error Response.
{
“code” : 5001,
“message” : "Invalid parameter",
“param” : "card.number"
}

The Card Object

Argument

Type

Description

holder_name

String

Cardholder's full name. Required if token not present.

expiration_month

Integer

Number representing the card's expiration month (start in 1). Required if token not present.

expiration_year

Integer

Number representing the card's expiration year. Required if token not present.

number

String

The card number, as a string without any separators. Required if encrypted_data or token not present.

cvv

String

Credit card verification value. Required if encrypted_data or token not present.

encrypted_data

String

JWE encrypted params. Optional.

token

String

Temporary credit card token created using Smart Fields. Optional.

The Payer Object

Argument

Type

Description

name

String

Payer's name. Required.

document

String

Payer's document. Required.

email

String

Payer's email address. Optional.

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_cards

Example request body

{
"country": "BR",
"card": {
"holder_name": "Thiago Gabriel",
"expiration_month": 10,
"expiration_year": 2040,
"number": "4111111111111111",
"cvv": "123"
},
"payer": {
"name": "Luis Gabriel",
"document": "53033315550",
"email": "luis@email.com"
}
}

Save a Card on a Payment

You can save a card while making a Payment / Authorization. To do so, simple add a "save" : true parameter in the card object of the request.

If the operation was successful (eg: Payment is PAID, or Authorization is AUTHORIZED) The response will include the card_id that you can use for further payments. If the operation failed (eg: Payment REJECTED), no card_id will be generated.

Example Request

Example Request
Example Response

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,
"save" : true
},
"order_id": "657434343",
"notification_url": "http://merchant.com/notifications"
}

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",
"card_id" : "CID-124c18a5-874d-4982-89d7-b9c256e647b5"
},
"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"
}

get
Retrieve a Card

https://api.dlocal.com/cards/{card_id}
Retrieve information about a saved card.
Request
Response
Path Parameters
card_id
required
string
The card id received when saving the card.
200: OK
{
"card_id": "CV-af85ddba-f5f4-4644-b3fa-3c922e0687e9",
"holder_name": "Thiago Gabriel",
"expiration_month": 10,
"expiration_year": 2040,
"last4": "1111",
"brand": "VI"
}

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_cards

delete
Delete a card

https://api.dlocal.com/secure_cards/{card_id}
Unlink a card_id so that it cannot be use any further.
Request
Response
Path Parameters
card_id
optional
string
The card id received when saving the card
200: OK
{
"card_id" : "CV-af85ddba-f5f4-4644-b3fa-3c922e0687e9",

"deleted" : true
}

Example Request

curl -X DELETE \
-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_cards/CV-af85ddba-f5f4-4644-b3fa-3c922e0687e9

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.

400 Bad Request

5000

Invalid request.

5001

Invalid parameter.

5003

Country not supported.

5005

User unauthorized due to cadastral situation.

5008

Token not found or inactive.

5015

The card was rejected by the bank.