Skip to content

dLocal

Last updated: April 29, 2022

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

Information

To start accepting payments via dLocal, please contact your Customer Success Manager.

Overview

Warning

Local card schemes are not supported by our Frames solution. Merchants must be PCI-SAQ D compliant to use them, and must provide the card information directly in the payment request.

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.

International card schemes payment request

The request

Use the details below to set up your request.

Endpoint

    post

    https://api.checkout.com/payments

    Request example

    Note

    When testing dLocal payment methods in sandbox, make sure you include the name and email fields in the processing object. See them in the processing object in the following example.

    1
    {
    2
          "source": {
    3
            "type": "card",
    4
            "number": "4242424242424242",
    5
            "expiry_month": "12",
    6
            "expiry_year": "25",
    7
            "cvv": "100"
    8
          },
    9
          "reference" : "668",
    10
          "capture": false,
    11
          "amount": 10000,
    12
          "currency": "MXN",
    13
          "billing_descriptor": {
    14
            "name": "dynamic_descriptor",
    15
            "city": "GOTHAM"
    16
          },
    17
          "processing": {
    18
            "dlocal": {
    19
              "country": "MX",
    20
              "payer": {
    21
                "document": "SomeDocumentId",
    22
                "name": "John Doe",
    23
                "email": "john@doe.com"
    24
              },
    25
              "installments": {
    26
                "count": "3"
    27
              }
    28
            }
    29
          }
    30
        }

    Response example

    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.

    1
    {
    2
          "id": "pay_z7mylvkcalbedkvjxidz2wt7ea",
    3
          "action_id": "act_z7mylvkcalbedkvjxidz2wt7ea",
    4
          "amount": 10000,
    5
          "currency": "MXN",
    6
          "approved": true,
    7
          "status": "Authorized",
    8
          "auth_code": "213348",
    9
          "eci": "05",
    10
          "scheme_id": "923918049434504",
    11
          "response_code": "10000",
    12
          "response_summary": "Approved",
    13
          "risk": {
    14
            "flagged": false
    15
          },
    16
          "source": {
    17
            "id": "src_rcqlc7uaqxcelg6j4ya7ww7vme",
    18
            "type": "card",
    19
            "expiry_month": 12,
    20
            "expiry_year": 2025,
    21
            "scheme": "Visa",
    22
            "last4": "4242",
    23
            "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
    24
            "bin": "424242",
    25
            "card_type": "Credit",
    26
            "card_category": "Consumer",
    27
            "issuer": "JPMORGAN CHASE BANK NA",
    28
            "issuer_country": "US",
    29
            "product_id": "A",
    30
            "product_type": "Visa Traditional",
    31
            "avs_check": "S",
    32
            "cvv_check": "Y",
    33
            "payouts": true,
    34
            "fast_funds": "d"
    35
          },
    36
          "customer": {
    37
            "id": "cus_givlst32wmsebgwmar3ozgqlj4"
    38
          },
    39
          "processed_on": "2019-11-05T10:02:30Z",
    40
          "processing": {
    41
            "acquirer_transaction_id": "4616546139",
    42
            "retrieval_reference_number": "914387252893"
    43
          },
    44
          "_links": {
    45
            "self": {
    46
              "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea"
    47
            },
    48
            "actions": {
    49
              "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea/actions"
    50
            },
    51
            "capture": {
    52
              "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea/captures"
    53
            },
    54
            "void": {
    55
              "href": "https://api.sandbox.checkout.com/payments/pay_z7mylvkcalbedkvjxidz2wt7ea/voids"
    56
            }
    57
          }
    58
        }

    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

    1
    {
    2
          "source": {
    3
            "type": "dlocal",
    4
            "number": "6362970000457013",
    5
            "expiry_month": "04",
    6
            "expiry_year": "22",
    7
            "cvv": "551"
    8
          },
    9
          "reference" : "668",
    10
          "capture": false,
    11
          "amount": 100,
    12
          "currency": "USD",
    13
          "billing_descriptor": {
    14
            "name": "dynamic_descriptor",
    15
            "city": "GOTHAM"
    16
          },
    17
          "processing": {
    18
            "dlocal": {
    19
              "country": "BR",
    20
              "payer": {
    21
                "document": "53033315550",
    22
                "name": "John Doe",
    23
                "email": "john@doe.com"
    24
              },
    25
              "installments": {
    26
                "count": 4
    27
              }
    28
            }
    29
          }
    30
        }

    Pay in installments

    Information

    Paying in installments works with both international and local card schemes, provided the card was issued by a local bank.

    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).

    Note

    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.

    On this page

    Overview
    International card schemes payment request
    Local card schemes payment request
    Pay in installments