Developers
documentation

Simple API integration

Full API

- Introduction

This document covers the basic concepts of the payment transaction types and the technical details of the dLocal - Credit Card API. It contains functional examples of the requests and important observations to be taken into account during integration.

- Considerations

Technical details

  • The merchant needs to have a PCI DSS Compliance certificate.
  • Communication between Merchant and dLocal should be made by POST.
  • The protocol used is purely HTTPS.
  • Sensible information is sent server to server.
  • The return format of the functions is json.

Security details

  • Credentials must be used in all communications.
  • Both parties must use an HMAC-SHA-256 (RFC 2104) code to verify the integrity of the information received from each side.
  • HMAC‐SHA‐256 code (32 bytes) is generated using a key provided by dLocal. This code is converted to string as a hexadecimal representation of the code (64 upper chars).
  • All communications between Merchant and dLocal should be made exclusively through registered IPs on both sides.

- Environments

Your account is associated with two different environments: Sandbox and Live. Base URL for communication:

Sandbox

Test environment available for integration development and testing which simulates the requests and transactions available in the platform. In the test environment no transactions will actually be processed.

https://sandbox.dlocal.com/api_curl/cc/ (for transaction functions)
https://sandbox.dlocal.com/api_curl/query (for status functions)

Live - Production environment


https://cc.dlocal.com/api_curl/cc/ (for transaction functions)
https://api.dlocal.com/api_curl/query/ (for status functions)

- Function: Save

The Save Card function allows the Merchant to securely store the customer's credit card information for future or recurrent purchases. It checks if the credit card used is valid and creates a preapproval that allows the Merchant to debit automatically from the user credit card. The Merchant receives a unique token that could be used when sending sale transactions. Also, the Merchant can make a sale transaction by sending all credit card information again but whithout CVV.

POST:

https://cc.dlocal.com/api_curl/cc/save

Mandatory parameters

Field Format Description Example
x_login String (length: 32 chars) Your merchant ID in dLocal AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal D23weF2f4g 1
x_version String (Format: X.Y) API version 4.0
x_country String (max. length: 2 chars) User’s country. ISO 3166-1 alpha-2 codes BR
x_cpf Number (max. 30 digits) User’s personal identification number: CPF or CNPJ for Brazil, DNI for Argentina and ID for other countries. 123456789
x_name String User’s full name. Ivan Lolivier
x_email String User’s email address. [email protected]
cc_number Number (16 digits) User's credit card number 4111111111111111
cc_exp_month Number (2 digits) Credit card expiration month 02
cc_exp_year Number (4 digits) Credit card expiration year 2018
cc_cvv Number (max length: 4 digits) Credit card verification value 425
control String Control string JASG44DNNGIJ34IJ34OKOEWJNCV874Y4UY 2

1 - x_login and x_trans_key are your credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.
2 - Control string

  • $secretkey – secret key given to the merchant
  • $email– user’s email address (x_email)
  • $number–credit card number (cc_number)
  • $cvv–credit card cvv (cc_cvv)
  • $month – credit card expiration month (cc_exp_month)
  • $year – credit card expiration year (cc_exp_year)
  • $cpf – user’s document (x_cpf)
  • $country – country code (x_country)
 $message = $email.$number.$month.$cvv.$year.$cpf.$country;
           $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

Optional parameters

Field Format Description Example
x_bank String (max. 3 digits) Payment method code. See payment method codes. VI
cc_issuer Number Credit card issuer bank. See issuer bank codes. 105
x_iduser Decimal (max. 20 chars) Unique user id at the merchant side user 123
x_bdate String User’s date of birth (Format: YYYYMMDD) 19850812
x_ip String Buyer's IP address 200.11.222.3
x_address String User’s address 1225 Bonavita St.
x_zip String User’s zip/postal code 11300
x_city String User’s city Sao Paulo
x_state String (max. 3 chars) User’s state. Brazilian 2 letter format MO
x_phone String User’s phone number 099123456
x_merchant_id String Sub merchant identifier (only for PSPs). List of sub- merchants must be provided by PSP 1
x_description String (max. length: 200 chars) A description about your service Sony
x_device_id String Buyer's device Id. See Device id. 54hj4h5jh46hasjd
x_sub_code Integer To be provided if the merchant provided for the transaction is a sub-merchant 123456

