HomeGuidesAPI ReferenceStatus Page
API Reference

The Card Object

For credit card payments you can use the card information only if your 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

PropertyTypeDescription
holder_nameStringCardholder's full name. Required if token or card_id not present.
expiration_monthIntegerTwo digit number representing the card's expiration month. Required if token or card_id are not present.
expiration_yearIntegerFour digit number representing the card's expiration year. Required if token or card_id are not present.
numberStringThe card number, as a string without any separators. Required if encrypted_data, token or card_id not present.
cvv StringCredit card verification value. Optional. Required for India.
encrypted_dataStringJWE encrypted params.
token StringTemporary credit card token securely created using Smart Fields.
cvv_tokenStringTemporary CVV token securely created using the CVV -only Smart Field
card_idStringCredit card ID returned by the Create a Card endpoint.
installmentsStringNumber of installments. Default 1. ​
installments_idStringInstallments ID of an installment plan.
descriptorStringDynamic Descriptor.
captureBooleanWhether or not to immediately capture the charge. When false, the charge issues an authorization and will need to be captured later. Default TRUE. ​
saveBooleanWhether or not to save the card for future payments. The response will include a card_id. Learn more.
stored_credential_typeStringUse this field to store credentials for future payments.

Possible values:
* CARD_ON_FILE
* SUBSCRIPTION
* UNSCHEDULED_CARD_ON_FILE
* INSTALLMENTS
* NO_SHOW
* DELAYED_CHARGES
* REAUTHORIZATION
* RESUBMISSION

See all the information in the Merchant Initiated Transactions page.
stored_credential_usageStringIndicates if this is the first time the token is used (an initial payment) or if the token has already been used for a previous payment (subsequent payment).

Possible values:
* FIRST
* USED

See all the information in the Merchant Initiated Transactions page.

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