dLocal

This page provides an overview of the payments methods provided by the dLocal adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating dLocal within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.

Payment Methods

Payment Method	Transaction Flows	Transaction Types
Credit card	iFrame Form & payment.js Integration	Debit, Preauthorize, Capture, Void, Register, Deregister, Refund
BankTransfer	Full-Page Redirect	Debit, Payout
Abitab	Full-Page Redirect	Debit
AozoraVirtualAccounts	Full-Page Redirect	Debit, Refund
Baloto	Full-Page Redirect	Debit
BancoNacional	Full-Page Redirect	Debit
BNServicios	Full-Page Redirect	Debit
Boleto	Full-Page Redirect	Debit
BreBQR	Full-Page Redirect	Debit, Refund
CapitecPay	Full-Page Redirect	Debit, Refund
Cash	Full-Page Redirect	Debit
Davivienda	Full-Page Redirect	Debit
Efecty	Full-Page Redirect	Debit
Fawry	Full-Page Redirect	Debit
Multipago	Full-Page Redirect	Debit
Nequi	Full-Page Redirect	Debit
Oxxo	Full-Page Redirect	Debit
PagoEfectivo	Full-Page Redirect	Debit
PagoExpress	Full-Page Redirect	Debit
PagoFacil	Full-Page Redirect	Debit
PayCash	Full-Page Redirect	Debit
Pix	Full-Page Redirect	Debit
PuntoPago	Full-Page Redirect	Debit
PuntoXpress	Full-Page Redirect	Debit
QRInteroperable	Full-Page Redirect	Debit, Refund
QRIS	Full-Page Redirect	Debit, Refund
RapiPago	Full-Page Redirect	Debit
RedPagos	Full-Page Redirect	Debit
Serviepag	Full-Page Redirect	Debit
SevenEleven	Full-Page Redirect	Debit
Sinpe	Full-Page Redirect	Debit
Sinpe Movil	Full-Page Redirect	Debit, Refund
Speedmart	Full-Page Redirect	Debit
ThaiQRPayment	Full-Page Redirect	Debit, Refund
Tucan	Full-Page Redirect	Debit
UPI	Full-Page Redirect	Debit, Register
VirtualAccount	Full-Page Redirect	Debit, Refund
VNPAYQR	Full-Page Redirect	Debit, Refund
VPay	Full-Page Redirect	Debit
Wafacash	Full-Page Redirect	Debit

Additional Parameters

Credit card

Field	Required
customer.firstName	true
customer.lastName	true
customer.billingCountry	true
customer.nationalId	conditional please see: https://docs.dlocal.com/reference/country-reference
customer.billingAddress1	true in India
extraData.installments	true for Installments payments
extraData.installments_plan_id	false

Note: 3D-Secure behaviour is dependent on dLocal's configuration. For Mexico you may set 3dsecure explicitly to OPTIONAL.

APM & BankTransfer

Field	Required
customer.firstName	country dependent
customer.lastName	country dependent
customer.email	country dependent
customer.billingPhone	country and method dependent
customer.nationalId	country dependent
extraData.bank_id	true for BankTransfer

Payouts