Response

This function, if successful, returns a json with the following parameters:

Field Description
status OK
desc Response description message
control Control string 1
cc_token The token associated with the customer card. This information should be stored for future uses.

1 - Control signature

  • $secretkey – secret key given to the merchant
  • $token – credit card token (cc_token)
$message = $token;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Function: Sale

This function performs a one-shot or recurrent payment.
Recurrent payments have two options:

  • Send the token obtained in the save function.
  • Send card data without cvv (recurrent without token).

A Sale transaction checks if the card holder has sufficient funds for that purchase and if the transaction has passed the Acquirer's and Bank's risk assessment process. If approved, the transaction is completed.

POST:

https://cc.dlocal.com/api_curl/cc/sale

Mandatory Parameters

Field Format Description One-Shot / Recurrent Example
x_login String (length: 32 chars) Your merchant ID in dLocal Both AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal Both D23weF2f4g 1
x_version String (Format: X.Y) API version Both 4.0
x_invoice String (max. lenght 200 chars) Unique transaction identification at the merchant site. Both Invoice1234
x_amount Decimal (max. 2 decimal numbers) Transaction amount (in the currency entered in the field “x_currency”) Both 100.95
x_currency String (length: 3 chars) Currency code Both BRL
x_description String (max. length: 200 chars) A description of the payment Both Product 123
x_device_id String Buyer's device Id. See Device id. Both 54hj4h5jh46hasjd
x_country String (max. length: 2 chars) User’s country. in ISO 3166-1 alpha-2 codes One-Shot / Recurrent without token BR
x_cpf Number (max. 30 digits) User’s personal identification number: CPF or CNPJ for Brazil, DNI for Argentina and ID for other countries. Both 123456789
x_name String User’s full name. Both Ivan Lolivier
x_email String User’s email address. Both [email protected]
cc_number Number (16 digits) User's credit card number One-Shot / Recurrent without token 4111111111111111
cc_exp_month Number (2 digits) Credit card expiration month One-Shot / Recurrent without token 02
cc_exp_year Number (4 digits) Credit card expiration year One-Shot / Recurrent without token 2018
cc_cvv Number (max length: 4 digits) Credit card verification value One-shot 425
cc_token String Token obtained in Save function Recurrent with token 1aj2l3g4gj4fh5d5hh6d605
control String Control string Both JASG44DNNGIJ34IJ34OKOEWJNCV874Y4UY 2

1 - x_login and x_trans_key are your credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.

2 -Control string

  • $secretkey – secret key given to the merchant
  • $invoice– unique transaction ID at merchant (x_invoice)
  • $amount–payment amount (x_amount)
  • $currency–payment currency (x_currency)
  • $email– user’s email address (x_email)
  • $number–credit card number (cc_number)
  • $cvv–credit card cvv (cc_cvv)
  • $month – credit card expiration month (cc_exp_month)
  • $year – credit card expiration year (cc_exp_year)
  • $cpf – user’s document (x_cpf)
  • $country – country code (x_country)
  • $token – credit card token (cc_token)

If some of the above parameters are not sent in the request, they must not be considered for the control string.

$message = $invoice.$amount.$currency.$email.$number.$month.$cvv.$year.$cpf.$country.$token;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

Optional parameters

Field Format Description One-Shot / Recurrent Example Default
x_bank String (max. 3 digits) Payment method code. See payment method codes. One-Shot / Recurrent without token (only Mexico) VI
cc_issuer Number Credit card issuer bank. See issuer bank codes. One-Shot / Recurrent without token 105
cc_installments Number Number of installments One-Shot 3 1
cc_descriptor String (max: 13 char) Dynamic Descriptor Both AP Payment
x_ip String Buyer's IP address Both 200.11.222.3
x_confirm String To be provided if the confirmation URL is different from the confirmation URL registered by the merchant. Both http://merchant/confirm
x_bdate String User’s date of birth (Format: YYYYMMDD) One-Shot 19850812
x_iduser Decimal (max. 20 chars) Unique user id at the merchant side One-Shot user 123
x_address String User’s address One-Shot 1225 Bonavita St.
x_zip String User’s zip/postal code One-Shot 11300
x_city String User’s city One-Shot Sao Paulo
x_state String (max. 3 chars) User’s state. Brazilian 2 letter format One-Shot MO
x_phone String User’s phone number One-Shot 099123456
x_sub_code Integer To be provided if the merchant provided for the transaction is a sub-merchant Both 1

