Skip to main content

dLocal

Overview​

Gateway Website: https://www.dlocal.com/
Developer Documentation: https://docs.dlocal.com/reference/payins-security
Default Currency: USD

Request Objects: BillingAddress, CreditCard, OrderInfo, SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
This implementation of dLocal forwards requests to the below endpoints.

ActionProductionSandbox
Card Authorize, Card Purchasehttps://api.dlocal.com/secure_paymentshttps://sandbox.dlocal.com/secure_payments
Card Capturehttps://api.dlocal.com/paymentshttps://sandbox.dlocal.com/payments
Card Refundhttps://api.dlocal.com/refundshttps://sandbox.dlocal.com/refunds
Card Voidhttps://api.dlocal.com/payments/[transactionId]/cancelhttps://sandbox.dlocal.com/payments/[transactionId]/cancel

Supported Request Parameters​

Field NameTypedLocal MappingNotes
gatewaystringN/AdLocal
usernamestringx-login headerSee dLocal's documentation
passwordstringx-trans-key headerSee dLocal's documentation
privateKeystringsecret keySee dLocal's documentation
idempotencyKeystringx-idempotency-key headerSee dLocal's documentation
amountnumericamountThe amount in minor units. For example, 2000 means USD 20.00. Max length: 12 characters.
billingAddress.​address1stringpayer.​address.​streetUser’s address street. Required in India and South Africa.
billingAddress.​address2stringpayer.​address.​numberUser’s address number. Required in India and South Africa.
billingAddress.​citystringpayer.​address.​cityThe name of the city.
billingAddress.​countrystringcountryThree-Character Country Code ISO country code. TokenEx will convert to ISO 3166-1 alpha-2 code.
billingAddress.​fullNamestringpayer.​nameUser's full name.
billingAddress.​statestringpayer.​address.​stateUser's address state. Required in South Africa.
billingAddress.​zipstringpayer.​address.​zip_codeUser’s address zip_code. Required in South Africa.
billingAddress.​emailstringpayer.​emailUser’s email address.
billingAddress.​phonestringpayer.​phoneUser’s phone. Mandatory for Wallets in India. Also required for fraud prevention.
creditCard.​CVVstringcard.​cvvThe card verification code.
creditCard.​descriptorstringcard.​descriptorDynamic descriptor passthrough.
creditCard.​expMonthnumericcard.​expiration_monthThe customer’s credit card expiration month. Format: 2 digits, zero-padded for single digits. Example: 03 = March, 11 = November
creditCard.​expYearnumericcard.​expiration_yearThe customer’s credit card expiration year. Format: 4 digits. For example: 2030
creditCard.​fullNamestringcard.​holder_nameThe name of the cardholder, as printed on the card.
creditCard.​numberstringcard.​numberCard number or TokenEx Token - TokenEx will replace the Token with the Detokenized number
currencyCodestringcurrencyThe three-character ISO currency code. Alpha-3 ISO currency code
customerIpAddressstringpayer.​ipUser's IP address. Required for fraud prevention.
orderInfo.​customerIdstringpayer.​user_referenceUnique user id at the merchant side. Required for fraud prevention.
orderInfo.​orderIdstringorder_idID given by the merchant in their system. Will show up in gatewayResponse.merchantReferenceId
orderInfo.​originalOrderIdstringoriginal_order_idFor payment retries. ID given by the merchant in their system for the original transaction that was rejected and needs to be retried
softDescriptors.​merchantCategoryCodestringcard.​descriptorSee SoftDescriptors callout below.
softDescriptors.​merchantCitystringcard.​descriptorSee SoftDescriptors callout below.
softDescriptors.​merchantEmailstringcard.​descriptorSee SoftDescriptors callout below.
softDescriptors.​merchantPhonestringcard.​descriptorSee SoftDescriptors callout below.
softDescriptors.​merchantUrlstringcard.​descriptorSee SoftDescriptors callout below.
storedCredentials.​credentialStoredboolcard.​stored_credential_usageSee usage in The Basics - Stored Credentials. True = USED. False = FIRST.

See dLocal's documentation
storedCredentials.​transactionTypestringcard.​stored_credential_typeValid values:
"recurring" = "SUBSCRIPTION",
"installment" = "INSTALLMENTS",
"unscheduled" = "UNSCHEDULED_CARD_ON_FILE".
any other string value will be upper cased and forwarded.

See dLocal's documentation
threeDSecure.​CAVVstringthree_dsecure.​cavvThe cardholder authentication value for the 3D Secure authentication session. The returned value is a base64-encoded 20-byte array.
threeDSecure.​DSTransIdstringthree_dsecure.​ds_transaction_idThe transaction identifier assigned by the 3DS Server for v2 authentication (36 characters, commonly in UUID format).
threeDSecure.​ECIstringthree_dsecure.​eciThe electronic commerce indicator.
threeDSecure.​ThreeDSecureVersionstringthree_dsecure.​three_dsecure_version"2.1.0" or "2.2.0"
threeDSecure.​EnrollmentResponsestringthree_dsecure.​enrollment_responseSee dLocal's documentation
threeDSecure.​AuthenticationResponsestringthree_dsecure.​authentication_responseSee dLocal's documentation
documentstringpayer.​documentUser’s personal identification number.
descriptionstringdescriptionPayment description.
notificationUrlstringnotification_urlURL where dLocal will send notifications associated to changes to this payment.
Soft Descriptors - Descriptor Construction