Depending on the country and receiving bank, a variety of additional parameter may be required (refer to dLocal's documentation on country requirements).

Options Request

You can find more information about the options request here: Options Request

Debit - BankTransfer

For BankTransfer, you may retrieve a list of available banks in a country via the Options request identifier getBankList. You can display this list to your customer having him selecting his bank. The selected bank code should be submitted as bank_id in extra data.

Credit card - Installments

To make a payment using the installments make a Debit or Preauthorize request with extraData.installments param that stores the number of installment payments that customer chose to split the payment amount by. Optionally provide the id value of installment plan object inside extraData.installments_plan_id to secure the applicable installment rate.

To create an installment plan, you need to request it via the Options request identifier installmentsPlan. The returned value is installment plan object provided by dLocal (refer to dLocal's documentation on installment plans). It provides information of possible options for customer to split the payment by installments and the applicable installments rate.

Parameters

Name	Type	Required	Description
parameters.country	string	true	The country of the installments plan. 2 letters (ISO 3166-1 alpha-2)
parameters.currency	string	true	The currency of the installments plan. 3 letters (ISO 4217)
parameters.bin	string	true	The credit card bin.
parameters.amount	number	true	The amount of the installments plan

Credit card - Naranja BIN check

dLocal return different installment plans per merchant account and bind a plan to the account that created it. If your Naranja cards are processed on a separate connector, use the Options request identifier naranjaBinCheck to find out which connector a card belongs to, e.g. POST /options/{apiKey}/naranjaBinCheck with the API key of your default dLocal connector. Then request the installments plan and submit the payment on that same connector.

The list of Naranja BINs is part of the connector configuration. Please contact support to change it.

Parameters

Name	Type	Required	Description
parameters.bin	string	true	The first six or eight digits of the card. Non-digit characters are ignored.

Response

Name	Type	Description
options.bin	string	The BIN as evaluated, after non-digit characters were removed
options.isNaranja	boolean	true if the BIN is a configured Naranja BIN, false otherwise

{
  "success": true,
  "options": {
    "bin": "589562",
    "isNaranja": true
  }
}

Errors are returned with HTTP status 200, "success": false and an errorMessage:

errorMessage	Cause
Invalid Request. Parameter "bin" must contain at least one digit.	bin is missing, empty, not a string or contains no digits
Given identifier 'naranjaBinCheck' is invalid.	The API key does not belong to a dLocal credit card connector
No Naranja BINs are configured on this connector. ...	The connector has no Naranja BINs configured

Recurring UPI Payment

UPI Registration - Parameters

Name	Type	Required	Description
extraData.psp:currency	string	Conditional	Three Letter Currency Code (e.g., INR for India). This field is required if the Connector Config Field currencyForRegister is not set.
extraData.psp:wallet.recurring_info.subscription_frequency_unit	string	true	The unit of time for the recurring payments (e.g., 'days', 'months').
extraData.psp:wallet.recurring_info.subscription_frequency	int	true	The frequency of the recurring payment (e.g., 1 for monthly).
extraData.psp:wallet.recurring_info.subscription_start_at	string	true	The start date for the recurring subscription (in ISO 8601 format).
extraData.psp:wallet.recurring_info.subscription_end_at	string	false	The optional end date for the recurring subscription (in ISO 8601 format).

Recurring UPI Debit - Parameters

Name	Type	Required	Description
extraData.psp:wallet.recurring_info.prenotify	string	false	An optional prenotification for recurring debits.

dLocal MethodInventory - Payment Flows

The following payment flows are supported for recurring UPI payments:

FLOW_DIRECT: Used for direct payments, typically for debits that involve a stored wallet token.

FLOW_REDIRECT: Used for the UPI registration flow, where the user is redirected to authenticate the transaction.

3. PIX-Specific Fields (Recurring / Enrollment / payments)

PIX supports recurring payments and subscription enrollments through extraData fields.

Name	Type	Required	Description
extraData.psp:type	Debit / Register	Yes	Type of enrollment, e.g., RECURRING_CONSENT.
extraData.psp:retry_payment_id	Debit (Retry)	Conditional	ID of original payment for retry.
extraData.psp:scheduled_date	Debit (Recurring)	Optional	Date of recurring charge (YYYY-MM-DD). Defaults to current date.
extraData.psp:subscription.frequency	Register	Yes	Billing frequency, e.g., MONTHLY, DAILY.
extraData.psp:subscription.amount.type	Register	Yes	Subscription amount type (FIXED or VARIABLE).
extraData.psp:subscription.amount.value	Register	Conditional (FIXED)	Amount for FIXED type subscription (string).
extraData.psp:subscription.end_date	Register	Optional	Subscription end date (YYYY-MM-DD).
extraData.psp:enrollment.type	Debit (Initial Enrollment)	Yes	Type of enrollment, e.g., RECURRING_CONSENT.
extraData.psp:enrollment.subscription.start_date	Debit (Initial Enrollment)	Optional	Subscription start date (YYYY-MM-DD). Defaults to current date.
extraData.psp:enrollment.subscription.end_date	Debit (Initial Enrollment)	Optional	Subscription end date (YYYY-MM-DD).
extraData.psp:enrollment.subscription.frequency	Debit (Initial Enrollment)	Optional	Billing frequency, e.g., MONTHLY, DAILY.
extraData.psp:enrollment.subscription.amount.type	Debit (Initial Enrollment)	Optional	Subscription amount type (FIXED or VARIABLE).
extraData.psp:enrollment.subscription.amount.min_value	Debit (Initial Enrollment)	Conditional (VARIABLE)	Minimum value for VARIABLE type subscription (string).

The Address Object

Credit card - For India Mode

Below are the detailed reference for the Address object structure and formatting requirements:

Field	Type	Required	Description
customer.billingAddress1	String	true	User's address street. Required in India and South Africa. Length: 100
customer.billingAddress2	String	true	User's address number. Required in India and South Africa. Length: 20
customer.billingCity	String	true	User's address city. Required in India and South Africa. Length: 100
customer.billingPostcode	String	true	User's address ZIP code. Required in India and South Africa. Length: 10
customer.billingState	String	false	User's address state. Required in South Africa. Length: 10