Response

This function, if successful, returns a json with the following parameters:

Field Description
status OK
desc Response description message
control Control string 1
result Transaction result. See possible results.
x_invoice Unique transaction ID number at the merchant
x_document Unique transaction ID number at dLocal. This information should be stored for future use.
x_currency Currency code
x_amount Transaction amount (in the currency entered in the field “x_currency”).
x_amount_paid The amount finally charged to the user, in local currency. It includes finance charges (if applies).
cc_descriptor The transaction descriptor that will appear in the user’s statement
x_description The description of the payment
cc_token Token obtained in Save function
x_iduser Unique user id at the merchant side

1 - Control signature

  • $secretkey – secret key given to the merchant
  • $result – transaction result code
  • $amount – payment amount (x_amount)
  • $currency – payment currency (x_currency)
  • $invoice – unique transaction ID at merchant (x_invoice)
  • $document – unique transaction ID at dLocal (x_document)
$message = $result . $currency . $amount . $invoice . $document . $token;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Function: Auth

URL:

https://cc.dlocal.com/api_curl/cc/auth

An Auth transaction checks if the card holder has sufficient funds for that purchase and if the transaction has passed the Acquirer's and Bank's risk assessment process, if authorized the amount is reserved against credit card's available limit

1 - Request Parameters

The request parameters are the same as the Sale command.

2. Request Control String

The request control string is the same as the Sale command.

3. Response Parameters
Field Description
status OK
desc Response description message
control Control string (see section Auth Response Control String)
result Void result (see section Sale Result Codes)
x_invoice Unique transaction ID number at the merchant
x_auth_id Unique authorization ID number at dLocal. This information should be stored for future use.
x_amount The amount of the payment (same as received)
x_currency The currency code (same as received)
x_amount_paid The amount finally charged to the user, in local currency. It includes finance charges (if applies)
cc_descriptor The transaction descriptor that will appear in the user’s statement

Notes

If authorization is approved the result is authorized (11), otherwise it is rejected (8)

4. Auth Response Control String

For the following variables:

  • $secretkey – secret key given to the merchant
  • $result – transaction result code
  • $amount –payment amount (x_amount)
  • $currency–payment currency (x_currency)
  • $invoice – unique transaction ID at merchant (x_invoice)
  • $auth_id – unique transaction ID at dLocal (x_auth_id)

the control string is calculated, as follows:

 $message = $result . $currency . $amount . $invoice . $auth_id;
           $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretkey)));

- Function: Capture

URL:

https://cc.dlocal.com/api_curl/cc/capture

1 - Request Parameters
Field Format Mandatory/Optional Description Example
x_login String (length: 10 chars) M dLocal Merchant id AsGsd35Grf 1
x_trans_key String (length: 32 chars) M Your merchant password in dLocal platform D23weF2f4g 1
x_version String (format: X.Y) M API version 4.0
x_invoice String (max. 20 chars) M Transaction identification (at Merchant site) Invoice1234
x_amount Decimal (max 2 decimal numbers) O Amount to be captured (in the currency entered in the field “x_currency”) Must be equal or less than the captured amount.
If not included the capture is for the total authorized amount.
199.95
x_currency String (length: 3 chars) O/M (*1) Transaction currency in ISO 4217 (see http://en.wikipedia.org/wiki/ISO_4217) Each country accepts USD and local currency USD
control String (length: 40 chars) M Control string calculated by you JASGDNNGIJIJ34OKOEWJNCV874Y4UY 2
type One of these: xml, json O The return format of the function. One of these: xml or json Default: xml xml 2

Notes

  • (*1) Mandatory if amount is present
  • Capture must be done within the next 5 days Authorization has been made.
2. Request Control String

For the following variables:

  • $secretkey – secret key given to the merchant
  • $invoice– unique transaction ID at merchant (x_invoice)
  • $auth_id – unique transaction ID at dLocal (x_auth_id)
  • $amount–payment amount (x_amount, only present if parameter is sent)
  • $currency–payment currency (x_currency, only present if parameter is sent)

the control string is calculated, as follows:

 $message = $invoice . $auth_id . $amount . $currency;
           $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretkey)))