dLocal API's card.descriptor is a free-text field. If values are sent in the TokenEx softDescriptor fields, they will be concatenated and space separated in the forwarded request. Alternatively, use the descriptor passthrough in creditCard.

Example usage:

"softDescriptors": {
  "merchantName":"Bob Smalls",
  "merchantPhone": "(876) 613-1270 x38785",
  "merchantEmail":"[email protected]",
  "merchantUrl": "http://merchant.com"
}

Forwarded output: Bob Smalls (876) 613-1270 x38785 [email protected] http://merchant.com

Example Requests​

{
  "amount": 1000,
  "gateway": "dLocal",
  "username": "<Your dLocal x-login header>",
  "password": "<Your dLocal x-trans-key header>",
  "privateKey": "<Your dLocal secret key>",
  "currencyCode": "USD",
  "document": "12345678",
  "creditCard": {
    "brand": "Visa",
    "number": "4111111111111111",
    "expMonth": 6,
    "expYear": 2026,
    "fullName": "Thiago Gabriel",
    "cvv": "123"
  },
  "billingAddress": {
    "phone": "555-555-5555",
    "email": "[email protected]",
    "fullName": "Thiago Gabriel",
    "address1": "Servidao B-1",
    "address2": "1106",
    "city": "Volta Redonda",
    "state": "Rio de Janeiro",
    "zip": "27275-595",
    "country": "BRA"
  },
  "orderInfo": {
    "orderId": "fd14dfcc-b545-4695-9fbd-73a759f8efa5"
  }
}

Gateway Response Parameters​

Field NameTypedLocal MappingNotes
Approvedbooleanstatus and statusCodeTrue if the status is PENDING, PAID, SUCCESS, CANCELLED, AUTHORIZED, or VERIFIED and its respective statusCode is returned.
ProviderTransactionCodestringidUnique Identifier returned by dLocal for the transaction.
TokenExTransactionCodestringid and currencyBase64 encoded id;currency from rawResponse
MerchantReferenceIdstringorderIdValue sent in request's 'OrderInfo.OrderId' parameter
GatewayErrorsobject array--See GatewayErrors callout below.
GatewayErrors[0].Codestringcode or statusCodeSee GatewayErrors callout below.
GatewayErrors[0].Messagestringmessage or statusDetailSee GatewayErrors callout below.
GatewayErrors[0].SourcestringN/APossible values: Unspecified, Gateway, Processor, TokenEx.
GatewayErrors Code, Message, and Source assignment

There are three non-overlapping flows which will add an entry to GatewayErrors.

  1. If the response from dLocal is formatted in an unanticipated way, the following error will be returned.
    Parsing Error
    {
      "code": "8012",
      "message": "Could not parse gateway response",
      "source": "TokenEx"
    }
  2. When the rawResponse from dLocal contains a status of "REJECTED" and a statusCode between 300 and 399 (inclusive), the gatewayErrors[0].code is mapped to statusCode, thegatewayErrors[0].message is mapped to statusDetail, and the gatewayErrors[0].source will be "Processor".
    dLocal - Payment Status Codes
    dLocal - Refund Status Codes
  3. When the rawResponse from dLocal does not contain a status matching PENDING, PAID, SUCCESS, CANCELLED, AUTHORIZED, VERIFIED, or REJECTED or the statusCode is not present or does not match the respective status' code as defined in the two links above, the gatewayErrors[0].code is mapped to code, thegatewayErrors[0].message is mapped to message, and the gatewayErrors[0].source will be "Gateway".
    dLocal - Payments Errors
    dLocal - Refunds Errors

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "{\"id\":\"T-15078-74cb33cb-b869-45ad-adf6-ddf60761123a\",\"amount\":10.00,\"currency\":\"ARS\",\"payment_method_id\":\"CARD\",\"payment_method_type\":\"CARD\",\"payment_method_flow\":\"DIRECT\",\"country\":\"AR\",\"card\":{\"holder_name\":\"John Doe\",\"expiration_month\":6,\"expiration_year\":2026,\"brand\":\"VI\",\"last4\":\"1111\",\"installments_responsible\":\"customer\",\"verify\":false},\"three_dsecure\":{},\"created_date\":\"2023-10-11T21:21:25.000+0000\",\"approved_date\":\"2023-10-11T21:21:27.000+0000\",\"status\":\"AUTHORIZED\",\"status_detail\":\"The payment was authorized.\",\"status_code\":\"600\",\"order_id\":\"859b6bca-1465-44e4-8b5a-7de3e9f62adb\"}",
    "gatewayErrors": [],
    "tokenExTransactionCode": "VC0xNTA3OC03NGNiMzNjYi1iODY5LTQ1YWQtYWRmNi1kZGY2MDc2MTEyM2E7QVJT",
    "approvalCode": "",
    "providerTransactionCode": "T-15078-74cb33cb-b869-45ad-adf6-ddf60761123a",
    "approved": true,
    "merchantReferenceId": "859b6bca-1465-44e4-8b5a-7de3e9f62adb"
  },
  "referenceNumber": "023101116212247171683",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on