Documentation
Documentation
OUR SOLUTION
COUNTRIES
CUSTOMERS
CONTACT US
Documentation
Documentation
dLocal Documentation
Solutions
Payins
Payouts
API Documentation
Payins API Reference
Security
Payment Methods
Payments
Credit Card Payments
Authorization and Capture
Chargebacks
3D-Secure
Saving Cards
Installments
Cash (Ticket) Payments
Bank Transfer Payments
PayLater Payments
Wallet Payments
PIX Payments
Mobile Money Payments
Refunds
Orders
Fraud Prevention
Currency Exchange
Country Reference
Payouts API Reference
Products
Smart Fields
GUIDES
API integration guide
PCI Compliance
Google Pay™
Shopify setup
Other
Changelog
Status Page
Chinese 中文文档
Powered by GitBook

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 flow.
additional_risk_data
optional
object
Additional information for fraud prevention, see the Fraud Prevention - Additional Risk Data Object documentation.
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

Previous
Payments
Next
Authorization and Capture
Last updated 2 days ago
Contents
post
Create a Card Payment
Pay with Card information
Pay with Smart Fields
Pay with Saved Card
Other Card Payment Operations