3. Response Parameters

This function, if successful, returns the following parameters:

Field Description
status OK
desc Response description message
control Control string (see section Capture Response Control String)
result Void result (see section Sale Result Codes)
x_invoice Unique transaction ID number at the merchant
x_auth_id Unique authorization ID number at dLocal. This information should be stored for future use.
x_amount The amount of the capture (same as request)
x_currency The currency code (same as request)
x_amount_captured The captured amount, in local currency
x_document Unique capture transaction ID number at dLocal

4. Capture Response Control String

For the following variables:

  • $secretkey – secret key given to the merchant
  • $result – refund result code
  • $amount –captured amount
  • $currency –currency code
  • $invoice – unique transaction ID at merchant
  • $document – unique transaction ID at dLocal
  • $auth_id – unique authorization ID at dLocal (x_auth_id)

the control string is calculated, as follows:

 $message = $result . $invoice . $document . $amount . $currency . $auth_id;
           $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretkey)));

- Function: Capture Refund

The refund command is the same as the one used for sale.

If x_document includes the x_document of the capture, the payment is refunded (capture must be approved)

- Function: Auth Void

URL:

https://cc.dlocal.com/api_curl/cc/cancel

1 - Request Parameters
Field Format Mandatory/Optional Description Example
x_login String (length: 10 chars) M dLocal Merchant id AsGsd35Grf 1
x_trans_key String (length: 32 chars) M Your merchant password in dLocal platform D23weF2f4g 1
x_version String (format: X.Y) M API version 4.0
x_invoice String (max. 20 chars) M Transaction identification (at Merchant site), returned in the original Auth transaction Invoice1234
x_auth_id String M Unique authorization Id Number by dLocal, returned in Auth command 199.95
control String (length: 40 chars) M Control string calculated by you JASGDNNGIJIJ34OKOEWJNCV874Y4UY 2
type One of these: xml, json O The return format of the function. One of these: xml or json Default: xml xml 2
2. Request Control String

For the following variables:

  • $secretkey – secret key given to the merchant
  • $invoice– unique transaction ID at merchant (x_invoice)
  • $auth_id – unique transaction ID at dLocal (x_auth_id)

the control string is calculated, as follows:

 $message = $invoice . $auth_id;
           $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretkey)));
3. Response Parameters

This function, if successful, returns the following parameters:

Field Description
status OK
desc Response description message
control Control string (see section Authorization Void Response Control String)
result Void result (see section Void result codes)
x_invoice Unique transaction ID number at the merchant
x_auth_id Unique authorization ID number at dLocal. This information should be stored for future use.
x_currency The currency code (same as request)
x_amount_canceled The canceled amount, in local currency

4. Auth Void Response Control String

For the following variables:

  • $secretkey – secret key given to the merchant
  • $result – refund result code
  • $invoice – unique transaction ID at merchant
  • $auth_id – unique authorization ID at dLocal (x_auth_id)

the control string is calculated, as follows:

 $message = $result . $invoice . $auth_id;
           $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $secretkey)));


Exception:
- Auth with capture approved → rejected

5. Auth Void Result codes
code Description
1 void approved
2 void rejected

- Function: Refund

A Refund is the reversal of a credit card transaction, where the funds are taken from the Merchant and given back to the Card Holder. A refund processing fee may apply. The refund to the user is always performed is local currency.

POST:

https://cc.dlocal.com/api_curl/cc/refund

Mandatory parameters

Field Format Description Example
x_login String (length: 32 chars) Your merchant ID in dLocal platform AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal platform D23weF2f4g 1
x_version String (format: X.Y) API version 4.0
x_invoice String (max. 20 chars) Transaction identification (at Merchant site), returned in the original Sale transaction Invoice1234
x_document String Unique transaction Id Number by dLocal, returned in Sale command 34587
control String (length: 40 chars) Control string calculated by you 4s5d4r42R5gJU23F45HQ1ad45Qdg3f5rTqF63g45 2

