dLocal

📘

To start accepting payments via dLocal, please contact your customer success manager.

Our partnership with dLocal allows you to accept payments from customers across Latin America using both international and local card schemes.

A dLocal payment request uses the same endpoint as a standard card payment, and is structured similarly, but there are a few important differences.

For Latin American countries, merchants are required to provide their customers' identification numbers along with all authorization requests. Depending on the customer's country of residence, a differing type of identification number might be required, so a customer-specific country field needs to be sent in the authorization request.

Also, the billing country associated with the payer's data may not be the same as the customer's country of residence (if, for instance, the payer is different from the customer). For this reason, a specific field for the merchant customer's country of residence needs to be specified explicitly.

• Make a payment using an international card scheme
• Make a payment using a local card scheme

International card schemes payment request

The request

Use the details below to set up your request.

Endpoints

Live

POSThttps://api.checkout.com/payments

🚧

This endpoint is only available in a live environment.

Header parameters

Body parameters

Request example

{
  "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": "12",
    "expiry_year": "25",
    "cvv": "100"
  },
  "reference" : "668",
  "capture": false,
  "amount": 10000,
  "currency": "MXN",
  "billing_descriptor": {
    "name": "dynamic_descriptor",
    "city": "GOTHAM"
  },
  "processing": {
    "dlocal": {
      "country": "MX",
      "payer": {
        "document": "SomeDocumentId",
        "name": "John Doe",
        "email": "[email protected]"
      },
      "installments": {
        "count": "3"
      }
    }
  }
}

The response

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

Response example

{
  "id": "pay_z7mylvkcalbedkvjxidz2wt7ea",
  "action_id": "act_z7mylvkcalbedkvjxidz2wt7ea",
  "amount": 10000,
  "currency": "MXN",
  "approved": true,
  "status": "Authorized",
  "auth_code": "213348",
  "eci": "05",
  "scheme_id": "923918049434504",
  "response_code": "10000",
  "response_summary": "Approved",
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_rcqlc7uaqxcelg6j4ya7ww7vme",
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2025,
    "scheme": "Visa",
    "last4": "4242",
    "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
    "bin": "424242",
    "card_type": "Credit",
    "card_category": "Consumer",
    "issuer": "JPMORGAN CHASE BANK NA",
    "issuer_country": "US",
    "product_id": "A",
    "product_type": "Visa Traditional",
    "avs_check": "S",
    "cvv_check": "Y",
    "payouts": true,
    "fast_funds": "d"
  },
  "customer": {
    "id": "cus_givlst32wmsebgwmar3ozgqlj4"
  },
  "processed_on": "2019-11-05T10:02:30Z",
  "processing": {
    "acquirer_transaction_id": "4616546139",
    "retrieval_reference_number": "914387252893"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea/actions"
    },
    "capture": {
      "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea/captures"
    },
    "void": {
      "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea/voids"
    }
  }
}

Local card schemes payment request

The request

Make a payment request using the same endpoint and parameters as above, with two differences:

• Set source.type to dlocal.
• Latin American card numbers (source.number) are between 12-19 characters in length.

🚧

Card number validation
Because Latin American card numbers vary in length and structure, they cannot be validated with a Luhn check. You should disable this check when making a dlocal payment request to avoid the card number being flagged as invalid to the customer and to prevent the request from being rejected.

Request example

{
  "source": {
    "type": "dlocal",
    "number": "6362970000457013",
    "expiry_month": "04",
    "expiry_year": "22",
    "cvv": "551"
  },
  "reference" : "668",
  "capture": false,
  "amount": 100,
  "currency": "USD",
  "billing_descriptor": {
    "name": "dynamic_descriptor",
    "city": "GOTHAM"
  },
  "processing": {
    "dlocal": {
      "country": "BR",
      "payer": {
        "document": "53033315550",
        "name": "John Doe",
        "email": "[email protected]"
      },
      "installments": {
        "count": 4
      }
    }
  }
}

Pay in installments

📘

Paying in installments works with both international and local card schemes.

Paying in installments is a popular way of paying by credit card in Latin America. It allows customers to receive the goods or services straight away, but spread the cost of the purchase over several months.

When a customer pays via an installment plan, the purchase is split into multiple smaller payments, or installments. The first payment is charged to the customer's card immediately, and subsequent installments are charged every 30 days until their purchase has been fully paid.

To make an installment payment, include the processing.dlocal.installments object in your request, and set the number of payments to be made each year with the processing.dlocal.installments.count field.

Number of payments per year

The number of payments a customer can make per year in an installment plan varies by country:

• In Argentina, Brazil, Chile, Colombia and Peru, the customer can make 1 to 12 payments a year.
• In Mexico, the customer can make either 3, 6, 9 or 12 payments a year.

Fees

The customer will be charged a fee by their bank for making payments via an installment plan, and you must make these fees clear to your customers.

These fees change frequently, so you should request the latest fee tables from dLocal regularly to ensure your customers are kept up to date.

👍

Displaying installment fees

Use the fee tables from dLocal to build a user interface that shows the customer:

• The fees per installment payment, using the formula (order amount + order amount * interest) / number of installments.
• The total cost of the plan, including the fees, using the formula purchase amount + (purchase amount * interest fee).

🚧

When accepting payments in installments in Latin American countries, you are legally required to show the customer the fees for each individual installment as well as the total cost of the plan.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].