Dynamic Virtual Accounts

Dynamic Virtual Accounts (DVA) are account numbers that are issued dynamically per transaction so merchants can accept payments from their retail customers.

They typically have an expiry period depending on what is supported by the bank in the market.

Types of Dynamic Virtual Accounts

In this case we only have the following option:

  • Merchant Initiated Payments (MIP) using Bank Dynamic Virtual Accounts
    • MIP: These are scenarios where the merchant must always send a request to dLocal to process a payment. The payment can only be completed for the amount specified in the merchant's request to dLocal.
    • Bank Dynamic Virtual Accounts: Bank account numbers issued dynamically per transaction requested by the merchant. Each payment will be related to a different bank account.

Availability

Pestañas Verticales con Banderas

Mexico



Minimum Amount: 1 MXN

Notification delay: Immediate

Flow: REDIRECT, DIRECT

MIP: Available

  • "payment_method_id" = "SE"
  • "payment_method_id" = "IO"

Bank Static Virtual Accounts:Available

  • "payment_method_id" = "SE"
  • "payment_method_id" = "IO"

Indonesia



Minimum Amount: 1 IDR

Notification delay: Immediate

Flow: REDIRECT, DIRECT

MIP: Available

  • "payment_method_id" = "IO"

Bank Static Virtual Accounts:Available

  • "payment_method_id" = "IO"

Niegeria



Minimum Amount: 1 NGN

Notification delay: Immediate

Flow: REDIRECT, DIRECT

MIP: Available

  • "payment_method_id" = "IO"

Bank Static Virtual Accounts:Available

  • "payment_method_id" = "IO"

Japan



Minimum Amount: 1 JPY

Notification delay: Immediate

Flow: REDIRECT, DIRECT

MIP: Available

  • "payment_method_id" = "IO"

Bank Static Virtual Accounts:Available

  • "payment_method_id" = "IO"

Overall flow

1. Merchant Initiated Payments using Bank Dynamic Virtual Accounts

This should be repeated for every transaction and the bank account will change each time.

Bank dynamic account creation with payment associated

Example request

{
    "amount": 100,
    "currency": "MXN",
    "country": "MX",
    "payment_method_id": "SE",
    "payment_method_flow": "DIRECT",
    "payer": {
        "name": "Jane Doe",
        "email": "[email protected]",
        "document": "1234567890",
        "phone": "+529848774040",
        "document": "99999999",
        "ip": "179.27.83.210",
        "address": {
            "country": "MX",
            "state": "Mexico DF",
            "city": "Mexico DF",
            "zip_code": "8858",
            "street": "Av. Principal",
            "number": "5940"
        }
    },
    "order_id": "34545sk3483kqw0",
    "description": "Tshirt",
    "notification_url": "http://merchantsite.com/notification/new",
    "callback_url": "http://merchantsite.com/success_page"
}

Request params

FieldRequiredDescription
amountYesPayment amount.
currencyYesPayment currency.
countryYesPayment processing country code. ISO 3166-1 alpha-2 code.
payment_method_idYesPayment method code chosen to create the virtual account.
Payer ObjectYes
payer.nameYesPayer's full name.
payer.emailYesPayer's email.
payer.phoneNoPayer's mobile phone number.
payer.documentYesPayer's document.
payer.ipNoPayer's IP.
payer.user_referenceYesUnique user ID at the merchant side.
Address ObjectNo
payer.address.countryNoPayer's address country.
payer.address.stateNoPayer's address state.
payer.address.cityNoPayer's address city.
payer.address.zip_codeNoPayer's address ZIP Code.
payer.address.streetNoPayer's address street.
payer.address.numberNoPayer's address number.
order_idYesID of the payment given by the merchant in their system. Can retrieve payments based on this ID. (is not mandatory).
notification_urlNoURL where dLocal will send notifications associated to changes to this payment.
callback_urlNoURL where dLocal does the final redirect. Required only for REDIRECT payment flow.

Synchronous response

{
    "id": "D-4-3e6e6631-2ed6-4444-65tr-b109af0f5a1d",
    "amount": 100,
    "currency": "MXN",
    "payment_method_id": "IO",
    "payment_method_type": "BANK_TRANSFER",
    "payment_method_flow": "DIRECT",
    "country": "MX",
    "bank_transfer": {
        "bank_account_type": "CHECKING",
        "bank_name": "STP",
        "bank_code": "STP",
        "beneficiary_name": "DEMERGE MEXICO SA DE CV",
        "bank_account": "646180205700879296",
        "bank_account_label": "CLABE",
        "reference": "64618020",
        "redirect_url": "https://pay.dlocal.com/gmf-apm/payments/M-450359a6-b3a6-4415-82a4-7965tr370370",
        "user_payment_amount": 100,
        "payment_instruction": "Ingresa a tu banca en línea y realiza la transferencia a la siguiente cuenta. Recuerda que no se pueden hacer pagos en ventanilla.",
        "expiration_date": "2023-07-06T00:16:02.500+0000"
    },
    "ticket": {},
    "created_date": "2023-07-05T22:16:02.000+0000",
    "status": "PENDING",
    "status_detail": "The payment is pending.",
    "status_code": "100",
    "order_id": "34545sk3483kqw0",
    "notification_url": "http://merchantsite.com/notification/new"
}

{
   "status": "REJECTED",
   "status_detail": "The payment was rejected",
   "status_code": "300",
  }

Response params

FieldDescription
idPayment ID.
amountPayment amount.
currencyPayment currency.
created_datePayment's creation date.
statusPayment status.
status_detailDescription of the status of the payment.
status_codePayment status code.
payment_method_idID of the selected payment method by the user.
payment_method_typeType can be BANK_TRANSFER.
payment_method_flowPayment method flow, can DIRECT or REDIRECT.
Bank Transfer Object
bank_transfer.bank_account_typeThe type of ticket can be CHECKING or SAVING.
bank_transfer.bank_nameName of the bank.
bank_transfer.bank_codeCode of the bank.
bank_transfer.beneficiary_nameName of the account holder.
bank_transfer.bank_accountBank account number.
bank_transfer.bank_account_labelLabel to be displayed related to bank_account.
bank_transfer.beneficiary_document_typeType of document of the account holder.
bank_transfer.beneficiary_documentDocument number of the account holder.
bank_transfer.referenceReference code for the payer to add on payment.
bank_transfer.redirect_urlURL of the full version of the ticket. In case you want to redirect.
bank_transfer.user_payment_amountAmount the user needs to pay.
bank_transfer.payment_instructionInstructions for making the payment.
order_idID of the payment given by the merchant in their system. Can retrieve payments based on this ID. (is not mandatory)
notification_urlURL where dLocal will send notifications associated to changes to this payment.