1 - x_login and x_trans_key are your credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.

2 - Control string

  • $secretkey – secret key given to the merchant
  • $invoice – unique transaction ID at merchant (x_invoice)
  • $document – unique transaction ID at dLocal (x_document)
  • $amount – payment amount (x_amount, only present if parameter is sent)
  • $currency – payment currency (x_currency, only present if parameter is sent)
$message = $document . $invoice . $amount . $currency;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

Optional Parameters

Field Format Description Example Default
x_amount Decimal (max. 2 decimal numbers) Amount to be refunded (in “x_currency”). It must be equal or less than the captured amount. 100.95 Total captured amount
x_currency String (length: 3 chars) Transaction currency in ISO 4217. Mandatory if amount is present EUR

Response

Field Description
Status OK
desc Response description message
control Control string 1
result Refund result. See possible results.
x_invoice Unique transaction ID number at the merchant
x_document Unique transaction ID number at dLocal
x_amount The amount of the refund (same as request)
x_currency The currency code (same as request)
x_amount_refunded The refunded amount, in local currency
x_refund Unique refund reference at dLocal

1 - Control signature

  • $secretkey – secret key given to the merchant
  • $result – refund result code
  • $amount –captured amount
  • $currency –currency code
  • $invoice – unique transaction ID at merchant
  • $document – unique transaction ID at dLocal
  • $refund – unique refund reference at dLocal
$message = $result . $invoice . $document . $amount . $currency . $refund;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Function: Payment status

The status of a transaction can be verified with:

POST or GET:

https://api.dlocal.com/api_curl/query/paystatus

Parameters

Field Format Description Example
x_login String (length: 32 chars) Your merchant ID in dLocal platform AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal platform D23weF2f4g 1
x_version String (format X.Y) API version 4.0
x_invoice String (max 20 chars) The unique transaction ID at merchant site Invoice1234
type (Optional) String (max 10 chars) Type of format for the response. The possible fields can be "string", "json" and "xml". By default is string. json

1 - x_login and x_trans_key are your Webpaystatus credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.

Response

Field Description
result Transaction result. See possible results.
x_iduser User’s unique ID at the Merchant's side
x_invoice Unique transaction ID number at Merchant's site
x_amount Original transaction amount
PT “0” for Production, “1” for Test
Sign Control string 1
x_document Unique transaction ID number at dLocal
x_bank Payment method code. See payment method codes.
x_payment_type Payment type code at dLocal (always 03)
x_bank_name Name of the payment method
x_currency Transaction currency code

1 - Control signature

  • $secretkey – secret key given to the merchant
  • $x_login – x_login given to the merchant (for status functions)
  • $result –transaction result
  • $amount –payment amount
  • $invoice – unique transaction ID at merchant
$message = $x_login . $result . $amount . $invoice;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Function: Refund status

The status of a refund can be verified with:

POST or GET:

https://api.dlocal.com/api_curl/query/refundstatus

Parameters

Field Format Description Example
x_login String (length: 32 chars) Your merchant ID in dLocal platform AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal platform D23weF2f4g 1
x_refund String (max. 20 chars) The unique refund reference at dLocal

1 - x_login and x_trans_key are your Webpaystatus credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.

Response

Field Description
result Refund result. See possible results.
x_invoice Unique transaction ID number at Merchant's site
x_document Unique transaction ID number at dLocal

- Function: Currency exchange

The currency exchange rate can be verified with:

POST or GET:

https://api.dlocal.com/api_curl/query/currencyexchange

Parameteres

Field Format Description Example
x_login String (length: 32 chars) Your merchant ID in dLocal platform AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal platform D23weF2f4g 1
x_country String (2 chars) The ISO code of the country whose currency exchange rate you want to know BR

1 - x_login and x_trans_key are your Webpaystatus credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.

Response

The response is a string with the price of 1 dollar in local currency. If we don't have the currency for that country we will return 0.

- Function: Installments (only one-shot)

The possible number of installments for each amount and its associated rate can be verified.

POST or GET:

https://api.dlocal.com/api_curl/query/installments

Parameters

Field Format Description Example
x_login String (length: 32 chars) Your merchant ID in dLocal platform AsGsd35Grf 1
x_trans_key String (length: 32 chars) Your merchant password in dLocal platform D23weF2f4g 1
x_country String (2 chars) The ISO code of the country whose currency exchange rate you want to know BR
x_bin Number BIN (Bank Identification Number) code. First 6 digits of card number 400344

1 - x_login and x_trans_key are your Webpaystatus credentials. Remember to find them in the panel, section Integration -> Credentials & Settings.

Response (array)

Field Description
installments Number of installments
installment_rate Instalment rate (charged to customer)
min_allowed_amount Minimum allowed amount (in local currency)

- Transaction asynchronous notification

The transaction status is usually final (Paid or Cancelled), but, some risky transactions need to pass though a fraud review process before a final status is decided. For those pending (7) transactions, the payment confirmation is sent asynchronously to the Merchant confirmation URL (x_confirm) by POST protocol, sending the following parameters:

Field Description
result Transaction result. See possible results.
x_invoice Unique transaction ID number at the merchant
x_iduser User’s unique ID at the merchant / account number
x_description Transaction description
x_document Unique transaction ID number at dLocal
x_bank Bank code
x_payment_type Payment type (always 03)
x_bank_name Payment method name
x_currency Transaction currency in ISO 4217
x_control Control string 1

1 - Control signature

  • $secretkey – secret key given to the merchant
  • $x_login – x_login given to the merchant
  • $result –transaction result
  • $amount –payment amount (x_amount)
  • $invoice – unique transaction ID at merchant (x_invoice)
$message = $x_login . $result . $amount . $invoice;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Refund asynchronous notification

If a refund is pending (result = 0), the refund confirmation is sent asynchronously to the previously registered Merchant refund confirmation URL by POST protocol, sending the following parameters:

Field Description
result Transaction result. See possible results.
x_refund Unique refund reference number at dLocal
x_invoice Unique transaction ID number at the merchant
x_document Unique transaction ID number at dLocal
amount The amount of the refund Decimal (max. 2 decimal numbers)
currency The currency code of the refund String (length: 3 chars)
amount_refunded The refunded amount Decimal (max. 2 decimal numbers)
x_control Control string 1

1- Control signature

  • $secretkey – secret key given to the merchant
  • $result –transaction result
  • $refund – unique refund ID at dLocal (x_refund)
  • $document – unique transaction ID at dLocal (x_document)
  • $invoice – unique transaction ID at merchant (x_invoice)
$message = $refund . $result . $invoice . $document;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Chargeback asynchronous notification

If a charge back was applied (requested by the user) a notification is sent to the merchant to the previously registered Merchant refund confirmation URL by POST protocol, sending the following parameters:

Field Description
result Transaction result. See possible results.
x_chargeback Unique charback reference number at dLocal
x_invoice Unique transaction ID number at the merchant
x_document Unique transaction ID number at dLocal
amount The amount of the chargeback Decimal (max. 2 decimal numbers)
currency The currency code of the chargeback String (length: 3 chars)
amount_chargedback The chargedback amount Decimal (max. 2 decimal numbers)
x_control Control string 1

1 -Control signature

  • $secretkey – secret key given to the merchant
  • $x_login – x_login given to the merchant
  • $result –transaction result
  • $chargeback – unique chargeback ID at dLocal (x_chargeback)
  • $document – unique transaction ID at dLocal (x_document)
  • $invoice – unique transaction ID at merchant (x_invoice)
$message = $result . $invoice . $document . $chargeback;
          $control = strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*',$secretkey)));

- Api Codes: Errors

{ 
            “status”:”ERROR”, 
            “desc”:”[Description of the error]”,
            “error_code”:”[Error code]” 
          }

References

Description Code range
Syntax validation in parameter/s 3xx
Merchant identification validation 4xx
Business logic validation 5xx
Semantic validation in parameter/s 6xx
Transactional error 7xx
External transactional error 8xx

Codes

Code Error message
300 Invalid params + [param name]
301 Empty params + [param name]
302 Invalid control string
303 Invalid request
401 Invalid credentials
402 Unregistered IP address
403 Merchant has no authorization to use this API
501 The user must be adult
502 User unauthorized
504 User unauthorized due to cadastral situation
506 Payment method not found
507 Country not supported
508 User limit exceeded
510 Invalid transaction status
511 Amount exceeded
512 Email associated with another country
514 Insufficient funds
601 Currency not allowed for this country
603 Token not found or inactive
604 Credit card not found
605 Mismatch credit card – user data
606 Transaction not found
704 Could not process transaction
705 Could not communicate with acquirer
800 Rejected by bank
801 Pending for contingency
802 Rejected due to card blacklisted
803 Rejected due insufficient amount
804 Rejected due bad + [param name]
805 Rejected due max attempts reached
806 User must call bank for authorize
807 Rejected due duplicated payment
808 Rejected due credit card disabled
809 Rejected due score validation

- Api Codes: Sale result codes

code Description
6 Invalid transaction
7 Transaction pending
8 Transaction rejected (final status)
9 Amount paid. Transaction successfully concluded (final status)
11 Authorized (only applicable for auth function)

- Api Codes: Refund / Chargeback result codes

code Description
0 Refund / chargeback pending
1 Amount refunded/ chargebacked successfully (final status)
2 Refund/chargeback cancelled / reimbursed (final status)
3 Refund failed

- Api codes: Payment method codes

The payment method codes (x_bank) are shown below:

code Description Countries
VI Visa AR, BR, CL, CO, IN, MA, MX, PE, TR, UY
MC Mastercard AR, BR, CL, CO, IN, MA, MX, TR, UY
AE American express AR, BR, CL, CO, IN, MX, TR
DC Diners AR, BR, CL, CO, IN
VD Visa debit AR, MX
EL Elo BR
HI Hipercard BR
ML Cartao MercadLivre BR
MS Maestro Debit AR
NJ Naranja AR
NT Nativa Master Card AR
TS Tarjeta Shopping AR
CS Cencosud AR
CL Cabal AR
AG Argencard AR
IZ ItzCash IN
MI CMI MA
MD Mastercard Debit MX
OA OCA UY
LI Lider UY

- Api codes: Issuer bank code

The issuer bank codes (x_bank) for Mexico are shown below:

code Description Payment method
163 Banorte VI, MC
164 HSBC VI, MC, VD, MD
165 Scotiabank VI, MC
160 Santander VI, MC, VD, MD
1023 Inbursa VI, MC
1020 Ixe VI, MC
1021 Bajio VI, MC
1024 Mifel VI, MC
1018 Banco Ahorro Famsa VI, MC
1022 Banregio VI, MC
1019 Invex VI, MC
1017 Afirme VI, MC
158 Bancomer VI, MC, VD
159 Banamex VI, MC, VD, MD
162 Other VI, MC

- Device ID

To obtain the x_device_id (unique identifier of the computer where the payment is originated) it is necessary to display the following HTML to the customer. Typically this html can be added to the bottom of the same page that is used to collect the card number.


            <html>
                <body>
                    //DeviceId is available when the transaction is
            submitted. Could also be placed in a hidden input var
                    <form>
                        <input type='hidden' id='deviceId'
            name='deviceId'/>
                    </form>
                    <script src="https://cc.dlocal.com/js/device_collector.js"></script>
                </body>
                </html>
        

- Testing

Use the following information in Sandbox

Save

Any name will approve the save


Sale

  • Must be done with token returned by save function or with a test card.
  • If token sent, will always be approved.
  • For pending transaction: name = ‘PEND’. (pending)
  • For pending transaction: name = ‘CONT’. (in_process).
  • For rejected transaction: name = ‘REJE’. (cc_rejected_other_reason).
  • For rejected transaction: name =’CALL’. (cc_rejected_call_for_authorize).
  • For rejected transaction: name = ‘FUND’. (cc_rejected_insufficient_amount).
  • Any other name will trigger and approved transaction.
Card name Card number CVV Exp. Date
MASTERCARD 5031433215406351 153 09/2020
VISA 4556993263529121 554 06/2019

Use the information below for a test user:

CPF: 00003456789
Email: [email protected]
Birthdate: 04/03/1984
Zip code (CEP): 0750000
Address: dLocal 1234
City: Santa Isabel
State: RJ
Country: BR
Phone: 11987659876