dLocal Gateway Guide

dLocal fact sheet

Quick Start

New to integrating dLocal with Spreedly? Here's your setup guide:

Retrieve your dLocal credentials
1. Contact the dLocal support team to obtain API credentials
Get familiar with the Spreedly API
1. Review Spreedly API basics
2. Understand the core concepts: Gateways, Payment Methods, and Transactions
Add dLocal gateway to Spreedly in sandbox mode

📘
Review this documentation to understand more about how to test transactions.

Additional notes
The current supported dLocal API can respond with a success message for a request to void an authorization that has already been captured, but that void request will have no effect on the payment.
dLocal requires a Country code to be sent for each transaction. The Country can be added to a transaction by overriding the Country field of the billing address during the transaction or by sending the optional country gateway specific field. Alternately, the Country code will default to match the Country field in the billing address that was provided when the payment method token was created.
To enable the return of the `network_tx_reference` value within the gateway response for Stored Credential transactions, merchants must contact their assigned Account Manager at dLocal. This feature requires specific activation for the merchant's account.
Offsite LPM purchases are asynchronous: Spreedly returns pending until dLocal notifies completion via callback or inquire. Wallet-based refunds (Mercado Pago, Nequi, etc.) use the standard refund flow with the `wallet` gateway-specific field from the reference transaction.

Adding a dLocal Gateway

Required Credentials

login: dLocal X-Login credential (exposed via Spreedly API as a safe credential)

trans_key: dLocal X-Trans-Key (encrypted at rest)

secret_key: dLocal secret key for HMAC-SHA256 signing (encrypted at rest)

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>d_local</gateway_type>
        <login>Your login</login>
        <trans_key>Your trans_key</trans_key>
        <secret_key>Your secret_key</secret_key>
      </gateway>'

Response

<gateway>
  <token>LAynfqGFs6oWO2s3Q0MtxOQXxyz</token>
  <gateway_type>d_local</gateway_type>
  <name>dLocal</name>
  <login>Your login</login>
  <characteristics>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_card_scheme_ntid type="boolean">true</supports_card_scheme_ntid>
    <supports_credit type="boolean">true</supports_credit>
    <supports_inquire_by_gateway_transaction_id type="boolean">true</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">true</supports_inquire_by_order_id>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
    <supports_partial_capture type="boolean">true</supports_partial_capture>
    <supports_partial_credit type="boolean">true</supports_partial_credit>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_remove type="boolean">true</supports_remove>
    <supports_store type="boolean">true</supports_store>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    <supports_transaction_retry type="boolean">true</supports_transaction_retry>
    <supports_verify type="boolean">true</supports_verify>
    <supports_void type="boolean">true</supports_void>
  </characteristics>
  <gateway_specific_fields>
    <gateway_specific_field>additional_data</gateway_specific_field>
    <gateway_specific_field>bank_id</gateway_specific_field>
    <gateway_specific_field>birth_date</gateway_specific_field>
    <gateway_specific_field>country</gateway_specific_field>
    <gateway_specific_field>description</gateway_specific_field>
    <gateway_specific_field>device</gateway_specific_field>
    <gateway_specific_field>device_id</gateway_specific_field>
    <gateway_specific_field>document</gateway_specific_field>
    <gateway_specific_field>document2</gateway_specific_field>
    <gateway_specific_field>dynamic_descriptor</gateway_specific_field>
    <gateway_specific_field>enrollment_description</gateway_specific_field>
    <gateway_specific_field>enrollment_id</gateway_specific_field>
    <gateway_specific_field>external_id</gateway_specific_field>
    <gateway_specific_field>force_type</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>installments</gateway_specific_field>
    <gateway_specific_field>installments_id</gateway_specific_field>
    <gateway_specific_field>notification_url</gateway_specific_field>
    <gateway_specific_field>original_amount</gateway_specific_field>
    <gateway_specific_field>original_order_id</gateway_specific_field>
    <gateway_specific_field>original_tax_type</gateway_specific_field>
    <gateway_specific_field>original_taxed_amount</gateway_specific_field>
    <gateway_specific_field>payment_method_flow</gateway_specific_field>
    <gateway_specific_field>payment_method_id</gateway_specific_field>
    <gateway_specific_field>retry_configuration</gateway_specific_field>
    <gateway_specific_field>save</gateway_specific_field>
    <gateway_specific_field>scheduled_date</gateway_specific_field>
    <gateway_specific_field>subscription</gateway_specific_field>
    <gateway_specific_field>type</gateway_specific_field>
    <gateway_specific_field>user_reference</gateway_specific_field>
    <gateway_specific_field>wallet</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>apple_pay</payment_method>
    <payment_method>boleto_bancario</payment_method>
    <payment_method>credit_card</payment_method>
    <payment_method>efecty</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>khipu</payment_method>
    <payment_method>mercado_pago</payment_method>
    <payment_method>nequi</payment_method>
    <payment_method>oxxo</payment_method>
    <payment_method>pago_efectivo</payment_method>
    <payment_method>pago_facil</payment_method>
    <payment_method>pix</payment_method>
    <payment_method>pix_automatico</payment_method>
    <payment_method>pse</payment_method>
    <payment_method>rapi_pago</payment_method>
    <payment_method>spei</payment_method>
    <payment_method>third_party_google_pay</payment_method>
    <payment_method>third_party_network_token</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>webpay</payment_method>
    <payment_method>yape</payment_method>
  </payment_methods>
  <state>retained</state>
  <sandbox type="boolean">true</sandbox>
</gateway>

Purchase (Auth and Capture)

Example credit card purchase with common gateway-specific fields. Amount 100 = 1.00 in the transaction currency.

Request

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
  <payment_method_token>payment_method_token</payment_method_token>
  <amount>100</amount>
  <currency_code>BRL</currency_code>
  <gateway_specific_fields>
    <d_local>
      <document>1234567890</document>
      <country>Brazil</country>
      <idempotency_key>key-123</idempotency_key>
    </d_local>
  </gateway_specific_fields>
</transaction>'

Offsite Local Payment Methods

dLocal supports offsite purchase for local payment methods (Efecty, SPEI, OXXO, Pix, PSE, Webpay, Mercado Pago, Yape, Nequi, Khipu, and others). Use offsite purchase with the appropriate payment method token and, where needed, payment_method_id, payment_method_flow, and bank_id gateway-specific fields.

Detailed LPM integration guides live under the GWI LPM folder (e.g. Efecty via dLocal). Client-facing README sections merge under ## Local Payment Methods in the gateway guide.

Gateway Specific Fields

Field Name	Type	Required	Use Case	Example Value
`additional_data`	Object	No	Open-ended fraud/risk data (additional_risk_data in dLocal docs)	{...}
`bank_id`	String	No	Bank identifier for PSE and similar LPMs	1051
`birth_date`	String	No	Customer birth date (DD-MM-YYYY)	01-01-1980
`country`	String	No	Override billing address country on the transaction	Mexico
`description`	String	No	Transaction description sent to dLocal	Order 123
`device`	Object	No	Device fingerprint data for fraud prevention	{...}
`device_id`	String	No	dLocal device ID for fraud prevention (event_uuid in dLocal docs)	123
`document`	String	Often	Customer national identification number	1234567890
`document2`	String	No	Secondary document identifier	0987654321
`dynamic_descriptor`	String	No	Dynamic descriptor on card transactions	My Store
`enrollment_description`	String	No	Description for enrollment/recurring setup	Monthly plan
`enrollment_id`	String	No	Existing dLocal enrollment ID for recurring charges	E-15104-...
`external_id`	String	No	Merchant external reference; defaults to Spreedly transaction token	txn-abc
`force_type`	String	No	Card type when debit/credit ambiguous (Brazil): CREDIT or DEBIT	DEBIT
`idempotency_key`	String	No	Safe retry key for duplicate prevention	key-123
`installments`	Integer	No	Number of installments (Brazil cards)	3
`installments_id`	String	No	Installment plan identifier from dLocal	INS54434
`notification_url`	String	No (refunds)	Callback URL for async refund finalization	https://example.com/refunds
`original_amount`	String/Number	No	Original amount for tax conversion flows	100.00
`original_order_id`	String	No	Original merchant order ID when retrying a rejected transaction	ABC123
`original_tax_type`	String	No	Tax type for original amount fields	VAT
`original_taxed_amount`	String/Number	No	Original taxed amount	121.00
`payment_method_flow`	String	No	DIRECT or REDIRECT for offsite LPM flows	DIRECT
`payment_method_id`	String	No	Override dLocal payment method ID (e.g. EF, PQ, SE)	PQ
`retry_configuration`	Object	No	Retry configuration for recurring/enrollment flows	{...}
`save`	Boolean	No	Save card to merchant dLocal account on purchase/authorize/verify	true
`scheduled_date`	String	No	Scheduled charge date for enrollment (YYYY-MM-DD)	2026-01-15
`subscription`	Object	No	Subscription/recurring configuration	{...}
`type`	String	No	Transaction type override for specialized flows	...
`user_reference`	String	No	Merchant user reference sent to dLocal payer object	1357924680
`wallet`	Object	No	Wallet token for Mercado Pago, Nequi, etc. refunds	{...}

Gateway Specific Response Fields

A response from dLocal may contain the acquirer, notification_url, ticket, saved_card_type, country, status, and order_id gateway specific response fields, plus additional fields Spreedly maps from dLocal offsite and enrollment responses (wallet, qr_code, qr_code_url, redirect_url, enrollment_status, enrollment_id).

EXAMPLE (published guide format)

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0xyz</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
    <d_local>
      <acquirer>Test</acquirer>
      <notification_url>test.com</notification_url>
      <ticket>123456</ticket>
      <saved_card_type>CREDIT</saved_card_type>
      <country>BR</country>
      <status>PAID</status>
      <order_id>abcd-1234</order_id>
    </d_local>
  </gateway_specific_response_fields>
</transaction>

EXAMPLE (extended offsite / enrollment fields)

<gateway_specific_response_fields>
  <d_local>
    <acquirer>Test</acquirer>
    <notification_url>https://example.com/callback</notification_url>
    <status>PAID</status>
    <country>BR</country>
    <saved_card_type>CREDIT</saved_card_type>
    <ticket>
      <number>123456</number>
      <expiration_date>2026-12-31</expiration_date>
    </ticket>
    <redirect_url>https://pay.dlocal.com/redirect/abc</redirect_url>
    <qr_code>00020126580014BR.GOV.BCB.PIX...</qr_code>
    <qr_code_url>https://pay.dlocal.com/qr/abc.png</qr_code_url>
    <wallet>{...}</wallet>
    <enrollment_status>ACTIVE</enrollment_status>
    <enrollment_id>E-15104-2365e2ec-c0fc-4ab6-ba5c-992b5b43c210</enrollment_id>
  </d_local>
</gateway_specific_response_fields>

Field Name	Type	Description
`acquirer`	String	Acquiring bank or processor name returned by dLocal.
`notification_url`	String	Callback URL dLocal will use for asynchronous payment status updates on this transaction.
`ticket`	Object	Ticket/voucher details for offsite LPMs (barcode, expiration, reference number). For Webpay (`WP`) and SPEI (`SE`), dLocal returns ticket data in a `bank_transfer` hash at the gateway; Spreedly maps it to `ticket` (excluding `image_url`).
`saved_card_type`	String	Card type saved to the merchant dLocal account when `save` is true (e.g. `CREDIT`, `DEBIT`).
`country`	String	Two-letter ISO country code for the transaction (e.g. `BR`, `MX`).
`status`	String	Payment status at dLocal (e.g. `PAID`, `PENDING`, `REJECTED`). Spreedly may mark the transaction pending when status is not `PAID`/`SUCCESS`.
`wallet`	Object	Wallet token/details for wallet-based payment methods (Mercado Pago, Nequi, etc.). Used on subsequent wallet refunds.
`qr_code`	String	QR code payload for Pix and similar LPMs (from dLocal `qr.code`).
`qr_code_url`	String	URL to a hosted QR code image (from dLocal `qr.url`).
`redirect_url`	String	Redirect URL for offsite/REDIRECT payment flows where the buyer completes payment on dLocal or a partner page.
`enrollment_status`	String	Status of a recurring enrollment (from dLocal `enrollment.status`; e.g. Pix Automatico).
`enrollment_id`	String	dLocal enrollment identifier for recurring/charge flows (from dLocal `enrollment.id`).

Related Spreedly fields (not GSRFs):

gateway_transaction_id — dLocal payment id, payment_id, or saved card_id.
response.pending — set when dLocal status is PENDING or blank on inquire/refund responses awaiting async callbacks.
payment_method.stored_credential_usage.d_local.network_transaction_id — dLocal network_tx_reference when enabled on the merchant account (not a GSRF).

Syncing Transactions

Spreedly supports updating the status of transactions that have been initiated at the dLocal gateway. dLocal currently supports using gateway_transaction_id or order_id for updates. The gateway_transaction_id would be the payment_id of the order. While order_id is the unique identifier used by the merchant in dLocal’s system. See our Syncing Your Gateway Transaction documentation for more information.

Supported inquire characteristics: supports_inquire_by_gateway_transaction_id, supports_inquire_by_order_id.

Request (sync by transaction token — Spreedly inquires dLocal using stored gateway_transaction_id or order_id)

curl https://core.spreedly.com/v1/transactions/[transaction_token]/sync.json \
  -u 'EnvironmentKey:AccessSecret' \
  -X POST

Response (abbreviated — pending offsite payment updated to final status)

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "OffsitePurchase",
    "gateway_specific_response_fields": {
      "d_local": {
        "status": "PAID",
        "country": "BR"
      }
    },
    "response": {
      "success": true,
      "pending": false,
      "message": "The payment was paid."
    }
  }
}

Custom Terminal State Rules

When syncing your transaction, there are some transaction states that are ineligible for update. The dLocal gateway deviates from this rule. With dLocal, transactions with the state succeeded are still eligible for update only if that transaction is in a pending status at the gateway.

Third-party 3DS2 MPI

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to dLocal. dLocal supports third-party 3DS2 MPI on purchase and authorize (3dsecure_2_mpi_purchase, 3dsecure_2_mpi_authorize). Spreedly fields map to the relevant dLocal fields as described in the following table:

Spreedly field	dLocal field
`three_ds_version`	`three_dsecure_version`
`ecommerce_indicator`	`eci`
`authentication_value`	`cavv`
`directory_server_transaction_id`	`ds_transaction_id`
`authentication_response_status`	`authentication_response`
`enrolled`	`enrollment_response`
`xid`	`xid`

Third Party Google Pay

Third-Party Google Pay via dLocal allows merchants to accept Google Pay payments. Where dLocal decrypts the token on its side, extracts the underlying card details securely, processes the authorization through the card network, and returns the transaction result. Payment method type: third_party_google_pay.

Create Payment Method

The Google Pay token must be generated on the client using Google Pay APIs. Spreedly cannot generate this token.

Request

curl https://core.spreedly.com/v1/payment_methods.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment_method": {
    "third_party_google_pay": {
      "gateway_type": "d_local"
    },
    "first_name": "Test",
    "email": "[email protected]",
    "document_id": "12345678909",
    "payment_data": {
      "signature": "MEUCIQDLx5b+hiWGCbZSGXvUxuAq+KPZ33nLs3t6WrQRrI7lcwIgCFkYvfbXKkLIqMH98vmBgjES1+1ZlW1i7gJ5J1l8vYI=",
      "intermediateSigningKey": {
        "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4tvPAYP+TM/IdnDeAEE4X37Rwrrh3J82y1KwF/8tUN2viq6lP1prml+2RkMqnXCo1dffI7yzL9kek9MkaZwjKA\\u003d\\u003d\",\"keyExpiration\":\"1772002715515\"}",
        "signatures": [
          "MEUCIANW341pI6mM0rt62MV13jdTt5jm0ay3CHlp2XotJa3cAiEAiubCOItxWGiiuyUhbSDkKMwkDrmR07ktJOd98ffl2YY="
        ]
      },
      "protocolVersion": "ECv2",
      "signedMessage": "{\"encryptedMessage\":\"nr2LE5TPFU5qWTB4eX/gg4bI6qpAwqth53ZZFHjPUI0Z73P1yzHydT8ztzuA2sv6gl42vkEDYG7qE4uTfseS0TiWPyVEUfA6LaEMpvTEFERFZuiQs0L+tS5h6BOpgfbLGE2a2ma+v+2onUTe9/YxHUaTFIbNNe26zlzJcDdVwkeQY7E0BBpjepFS8GADs2WHVrDY5bS4KryVZn2fFj4uUmFcbdcvOCrifB4HgT8lbULeWNtuSe94c285VxDIHHc0MrV1iQ+l5c1wDaO341rNNIo8d8KIY8AyZt72sJrMFrl5iYT0qIi+8piIAa/psD9jDlEV+JoIzbhlVWQjr4VXht3mPj13WmczGEt7Z11f4aBChPxw68HA8NJa0Jf3O/jcIQNqFRbN35oKeSkHQld+TFgecJ9q6cZrJRx0frJJcFSvCH5t5359fGRcwAewJBlb5SsYhIDGwl4DPd49x50+1ODtmdA+CtL4v6Scy1Hv/m0\\u003d\",\"ephemeralPublicKey\":\"BKDX+proE6f0aucoOQQ9XbmbbQcRUNEFZnhqD3O8FVr2A/G0Ie4kwdh1BhwsBnHNoOU2K2KiR5dgJC9r84ylve4\\u003d\",\"tag\":\"xTKKDHVz0bHOoRiEZJg3v7jNp7NUGTaUv4UFRRomv10\\u003d\"}"
    },
    "retained": true
  }
}'

Response

{
  "transaction": {
    "token": "5M0R475VHV8ZEASN3PB3SHZR0Y",
    "created_at": "2026-02-17T08:24:01Z",
    "updated_at": "2026-02-17T08:24:01Z",
    "succeeded": true,
    "transaction_type": "AddPaymentMethod",
    "retained": true,
    "state": "succeeded",
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "payment_method": {
      "token": "01KHNB5ZKW21VF2EK6VGPWR7TM",
      "created_at": "2026-02-17T08:24:01.404Z",
      "updated_at": "2026-02-17T08:24:01.404Z",
      "email": "[email protected]",
      "storage_state": "retained",
      "test": false,
      "gateway_type": "d_local",
      "payment_method_type": "third_party_google_pay",
      "errors": []
    }
  }
}

Authorize Third Party Google Pay Transaction

Request

curl https://core.spreedly.com/v1/gateways/[gateway_token]/authorize.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "[google_payment_method_token]",
    "amount": 5200,
    "currency_code": "BRL",
    "callback_url": "https://example.com",
    "redirect_url": "https://example.com",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "document": "12345678909"
      }
    }
  }
}'

Response

{
  "transaction": {
    "on_test_gateway": true,
    "created_at": "2026-02-17T10:11:52Z",
    "updated_at": "2026-02-17T10:11:56Z",
    "succeeded": true,
    "state": "succeeded",
    "token": "GZJ6BSmxvxGPWQItZvO82aoRM90",
    "transaction_type": "Authorization",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "document": "12345678909"
      }
    },
    "gateway_specific_response_fields": {
      "d_local": {
        "saved_card_type": "DEBIT",
        "country": "BR",
        "status": "AUTHORIZED"
      }
    },
    "gateway_transaction_id": "T-15104-x1kp8fn9-vfeohpahoh0cn7-i5ssfn3cmmv8",
    "amount": 5200,
    "local_amount": 52,
    "currency_code": "BRL",
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "gateway_type": "d_local",
    "response": {
      "success": true,
      "message": "The payment was authorized.",
      "pending": false,
      "network_transaction_id": "783675059796927"
    },
    "redirect_url": "https://example.com",
    "callback_url": "https://example.com",
    "payment_method": {
      "token": "01KHNB5ZKW21VF2EK6VGPWR7TM",
      "gateway_type": "d_local",
      "payment_method_type": "third_party_google_pay"
    }
  }
}

Void / Capture Transaction

Next transaction can go either of these ways: Void Transaction and Capture Transaction.

Request(Void)

curl https://core.spreedly.com/v1/transactions/[successful_authorize_token]/void.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response(Void)

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Void",
    "gateway_specific_response_fields": {
      "d_local": {
        "country": "BR",
        "status": "CANCELLED"
      }
    },
    "response": {
      "success": true,
      "message": "The payment was cancelled."
    }
  }
}

Request (Capture)

curl https://core.spreedly.com/v1/transactions/[authorize_transaction_token]/capture.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "amount": 5200,
    "currency_code": "BRL"
  }
}'

Response (Capture)

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Capture",
    "gateway_specific_response_fields": {
      "d_local": {
        "country": "BR",
        "status": "PAID"
      }
    },
    "response": {
      "success": true,
      "message": "The payment was paid."
    }
  }
}

Purchase (Authorization + Capture) Transaction

The Purchase transaction performs an authorization and capture in a single request. This is equivalent to dLocal AUTHORIZATION_AND_CAPTURE transaction type. Use this flow when immediate settlement is required, no separate capture step is needed, and flexibility is not needed for voiding before capture.

Request

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "[google_payment_method_token]",
    "amount": 5200,
    "currency_code": "BRL",
    "callback_url": "https://example.com",
    "redirect_url": "https://example.com",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "document": "12345678909"
      }
    }
  }
}'

Response

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Purchase",
    "gateway_specific_response_fields": {
      "d_local": {
        "saved_card_type": "DEBIT",
        "country": "BR",
        "status": "PAID"
      }
    },
    "gateway_transaction_id": "T-15104-x1kp8fq0-csnftb23c95nj7-qoodg1gulhtg",
    "amount": 5200,
    "local_amount": 52,
    "currency_code": "BRL",
    "response": {
      "success": true,
      "message": "The payment was paid.",
      "network_transaction_id": "939830394026948"
    }
  }
}

Flow	Steps	When to use
Authorize → Capture	2 API calls	Void before settlement
Purchase	1 API call	Immediate capture is required

Stored Credentials

For dLocal, sending stored credential fields can be done using Spreedly’s first class support. For any Authorize, Purchase, or Verify request, include stored_credential_initiator and stored_credential_reason_type. Spreedly maps these to dLocal card.stored_credential_usage (FIRST or USED) and card.stored_credential_type.

When dLocal returns a network transaction ID, Spreedly stores it on the payment method at payment_method.stored_credential_usage.d_local.network_transaction_id (from dLocal network_tx_reference). Merchants must contact their dLocal Account Manager to enable network_tx_reference on the merchant account (see Additional Information). Set stored_credential_alternate_gateway to d_local when the original network transaction ID was obtained on dLocal but the current transaction runs on another gateway.

📘
Learn more about how Spreedly enables use of stored credentials by reviewing our Stored Credentials guide

First / credential-on-file setup (CIT)

`reason_type`	`initiator`	`card.stored_credential_usage`	`card.stored_credential_type`
`unscheduled`	cardholder	`FIRST`	`CARD_ON_FILE`
`unscheduled`	merchant	`FIRST`	`UNSCHEDULED_CARD_ON_FILE`
`recurring`	cardholder	`FIRST`	`SUBSCRIPTION`
`recurring`	merchant	`FIRST`	`SUBSCRIPTION`
`installment`	cardholder	`FIRST`	`SUBSCRIPTION`
`installment`	merchant	`FIRST`	`SUBSCRIPTION`

Subsequent use (MIT)

`reason_type`	`initiator`	`card.stored_credential_usage`	`card.stored_credential_type`
`unscheduled`	cardholder	`USED`	`CARD_ON_FILE`
`unscheduled`	merchant	`USED`	`UNSCHEDULED_CARD_ON_FILE`
`recurring`	cardholder	`USED`	`SUBSCRIPTION`
`recurring`	merchant	`USED`	`SUBSCRIPTION`
`installment`	cardholder	`USED`	`SUBSCRIPTION`
`installment`	merchant	`USED`	`SUBSCRIPTION`

Subsequent transactions include card.network_payment_reference when Spreedly has a stored network_transaction_id for dLocal.

Request (CIT — initial cardholder-initiated)

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 100,
    "currency_code": "BRL",
    "billing_address": { "country": "Brazil" },
    "gateway_specific_fields": {
      "d_local": { "document": "71575743221" }
    },
    "stored_credential_initiator": "cardholder",
    "stored_credential_reason_type": "recurring"
  }
}'

Request (CIT)

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Purchase",
    "amount": 100,
    "currency_code": "BRL",
    "response": {
      "success": true,
      "network_transaction_id": "MCC000000355"
    },
    "payment_method": {
      "token": "payment_method_token",
      "stored_credential_usage": {
        "d_local": {
          "network_transaction_id": "MCC000000355"
        }
      }
    },
    "gateway_type": "d_local",
    "message": "Succeeded!"
  }
}

Request (MIT — subsequent merchant-initiated)

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "payment_method_token",
    "amount": 100,
    "currency_code": "BRL",
    "billing_address": { "country": "Brazil" },
    "gateway_specific_fields": {
      "d_local": { "document": "71575743221" }
    },
    "stored_credential_initiator": "merchant",
    "stored_credential_reason_type": "unscheduled"
  }
}'

Response (MIT)

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Purchase",
    "amount": 100,
    "currency_code": "BRL",
    "payment_method": {
      "token": "payment_method_token",
      "stored_credential_usage": {
        "d_local": {
          "network_transaction_id": "MCC000000355"
        }
      }
    },
    "gateway_type": "d_local",
    "message": "Succeeded!"
  }
}

store and remove are supported for credit cards only. Attempting store on other payment method types raises IncompatibleAbilityOnPaymentMethodError. Alternatively, pass save: true in gateway-specific fields on purchase, authorize, or verify to save the card to the merchant’s dLocal account (returns saved_card_type GSRF).

Network Tokenization

dLocal supports network tokenization (supports_network_tokenization) for credit_card, third_party_network_token, and third_party_token payment methods. Set attempt_network_token: true when transacting with Spreedly-managed network tokens. dLocal has the recurring_network_token quirk enabled for recurring MIT flows with network tokens.

Request (network token purchase with stored credentials)

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "payment_method_token": "network_token_payment_method_token",
    "amount": 100,
    "currency_code": "BRL",
    "billing_address": { "country": "Brazil" },
    "gateway_specific_fields": {
      "d_local": { "document": "71575743221" }
    },
    "stored_credential_initiator": "merchant",
    "stored_credential_reason_type": "unscheduled",
    "attempt_network_token": true
  }
}'

Response

{
  "transaction": {
    "succeeded": true,
    "state": "succeeded",
    "transaction_type": "Purchase",
    "amount": 100,
    "currency_code": "BRL",
    "network_tokenization": {
      "attempted": true,
      "errors": []
    },
    "response": {
      "success": true,
      "network_transaction_id": "MCC000000355"
    },
    "gateway_type": "d_local",
    "message": "Succeeded!"
  }
}

Credit (Refund)

Refunds are processed as credit transactions. Google Pay refunds follow standard dLocal refund flow. Since Purchase already performs capture, Void is not applicable.

📘
Note
Refunds are only allowed after a successful CAPTURE.

Request

curl https://core.spreedly.com/v1/transactions/[successful_capture_transaction_token]/credit.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "amount": 5200,
    "currency_code": "BRL"
  }
}'

Response

{
  "transaction": {
    "on_test_gateway": true,
    "created_at": "2026-02-17T08:33:30Z",
    "updated_at": "2026-02-17T08:33:36Z",
    "succeeded": true,
    "state": "succeeded",
    "token": "NmCpHnGpoJCXkE1O2nCpW7XAFaD",
    "transaction_type": "Credit",
    "gateway_specific_response_fields": {
      "d_local": {
        "notification_url": "http://core.spreedly.test/transaction/NmCpHnGpoJCXkE1O2nCpW7XAFaD/callback",
        "status": "SUCCESS"
      }
    },
    "gateway_transaction_id": "REF-15104-x1kp89ut-928a083mhd7dp3-gv7118iit8n4",
    "amount": 5200,
    "local_amount": 52,
    "currency_code": "BRL",
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "gateway_type": "d_local",
    "response": {
      "success": true,
      "message": "The refund was paid.",
      "pending": false
    },
    "reference_token": "Z3vLrvLQBo0mnMNOhGiGdQb1Z91"
  }
}

Offsite LPM async refunds

For local payment method refunds where a callback_url is provided on the credit transaction, Spreedly sends dLocal a notification_url (via the hijacked callback URL). When dLocal does not immediately return PAID or SUCCESS, the refund is marked response.pending: true until dLocal posts an async callback. Passing notification_url in gateway-specific fields on refund will allow dLocal to send HTTP POST notices of the refund’s finalization to that URL, if the refund is not immediate.

Request (LPM refund with callback)

curl https://core.spreedly.com/v1/transactions/[successful_lpm_purchase_token]/credit.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
  "transaction": {
    "amount": 1000,
    "currency_code": "BRL",
    "callback_url": "https://example.com/refunds/callback",
    "gateway_specific_fields": {
      "d_local": {
        "notification_url": "https://example.com/refunds/callback"
      }
    }
  }
}'

Response (pending async refund)

{
  "transaction": {
    "succeeded": true,
    "state": "pending",
    "transaction_type": "Credit",
    "gateway_specific_response_fields": {
      "d_local": {
        "notification_url": "https://example.com/refunds/callback",
        "status": "PENDING"
      }
    },
    "response": {
      "success": true,
      "pending": true,
      "message": "The payment is pending."
    }
  }
}

Wallet-based refunds (Mercado Pago, Nequi, etc.): Spreedly includes the wallet object from the reference transaction’s gateway-specific fields automatically; these refunds do not use async callbacks.

LPM-specific refund rules (e.g. only refund after PAID, partial refund limits) are documented in each Local Payment Methods subsection of the client-facing gateway guide.

Google Pay

The dLocal gateway integration has been expanded to include support for Google Pay, allowing for the processing of payment tokens through the dLocal platform.

The implementation facilitates quick payment experience, reducing friction during the checkout process. Transactions via Google Pay follow the established authorization and capture lifecycle supported by the gateway.

Local Payment Methods

Spreedly supports a variety of payment methods through dLocal. Each may require unique parameters and flows. Please expand each payment method's details to find implementation information.

PIX

Pix

Pix is a payment method for instant direct bank transfers in Brazil, which is built and owned by the Central Bank (Banco Central) and operated by Brazilian banks, digital accounts, and wallets. This section explains how to integrate Pix (instant bank transfer payment in Brazil) via dLocal using Spreedly.

Key Capabilities

One-step offsite purchase: create Pix charge, await webhook confirmation.
Asynchronous notifications via notification_url (payment.updated).
Refunds (full and partial) after payment is PAID

Constraints

Country: BR; Currency: BRL.
dLocal payment method id: typically PIX
Session/QR expiration: short-lived (minutes), enforced by Pix/dLocal.

Create Pix Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "pix", //payment_method_type: must be "pix"
    "country_code": "BR",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "12345678909" //document_id: Brazilian CPF
  }
}

{
    "transaction": {
        "token": "7SF6BN2Y188M1TWT4AESZVTGXT",
        "created_at": "2026-04-22T10:21:02Z",
        "updated_at": "2026-04-22T10:21:02Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "01KPTBA84HH0DWHT4PHTVSGKP6",
            "created_at": "2026-04-22T10:21:02.481Z",
            "updated_at": "2026-04-22T10:21:02.481Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "last_successfully_used": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": "BR",
            "phone_number": null,
            "full_name": "Jane Doe",
            "first_name": "Jane",
            "last_name": "Doe",
            "bic": null,
            "payment_method_type": "pix",
            "errors": [],
            "document_id": "8909"
        }
    }
}

Create Pix Purchase

Redirect or Direct

Using the DIRECT method, the payment will have the PENDING status until the user confirms the payment, and dLocal gets notified (immediate after user confirmation). Use Pix details (QR code/qr string) from dLocal to render in the UI.

The API returns a redirect_URL, which is used to redirect the user to a dLocal-hosted page. The user will be able to open any App that supports Pix (Home Banking and Ewallets) and decide whether to use the scan QR or the Transaction ID copy/paste option.

API Request

POST /v1/gateways/{{gateway_token}}/purchase.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "transaction": {
    "payment_method_token": "{{pix_payment_method_token}}", //payment_method_token: token from Create Pix Payment Method
    "amount": 10000,
    "currency_code": "BRL",
    "callback_url": "https://merchant.example.com/pix/callback", //callback_url: where Spreedly will call back
    "redirect_url": "https://merchant.example.com/pix/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_id": "PIX",
        "payment_method_flow": "REDIRECT" //payment_method_flow: "DIRECT" or "REDIRECT" depending on dLocal config
      }
    }
  }
}

//Status: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-04-22T10:24:26Z",
        "updated_at": "2026-04-22T10:24:29Z",
        "succeeded": false,
        "state": "pending",
        "token": "F4bajKnGDRyemZ6lRXCSueWxHPZ",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_id": "PIX",
                "payment_method_flow": "REDIRECT"
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://ppathak.ngrok.dev/transaction/F4bajKnGDRyemZ6lRXCSueWxHPZ/callback",
                "country": "BR",
                "status": "PENDING",
                "redirect_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-0949a1c0-b1d7-4aba-8136-08663cf8a5d0"
            }
        },
        "gateway_transaction_id": "R-15104-x1kuh8er-aaa96saqal40pa-gg75ubhkhf1o",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1611,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 10000,
        "local_amount": null,
        "currency_code": "BRL",
        "reference": "R-15104-x1kuh8er-aaa96saqal40pa-gg75ubhkhf1o",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "2EQ287B66V9VY8JH3TBVC0GVCZ",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-04-22T10:24:28Z",
            "updated_at": "2026-04-22T10:24:29Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-0949a1c0-b1d7-4aba-8136-08663cf8a5d0"
        },
        "shipping_address": {
            "name": "Jane Doe",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/7QG876M6FX88VTQ7TKF0MVDP0B/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://merchant.example.com/pix/return",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-0949a1c0-b1d7-4aba-8136-08663cf8a5d0",
        "callback_url": "https://merchant.example.com/pix/callback",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-04-22T10:24:28Z",
            "updated_at": "2026-04-22T10:24:29Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-0949a1c0-b1d7-4aba-8136-08663cf8a5d0"
        },
        "payment_method": {
            "token": "01KPTBA84HH0DWHT4PHTVSGKP6",
            "created_at": "2026-04-22T10:21:02.481Z",
            "updated_at": "2026-04-22T10:21:02.481Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "last_successfully_used": null,
            "full_name": "Jane Doe",
            "first_name": "Jane",
            "last_name": "Doe",
            "bic": null,
            "payment_method_type": "pix",
            "errors": []
        }
    }
}

Note

Show the Pix QR code via:

gateway_specific_response_fields.d_local.pix.qr_code (EMV string)
or qr_code_base64/qr_code_url
or redirect the customer to checkout_url

Transaction stays pending until dLocal confirms via webhook

Webhook Notifications (notification_url)

dLocal sends asynchronous events to its notification_url and/or via Spreedly callback flows. A typical payment.updated looks like:

{
  "event": "payment.updated",
  "data": {
    "id": "R-15104-x1kuh8er-aaa96saqal40pa-gg75ubhkhf1o",
    "status": "PAID",
    "status_detail": "The Pix payment was successfully completed.",
    "status_code": "200",
    "amount": 10000,
    "currency": "BRL",
    "order_id": "order-id-123",
    "payment_method_id": "PIX",
    "pix": {
      "qr_code": "00020101021226...",
      "paid_at": "2026-01-10T14:11:02Z"
    }
  }
}

Recommended steps:

Validate authenticity (signature/secret per the dLocal contract).
Map data.id / order_id back to the internal order & Spreedly transaction.
Update local state according to status mapping (below).
Ensure idempotent updates (same event ID processed once)

Status Mapping

Provider Status	Meaning	Typical Action
`PENDING`	Pix charge created; awaiting customer payment	Show QR/checkout link; wait for webhook
`PAID`	Customer paid via Pix; funds confirmed by dLocal	Mark order paid; enable fulfillment & refunds
`EXPIRED`	QR/session expired without payment	Mark payment failed; offer new Pix attempt
`REJECTED`	Payment rejected/failed	Mark failed; show error and alternate payment
`CANCELLED`	Payment canceled (if supported)	Stop processing; show cancellation to customer

Refunds

Refunds are only valid once the original Pix payment is PAID. PENDING/EXPIRED/REJECTED should not be refundable

POST /v1/transactions/{{transaction_token}}/credit.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "transaction": {
    "amount": 10000, //Omit amount for full refund; include it for partial
    "currency_code": "BRL",
    "notification_url": "https://merchant.example.com/pix/refund-callback"
  }
}

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-04-22T10:32:34Z",
        "updated_at": "2026-04-22T10:32:38Z",
        "succeeded": false,
        "state": "processing",
        "token": "6OURKNNcJJqV2875X92td8WKbLf",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {},
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://ppathak.ngrok.dev/transaction/6OURKNNcJJqV2875X92td8WKbLf/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kuh8u6-29ubgk2gup3trd-0p47e1rfcoes",
        "sub_merchant_key": null,
        "gateway_latency_ms": 3917,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 10000,
        "local_amount": 100,
        "currency_code": "BRL",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "2EQ287B66V9VY8JH3TBVC0GVCZ",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-04-22T10:32:38Z",
            "updated_at": "2026-04-22T10:32:38Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "F4bajKnGDRyemZ6lRXCSueWxHPZ"
    }
}

//Refund Webhook Example


{
  "event": "payment.updated",
  "data": {
    "id": "REF-15104-x1kuh8u6-29ubgk2gup3trd-0p47e1rfcoes",
    "status": "SUCCESS",
    "status_detail": "Refund succeeded",
    "status_code": "200",
    "amount": 10000,
    "currency": "BRL",
    "order_id": "your-order-id-123",
    "payment_method_id": "PIX"
  }
}

API Field Reference

Field	Example / Type	Notes
`payment_method_type`	`"pix"`	Spreedly payment method type
`payment_method_id`	`"pix"`	dLocal ID for Pix (confirm with dLocal).
`payment_method_flow`	`"DIRECT" / "REDIRECT"`	Flow style per dLocal config
`country / country_code`	`"BR"`	Required; Brazil only.
`currency / currency_code`	`"BRL"`	Must be BRL
`notification_url`	`https://.../notifications/dlocal`	dLocal webhook endpoint
`callback_url`	`https://merchant.example.com/pix/callback`	Spreedly callback/return handling
`redirect_url`	`https://merchant.example.com/pix/return`	Where customer returns after redirect
`checkout_url`	`https://sandbox.dlocal.com/gmf-apm/payments/...`	dLocal-hosted Pix page (redirect)

Pix Automatico

Pix Automático is dLocal’s recurring payment solution for Brazil, allowing merchants to create subscription-based or automated recurring collections using Pix. The flow starts with an Enrollment request that registers the payer and subscription details. Once enrolled, recurring debits occur automatically based on the configured schedule

Create Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
    "payment_method": {
        "email": "[email protected]",
        "payment_method_type": "pix_automatico",
        "full_name": "Demo User",
        "document_id": "12345678909",
        "country": "BR",
        "currency_code": "BRL",
        "zip": "12345",
        "address1": "1234 test ave",
        "city": "Rio",
        "state": "CE",
        "phone_number": "1234567890",
        "retained": "true"
    }
}

//Status Code: 201 Created

{
    "transaction": {
        "token": "8Q4cB7bmzbxv31sRpHzhhRunVpJ",
        "created_at": "2025-12-11T02:12:22Z",
        "updated_at": "2025-12-11T02:12:22Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": true,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "MzZQMcx22L92Y880Lsa7BIAAIQY",
            "created_at": "2025-12-11T02:12:22Z",
            "updated_at": "2025-12-11T02:12:22Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "BR",
            "phone_number": "1234567890",
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "pix_automatico",
            "errors": [],
            "document_id": "8909"
        }
    }
}

Create Enrollments

Gateway Specific Fields & Gateway Specific Response Fields

Gateway Specific Fields are additional parameters required by the Spreedly for enrollment processing. These can be provided as key/value pairs or as a hash.

Gateway Specific Response Fields are additional data returned by the payment gateway after enrollment processing

{
  "transaction": {
    "payment_method_token": "{{pix_automatico_payment_method_token}}",
    "currency_code": "BRL",
    "callback_url": "https://webhook.site/717f09fd-424b-4765-8378-df4eca9a6c23",
    "redirect_url": "https://webhook.site/717f09fd-424b-4765-8378-df4eca9a6c23",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "type": "MERCHANT_SUBSCRIPTION",
        "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
        "subscription": {
          "start_date": "2025-12-20",
          "end_date": "2026-12-20",
          "frequency": "MONTHLY",
          "amount": {
            "type": "VARIABLE",
            "min_value": "300"
          }
        }
      }
    }
  }
}

"gateway_specific_response_fields": {
            "d_local": {
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002635134",
                    "expiration_date": "2026-01-03",
                    "id": "9900002635134",
                    "barcode": "226275591",
                    "company_name": "The Best Company",
                    "company_id": "112903"
                },
                "status": "PENDING"
            }
        }

"response": {
            .........
            "success": true,
            "message": "The enrollment is pending.",
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-1305af55-1da4-4b6c-8de8-cdb083af6b0c"
            ..........
        }

Fixed & Variable Amount Enrollments

{
  "transaction": {
    "payment_method_token": "{{pix_automatico_payment_method_token}}",
    "currency_code": "BRL",
    "callback_url": "https://webhook.site/717f09fd-424b-4765-8378-df4eca9a6c23",
    "redirect_url": "https://webhook.site/717f09fd-424b-4765-8378-df4eca9a6c23",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "type": "MERCHANT_SUBSCRIPTION",
        "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
        "subscription": {
          "start_date": "2025-12-20",
          "end_date": "2026-12-20",
          "frequency": "MONTHLY",
          "amount": {
            "type": "FIXED",
            "value": "300"
          }
        }
      }
    }
  }
}

{
  "transaction": {
    "payment_method_token": "{{pix_automatico_payment_method_token}}",
    "currency_code": "BRL",
    "callback_url": "https://webhook.site/717f09fd-424b-4765-8378-df4eca9a6c23",
    "redirect_url": "https://webhook.site/717f09fd-424b-4765-8378-df4eca9a6c23",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "type": "MERCHANT_SUBSCRIPTION",
        "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
        "subscription": {
          "start_date": "2025-12-20",
          "end_date": "2026-12-20",
          "frequency": "MONTHLY",
          "amount": {
            "type": "VARIABLE",
            "min_value": "300"
          }
        }
      }
    }
  }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-12-19T06:47:15Z",
        "updated_at": "2025-12-19T06:47:21Z",
        "succeeded": false,
        "state": "processing",
        "token": "9ibDi4PgVHHKRo98P4e2kjWHUEK",
        "transaction_type": "Verification",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "country": "BR",
                "type": "MERCHANT_SUBSCRIPTION",
                "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
                "subscription": {
                    "start_date": "2025-12-20",
                    "end_date": "2026-12-20",
                    "frequency": "MONTHLY",
                    "amount": {
                        "type": "FIXED",
                        "value": "300"
                    }
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002635150",
                    "expiration_date": "2026-01-03",
                    "id": "9900002635150",
                    "barcode": "152118800",
                    "company_name": "The Best Company",
                    "company_id": "112903"
                },
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "E-15104-555248e0-f71c-4778-af05-d69b7c62fb01",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2548,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "currency_code": "BRL",
        "payment_method_added": false,
        "retain_on_success": false,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "3W5Q2TFWMW8DZREX3R9PPNSSY0",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The enrollment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": "100",
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-19T06:47:18Z",
            "updated_at": "2025-12-19T06:47:21Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-8018f2b1-eed7-4618-a3b5-122a432793ed"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "callback_url": null,
        "payment_method": {
            "token": "6j7I3yFZxH5W4iy4MoD8FZGXnwr",
            "created_at": "2025-12-18T05:06:26Z",
            "updated_at": "2025-12-18T05:06:26Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "pix_automatico",
            "errors": []
        }
    }
}

Create Payment Request for Enrollments

Gateway Specific Fields & Gateway Specific Response Fields

Gateway Specific Fields for payment requests include transaction-specific parameters and Gateway Specific Response Fields for payment responses.

"gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "enrollment_id": "{{enrollment_id}}",
        "payment_method_flow": "DIRECT",
        "scheduled_date": "2026-01-15"
      }
    }

"gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://c8dbedb691b3.ngrok.app/transaction/BdWWRtgoNDV3AmC6Wwunw9E0zz6/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002627140",
                    "expiration_date": "2025-12-25T02:59:59.999+0000",
                    "id": "9900002627140",
                    "barcode": "609251680",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "amount": 50.0
                },
                "country": "BR",
                "status": "PENDING"
            }
  }

API Request

POST POST /v1/gateways/{{gateway_token}}/purchase.json

{
  "transaction": {
    "payment_method_token": "{{pix_automatico_payment_method_token}}",
    "amount": 500,
    "currency_code": "BRL",
    "description": "Monthly subscription payment",
    "callback_url": "https://webhook.site/your-callback-url",
    "redirect_url": "https://webhook.site/your-redirect-url",
    "gateway_specific_fields": {
      "d_local": {
        "country": "BR",
        "enrollment_id": "{{enrollment_id}}",
        "payment_method_flow": "DIRECT",
        "scheduled_date": "2026-01-15"
      }
    }
  }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-12-17T12:25:51Z",
        "updated_at": "2025-12-17T12:25:56Z",
        "succeeded": false,
        "state": "processing",
        "token": "BdWWRtgoNDV3AmC6Wwunw9E0zz6",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": "Monthly subscription payment",
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "country": "BR",
                "enrollment_id": "E-15104-2365e2ec-c0fc-4ab6-ba5c-992b5b43c210",
                "payment_method_flow": "DIRECT",
                "scheduled_date": "2026-01-15"
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://c8dbedb691b3.ngrok.app/transaction/BdWWRtgoNDV3AmC6Wwunw9E0zz6/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002627140",
                    "expiration_date": "2025-12-25T02:59:59.999+0000",
                    "id": "9900002627140",
                    "barcode": "609251680",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "amount": 50.0
                },
                "country": "BR",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1kk58ag-i1berl2dfl5m1c-mujp2554lgd8",
        "sub_merchant_key": null,
        "gateway_latency_ms": 945,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "BRL",
        "reference": "D-15104-x1kk58ag-i1berl2dfl5m1c-mujp2554lgd8",
        "setup_verification": null,
        "expiration_date": "2025-12-25 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "0Y54GWSGWN88R9GYC6JTB23BP1",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-17T12:25:53Z",
            "updated_at": "2025-12-17T12:25:56Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-12feb065-20ef-4c76-8d4d-912e2b5c355e"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-17T12:25:53Z",
            "updated_at": "2025-12-17T12:25:56Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-12feb065-20ef-4c76-8d4d-912e2b5c355e"
        },
        "callback_url": null,
        "payment_method": {
            "token": "Hj1xQ382WQnQyIukOkj4HNAtnqx",
            "created_at": "2025-12-17T12:06:08Z",
            "updated_at": "2025-12-17T12:17:19Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "pix_automatico",
            "errors": []
        }
    }
}

Create Enrollment + Initial Payment

Gateway Specific Fields & Gateway Specific Response Fields

Gateway Specific Fields for payment requests include transaction-specific parameters and Gateway Specific Response Fields for payment responses.

"gateway_specific_fields": {
      "d_local": {
        "description": "200:approved",
        "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
        "country": "BR",
        "payment_method_flow": "DIRECT",
        "type": "MERCHANT_SUBSCRIPTION",
        "subscription": {
          "start_date": "2025-12-20",
          "end_date": "2026-12-20",
          "frequency": "MONTHLY",
          "amount": {
            "type": "VARIABLE",
            "min_value": "50",
            "installments": 1
          }
        }
      }
    }

"gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "http://example.com/transaction/X03ybIxRpvVpG9IMwQa0aVBBIAD/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002630858",
                    "expiration_date": "2025-12-26T02:59:59.999+0000",
                    "id": "9900002630858",
                    "barcode": "211948002",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "amount": 50.0
                },
                "country": "BR",
                "status": "PENDING",
                "enrollment_status": "PENDING",
                "enrollment_id": "E-15104-e66e6ce1-5f7f-48d1-ac5e-0479509092eb"
            }
        },

API Request

POST POST /v1/gateways/{{gateway_token}}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{pix_automatico_payment_method_token}}",
        "amount": 500,
        "currency_code": "BRL",
        "callback_url": "https://658806ef0735.ngrok.app",
        "redirect_url": "https://0a3289bedeb6.ngrok.app",
        "gateway_specific_fields": {
            "d_local": {
                "description": "200:approved",
                "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
                "country": "BR",
                "payment_method_flow": "DIRECT",
                "type": "MERCHANT_SUBSCRIPTION",
                "subscription": {
                    "start_date": "2025-12-20",
                    "end_date": "2026-12-20",
                    "frequency": "MONTHLY",
                    "amount": {
                        "type": "VARIABLE",
                        "min_value": "50",
                        "installments": 1
                    }
                }
            }
        }
    }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-12-18T10:18:56Z",
        "updated_at": "2025-12-18T10:19:00Z",
        "succeeded": false,
        "state": "processing",
        "token": "X03ybIxRpvVpG9IMwQa0aVBBIAD",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "description": "200:approved",
                "enrollment_description": "Pix Automatico - Monthly subscription - Variable amount",
                "country": "BR",
                "payment_method_flow": "DIRECT",
                "type": "MERCHANT_SUBSCRIPTION",
                "subscription": {
                    "start_date": "2025-12-20",
                    "end_date": "2026-12-20",
                    "frequency": "MONTHLY",
                    "amount": {
                        "type": "VARIABLE",
                        "min_value": "50",
                        "installments": 1
                    }
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "http://core.spreedly.test/transaction/X03ybIxRpvVpG9IMwQa0aVBBIAD/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002630858",
                    "expiration_date": "2025-12-26T02:59:59.999+0000",
                    "id": "9900002630858",
                    "barcode": "211948002",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "amount": 50.0
                },
                "country": "BR",
                "status": "PENDING",
                "enrollment_status": "PENDING",
                "enrollment_id": "E-15104-e66e6ce1-5f7f-48d1-ac5e-0479509092eb"
            }
        },
        "gateway_transaction_id": "D-15104-x1kk7l8g-jd80betckd0cj0-27n2i9cu5vns",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2836,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "BRL",
        "reference": "D-15104-x1kk7l8g-jd80betckd0cj0-27n2i9cu5vns",
        "setup_verification": null,
        "expiration_date": "2025-12-26 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "0Y54GWSGWN88R9GYC6JTB23BP1",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-18T10:18:59Z",
            "updated_at": "2025-12-18T10:19:00Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-10fda093-0a2d-44bb-b285-40f86bb3d69c"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-18T10:18:59Z",
            "updated_at": "2025-12-18T10:19:00Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-10fda093-0a2d-44bb-b285-40f86bb3d69c"
        },
        "callback_url": null,
        "payment_method": {
            "token": "Hj1xQ382WQnQyIukOkj4HNAtnqx",
            "created_at": "2025-12-17T12:06:08Z",
            "updated_at": "2025-12-17T12:26:11Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "pix_automatico",
            "errors": []
        }
    }
}

Void Enrollment

To cancel the enrollment the merchant must perform a void request on Verification

Endpoint:  POST /v1/transactions/{{successful_transaction}}/void.json

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-12-11T09:14:46Z",
        "updated_at": "2025-12-11T09:14:49Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "Jy8Uq43kn0tqAm0KBOojCSfXWRu",
        "transaction_type": "Void",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {},
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://e9d12d844132.ngrok.app/transaction/LAof7dGrMZc4yra7DYlXq3QbJ3n/callback",
                "country": "BR",
                "status": "CANCELLED"
            }
        },
        "gateway_transaction_id": "D-15104-x1kjl2ml-c15j4n86bl3h7d-37js7i6inju0",
        "sub_merchant_key": null,
        "gateway_latency_ms": 841,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "24RTMPP62W84V9CTWRW54J26ZF",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment was cancelled.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-11T09:14:47Z",
            "updated_at": "2025-12-11T09:14:49Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "reference_token": "LAof7dGrMZc4yra7DYlXq3QbJ3n"
    }
}

Refund Payment

POST /v1/transactions/{{successful_transaction}}/credit.json

{
    "transaction": {
        "on_test_gateway": false,
        "created_at": "2025-12-04T13:39:26Z",
        "updated_at": "2025-12-04T13:50:27Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "LillQMR9YUF1Nq1MxSAZNa9KrXr",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": "test description",
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://503a08dbcd4f.ngrok.app/transaction/LillQMR9YUF1Nq1MxSAZNa9KrXr/callback",
                "status": "SUCCESS",
                "enrollment_id": "REF-15104-x1kj33og-bb9un4ukv13db7-7okti4j4gid4"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kj33og-bb9un4ukv13db7-7okti4j4gid4",
        "sub_merchant_key": null,
        "gateway_latency_ms": null,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "BRL",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "6304SS3A7H9AYSAJ6QV7R7HM32",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": null,
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": false,
            "created_at": "2025-12-04T13:50:27Z",
            "updated_at": "2025-12-04T13:50:27Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "YuxhecgrKHffgVG1OpQ6OjCpmIj"
    }
}

Efecty

Efecty is a cash payment method in Colombia supported by dLocal. The merchant creates a voucher (ticket) that customers pay in person at an Efecty location. The transaction remains pending until dLocal confirms payment (or it expires). Flows can be DIRECT (voucher shown on your site) or REDIRECT (voucher hosted by dLocal).

API Field Reference (Efecty/dLocal)

Field	Type/Example	Notes
payment_method_id	"EY"	Use EFECTY/EY per dLocal docs
payment_method_flow	"DIRECT" \\| "REDIRECT"	Choose UX pattern; impacts response
notification_url	https://merchant.example.com/notifications/dlocal	Receive async status updates

DIRECT: Render the returned ticket/barcode and reference number in your UI.
REDIRECT: Obtain a checkout URL and send the customer to dLocal’s hosted page; dLocal displays the voucher and instructions.

Create Efecty Payment Method

Endpoint

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "efecty", //Must be "efecty"
    "country_code": "CO",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "12345678"
  }
}

//Status Code: 201 Created

{
    "transaction": {
        "token": "Ft3FP24PecDskKeKQ2JX1aBOdv4", // Unique identifier for the payment method
        "created_at": "2025-11-18T13:43:35Z",
        "updated_at": "2025-11-18T13:43:35Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": true,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "VkwPFqbN34Nc5x4lr9iM2aEcD9u",
            "created_at": "2025-11-18T13:43:35Z",
            "updated_at": "2025-11-18T13:43:35Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "CO",
            "phone_number": "8522847035",
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "efecty",
            "errors": [],
            "document_id": "7737"
        }
    }
}

Create Efecty Purchase (Voucher)

Take the payment method and create a purchase request.

Endpoint

POST /v1/gateways/{{gateway_token}}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{efecty_payment_method_token}}",
        "amount": 5000,
        "currency_code": "COP",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com",
        "gateway_specific_fields": {
            "dlocal": {
                "payment_method_flow": "DIRECT"
            }
        }
    }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-21T13:25:03Z",
        "updated_at": "2025-11-21T13:25:08Z",
        "succeeded": false,
        "state": "pending",
        "token": "2erbIHiLaA5TTTYUxDF8zIunXSH",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/2erbIHiLaA5TTTYUxDF8zIunXSH/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002555458",
                    "expiration_date": "2025-11-29T02:59:59.999+0000",
                    "id": "9900002555458",
                    "barcode": "963367063",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "image_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719",
                    "amount": 50
                },
                "country": "CO",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1ki0q1g-kppkmvgu5h3b1e-bfd4bmp7rquc",
        "sub_merchant_key": null,
        "gateway_latency_ms": 910,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "COP",
        "reference": "D-15104-x1ki0q1g-kppkmvgu5h3b1e-bfd4bmp7rquc",
        "setup_verification": null,
        "expiration_date": "2025-11-29 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-21T13:25:04Z",
            "updated_at": "2025-11-21T13:25:07Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719"
        },
        "shipping_address": {
            "name": "Spreedly GWI",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/427FGCAX4Q9RZAH7045K3MH7R1/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-21T13:25:04Z",
            "updated_at": "2025-11-21T13:25:07Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719"
        },
        "payment_method": {
            "token": "VkwPFqbN34Nc5x4lr9iM2aEcD9u",
            "created_at": "2025-11-18T13:43:35Z",
            "updated_at": "2025-11-21T12:02:00Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "efecty",
            "errors": []
        }
    }
}

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 80,
    "currency": "COP",
    "order_id": null,
    "payment_method_id": "EY",
    "ticket": {
      "number": "9900002555582"
    }
  }
}

Note:

dLocal posts asynchronous updates to notification_url. Validate signatures per the contract if available, then update the payment status.

Refunds (Full and Partial)

Endpoint

POST v1/transactions/{{transaction_token}}/credit.json

{
    "transaction": {
        "amount": 5000,
        "currency_code": "COP",
        "notification_url": "https://example.com/callback"
    }
}

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-21T13:37:03Z",
        "updated_at": "2025-11-21T13:37:07Z",
        "succeeded": false,
        "state": "processing",
        "token": "1LDR9ZUHToi6IeMSpYyRroZ7obe",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/1LDR9ZUHToi6IeMSpYyRroZ7obe/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1ki0qo0-qbdv1k0d9h2gbf-ahgje1e8955o",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1808,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 5000,
        "local_amount": 50,
        "currency_code": "COP",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-21T13:37:04Z",
            "updated_at": "2025-11-21T13:37:07Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "2erbIHiLaA5TTTYUxDF8zIunXSH"
    }
}

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 50,
    "currency": "COP",
    "order_id": null,
    "payment_method_id": "EY"
  }
}

Status Mapping

Field	Type/Example	Notes
PENDING	Voucher generated; awaiting cash payment	Display voucher; await webhook
PAID	Customer paid at Efecty; funds confirmed by dLocal	Fulfill order; allow refunds
EXPIRED/REJECTED	Payment window expired or cancelled/failed	Release reservation; show new voucher option

Mercado Pago Wallet

Mercado Pago is a popular digital wallet in Colombia and other LATAM markets. This section provides end-to-end technical documentation for integrating Mercado Pago (MP) wallet via dLocal in Colombia.

Key Capabilities

One-shot wallet payments

Customer approves a payment in their Mercado Pago experience (web/app)
dLocal returns a checkout_url (REDIRECT flow) or ticket info (DIRECT) to complete the UX

Wallet tokenization & recurring

Use dLocal’s wallet object in the purchase call
wallet.save = true to receive a wallet token
Future purchases can use wallet.token for recurring charges

Refunds

Full and partial refunds supported once payment is PAID/APPROVED

Constraints

Country: CO (Colombia)
Currency: COP
Minimum amount: 100 COP (per dLocal MP capabilities)
Expiration window for authentication: ~5 minutes (per dLocal)

Create Mercado Pago Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Bearer {access_token}

{
  "payment_method": {
    "payment_method_type": "mercado_pago",
    "country_code": "CO",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "123456789"
  }
}

//Status: 201 Created

{
  "transaction": {
    "token": "Pm3FP24PecDskKeKQ2JX1aBOdv4",
    "created_at": "2025-12-19T13:43:35Z",
    "updated_at": "2025-12-19T13:43:35Z",
    "succeeded": true,
    "transaction_type": "AddPaymentMethod",
    "retained": true,
    "state": "succeeded",
    "message": "Succeeded!",
    "payment_method": {
      "token": "MPwPFqbN34Nc5x4lr9iM2aEcD9u",
      "created_at": "2025-12-19T13:43:35Z",
      "updated_at": "2025-12-19T13:43:35Z",
      "email": "[email protected]",
      "storage_state": "retained",
      "country": "CO",
      "full_name": "Jane Doe",
      "payment_method_type": "mercado_pago",
      "document_id": "123456789",
      "errors": []
    }
  }
}

Create Mercado Pago Purchase

This section covers three core flows: One-shot purchase (no wallet token), One-shot purchase + wallet enrollment (save token) and Recurring Purchase via Wallet Token.

One-Time Purchase (No Recurring / No Token)

Used in case of a standard MP wallet payment, with no tokenization.

POST /v1/gateways/{gateway_token}/purchase.json

{
  "transaction": {
    "payment_method_token": "{{mercado_pago_payment_method_token}}",
    "amount": 5000,
    "currency_code": "COP",
    "callback_url": "https://merchant.example.com/return",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_id": "MP",
        "payment_method_flow": "REDIRECT",
        "country": "CO",
        "wallet": {
          "save": false
        }
      }
    }
  }
}

//Status: 202 Accepted, state = "pending"

{
  "transaction": {
    "token": "2erbIHiLaA5TTTYUxDF8zIunXMP",
    "transaction_type": "OffsitePurchase",
    "state": "pending",
    "amount": 5000,
    "currency_code": "COP",
    "gateway_specific_response_fields": {
      "d_local": {
        "payment_method_id": "MP",
        "payment_method_type": "BANK_TRANSFER",
        "payment_method_flow": "REDIRECT",
        "country": "CO",
        "status": "PENDING"
      }
    },
    "checkout_url": "https://pay.dlocal.com/gmf-apm/payments/N-mercadopago-checkout-id",
    "redirect_url": "https://merchant.example.com/return",
    "callback_url": "https://merchant.example.com/return",
    "message": "Pending"
  }
}

One-Time Purchase + Wallet Enrollment (Save Token)

Used when the customer should complete a one-shot MP payment and dLocal/Spreedly to return a wallet token for future recurring purchases.

{
  "transaction": {
    "payment_method_token": "{{mercado_pago_payment_method_token}}",
    "amount": 5000,
    "currency_code": "COP",
    "callback_url": "https://merchant.example.com/return",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_id": "MP",
        "payment_method_flow": "REDIRECT",
        "country": "CO",
        "wallet": {
          "save": true
        }
      }
    }
  }
}

Behavior:

User completes the payment in MP
On successful approval, dLocal returns a wallet token in its response / notification
Purchase (One Time) + Recurring with save: true → wallet token created

Recurring Purchase via Wallet Token

Used when there is already a valid MP wallet token from a prior enrollment and want to charge the customer without another approval step

{
  "transaction": {
    "payment_method_token": "{{mercado_pago_payment_method_token}}",
    "amount": 5000,
    "currency_code": "COP",
    "description": "200",
    "callback_url": "https://merchant.example.com/return",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_id": "MP",
        "payment_method_flow": "DIRECT",
        "country": "CO",
        "wallet": {
          "token": "{{mp_wallet_token}}",
          "save": false
        }
      }
    }
  }
}

Webhook Notifications

dLocal sends asynchronous updates for MP payments to your notification/callback URL. A typical dLocal webhook payload for a successful APM payment (pattern from Efecty/Nequi) looks like

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9dr-mp123456",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 5000,
    "currency": "COP",
    "order_id": "your-order-id-123",
    "payment_method_id": "MP",
    "wallet": {
      "token": "mp_wallet_token_abc123",
      "name": "Jane Doe"
    }
  }
}

Status Mapping

Status	Meaning (MP wallet)	Recommended Action
`pending`	Payment created; waiting for MP approval/processing	Display pending; wait for webhook; no fulfillment
`paid`/`approved`	Customer authorized, payment captured	Fulfill order; enable service; allow refunds
`rejected`	Customer declined, auth failed, or error in MP	Mark payment failed; prompt retry / new method
`expired`	Authorization window (≈5 min) expired	Mark payment failed; offer to initiate new payment

Refunds (Full and Partial)

Refund One-Time Purchase

POST /v1/transactions/{transaction_token}/credit.json

{
  "transaction": {
    "amount": 5000,
    "currency_code": "COP",
    "callback_url": "https://merchant.example.com/refund-callback"
  }
}

//Typical Response (Processing)

{
  "transaction": {
    "token": "1LDR9ZUHToi6IeMSpYyRroZ7mpR",
    "transaction_type": "Credit",
    "state": "processing",
    "amount": 5000,
    "currency_code": "COP",
    "gateway_specific_response_fields": {
      "d_local": {
        "status": "PENDING",
        "notification_url": "https://merchant.example.com/refund-callback"
      }
    },
    "message": "Processing"
  }
}

//Webhook will confirm success

{
  "event": "payment.updated",
  "data": {
    "id": "REF-15104-x1ki0qo0-xyz-mp",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 5000,
    "currency": "COP",
    "payment_method_id": "MP"
  }
}

Partial Refund on Recurring Purchase

Flow:

Identify the settled recurring charge (transaction token).
Call credit.json with partial amount less than or equal to original.
Track remaining refundable balance for that transaction in the system.

Enforce rules:

No refunds on PENDING / REJECTED / EXPIRED transactions
Sum of refunds ≤ original captured amount

WebPay

Webpay is a card-based payment method in Chile processed through Transbank rails. Through dLocal, you can initiate card purchases with either a merchant-hosted (DIRECT) or dLocal-hosted (REDIRECT) checkout. Authorization is asynchronous in some cases (3DS/challenge or offsite redirect), so your integration must rely on webhooks to finalize state.

Key capabilities

Support for CLP currency and Chile market (dLocal contract-dependent)
Flows: DIRECT (merchant UI) and REDIRECT (dLocal-hosted)
Asynchronous notifications via notification_url webhooks
Refunds: full and partial, post-settlement depending on acquirer rules

Constraints

Country: Chile (CL) only; Currency: CLP (confirm availability per contract)
Payment method identifier: Webpay per dLocal docs (confirm exact ID with your dLocal account)
3DS/step-up may be required; plan for challenge redirects and result callbacks

Integration checklist

dLocal account with Webpay enabled in sandbox and production
Public HTTPS notification_url reachable by dLocal; validate signatures if provided
Redirect/return URLs configured for REDIRECT or 3DS challenge flows
Idempotency keys and safe retry logic for all API calls and webhook processing

Create Webpay Payment Method

First, add a Webpay-capable payment method. Field names and shapes depend on your PCI posture and dLocal setup. Below is an example pattern using a generic add payment method endpoint.

1) API request

Endpoint:

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "webpay",
    "country_code": "CL",
    "full_name": "Juan Perez",
    "email": "[email protected]",
    "document_id": "12345678"
  }
}

{
    "transaction": {
        "token": "1ySK91lmnC0peiqVk4Wht9EClLv",
        "created_at": "2025-11-25T13:12:10Z",
        "updated_at": "2025-11-25T13:12:10Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "RAmwFH0gTuwhKA5xVY7O0eAYJQL",
            "created_at": "2025-11-25T13:12:10Z",
            "updated_at": "2025-11-25T13:12:10Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": "CL",
            "phone_number": null,
            "full_name": "Juan Perez",
            "first_name": "Juan",
            "last_name": "Perez",
            "payment_method_type": "webpay",
            "errors": [],
            "document_id": "5678"
        }
    }
}

Create Webpay Purchase

You can initiate a purchase either as DIRECT (merchant-hosted) or REDIRECT (dLocal-hosted). In both cases, treat the initial response as pending until a webhook arrives with the final status.

When to use DIRECT vs REDIRECT

DIRECT: You collect card details and call the API. Useful if you own the full UX and have PCI scope to handle card data through supported SAQ level or gateway tokenization.
REDIRECT: You obtain a checkout_url and send the customer to dLocal; dLocal manages Webpay UX, including 3DS/step-up.

1) API request (purchase)

Endpoint:

POST /v1/gateways/{{gateway_token}}/purchase.json

{
  "transaction": {
    "payment_method_token": "RAmwFH0gTuwhKA5xVY7O0eAYJQL",
    "amount": 9000,
    "currency_code": "CLP",
    "order_id": "ORD-100045",
    "callback_url": "https://merchant.example.com/dlocal/webhooks",
    "redirect_url": "https://merchant.example.com/return/webpay",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_flow": "REDIRECT",
        "payment_method_id": "WEBPAY",
        "customer_ip": "201.217.101.10"
      }
    }
  }
}

Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-25T13:18:47Z",
        "updated_at": "2025-11-25T13:18:50Z",
        "succeeded": false,
        "state": "pending",
        "token": "WYwjZBGqul2v3zrI8uQoARXftWe",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/WYwjZBGqul2v3zrI8uQoARXftWe/callback",
                "ticket": {
                    "bank_account_type": "CHECKING",
                    "bank_name": "The Best Bank",
                    "bank_code": "SI",
                    "beneficiary_name": "The Best user",
                    "bank_account": "XXXXXXXXX",
                    "bank_account2": "414-00543/6",
                    "bank_account2_label": "Número de cuenta",
                    "beneficiary_document_type": "DOCUMENT",
                    "beneficiary_document": "432432423423",
                    "reference": "9900002563923",
                    "bank_logo": "https://static.dlocal.com/images/providers/SI.png",
                    "redirect_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c18cde19-5090-4653-82c8-4fa7776f7861",
                    "bank_branch": "15",
                    "user_payment_amount": 90,
                    "payment_instruction": "These are the instructions to make the payment",
                    "expiration_date": "2025-12-03T02:59:59.999+0000"
                },
                "country": "CL",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1kibb5o-i9iik1n3t91cbe-mfflur0bt11c",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1338,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 9000,
        "local_amount": null,
        "currency_code": "CLP",
        "reference": "D-15104-x1kibb5o-i9iik1n3t91cbe-mfflur0bt11c",
        "setup_verification": null,
        "expiration_date": "2025-12-03 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T13:18:48Z",
            "updated_at": "2025-11-25T13:18:50Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c18cde19-5090-4653-82c8-4fa7776f7861"
        },
        "shipping_address": {
            "name": "Juan Perez",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/427FGCAX4Q9RZAH7045K3MH7R1/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c18cde19-5090-4653-82c8-4fa7776f7861",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T13:18:48Z",
            "updated_at": "2025-11-25T13:18:50Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c18cde19-5090-4653-82c8-4fa7776f7861"
        },
        "payment_method": {
            "token": "RAmwFH0gTuwhKA5xVY7O0eAYJQL",
            "created_at": "2025-11-25T13:12:10Z",
            "updated_at": "2025-11-25T13:12:10Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Juan Perez",
            "first_name": "Juan",
            "last_name": "Perez",
            "payment_method_type": "webpay",
            "errors": []
        }
    }
}

Key Fields:

Field	Type	Description
payment_method_id	M	The dLocal identifier for Webpay (confirm with dLocal; commonly WEBPAY)
payment_method_flow	M	DIRECT or REDIRECT
callback_url	M	Endpoint to receive asynchronous status updates

3) Webhook notifications (notification_url)

dLocal sends asynchronous updates to your notification_url. Verify authenticity (signature headers/secret per contract) and update the payment state accordingly.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1kibb5o-i9iik1n3t91cbe-mfflur0bt11c",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 9000,
    "currency": "CLP",
    "order_id": null,
    "payment_method_id": "WEBPAY"
  }
}

4) Status mapping

Provider Status	Meaning	Typical Action
PENDING	Authorization/checkout initiated; awaiting customer action or acquirer result	Display progress; wait for webhook; do not fulfill
PAID/APPROVED	Payment approved by Webpay/dLocal	Fulfill order; enable refunds
REJECTED/DECLINED	Payment failed (e.g., insufficient funds, fraud rules)	Notify customer; offer retry or alternative method

Oxxo

Oxxo is a cash payment method in Mexico supported by dLocal. The merchant creates a voucher (ticket) that customers pay at Oxxo convenience stores. The transaction remains pending until payment gateway confirms payment (or it expires).

Key Capabilities

One-step purchase/capture: create a voucher and await offsite cash payment
Notifications: asynchronous updates via notification_url webhooks

Constraints

Country: MX (Mexico) only; Currency: MXN only
Payment method id: OTHERS_CASH_MX
Voucher expiration: Customer can set their own expiration date that is earlier than the default of 10-12 days

Create Oxxo Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Bearer {access_token}

{
  "payment_method": {
    "payment_method_type": "oxxo",
    "country_code": "MX",
    "full_name": "Jane Doe",
    "email": "[email protected]"
  }
}

//Status Code: 201 Created

{
    "transaction": {
        "token": "Ft3FP24PecDskKeKQ2JX1aBOdv4",
        "created_at": "2025-11-18T13:43:35Z",
        "updated_at": "2025-11-18T13:43:35Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": true,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "VkwPFqbN34Nc5x4lr9iM2aEcD9u",
            "created_at": "2025-11-18T13:43:35Z",
            "updated_at": "2025-11-18T13:43:35Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": "MX",
            "phone_number": "8522847035",
            "full_name": "Jane Doe",
            "first_name": "Jane",
            "last_name": "Doe",
            "payment_method_type": "oxxo",
            "errors": []
        }
    }
}

Create Oxxo Purchase (Voucher)

Gateway Specific Fields

"gateway_specific_fields": {
  "d_local": {
    "expiration_date": "2021-06-12T16:07:11.586" //needs a date value in YYYY-MM-DDTHH:MM:SS format.
  }
}

API Request

POST /v1/gateways/{{gateway_token}}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{oxxo_payment_method_token}}",
        "amount": 5000,
        "currency_code": "MXN",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com"
    }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-12-05T22:36:15Z",
        "updated_at": "2025-12-05T22:36:16Z",
        "succeeded": false,
        "state": "pending",
        "token": "01KBRAH94EQQBCN0W5QK749R7D",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {},
        "gateway_specific_response_fields": {
            "d_local": {
                "order_id": 2156053984,
                "additional_info": {
                    "paymentNetwork": "DIESTEL",
                    "rejectionType": "NONE",
                    "responseNetworkMessage": null,
                    "travelAgencyAuthorizationCode": null,
                    "cardType": null,
                    "transactionType": "AUTHORIZATION_AND_CAPTURE"
                }
            }
        },
        "gateway_transaction_id": "d376ebba-0e94-4b7c-9bbd-f156e96cc3e7",
        "sub_merchant_key": null,
        "gateway_latency_ms": 545,
        "warning": null,
        "application_id": null,
        "risk_data": {},
        "merchant_metadata": {},
        "customer_data": {},
        "order_data": {},
        "workflow_key": null,
        "protection_parameters": {},
        "amount": 100,
        "local_amount": null,
        "currency_code": "MXN",
        "reference": "2156053984|d376ebba-0e94-4b7c-9bbd-f156e96cc3e7",
        "setup_verification": null,
        "expiration_date": "2025-12-12 22:59:59 -0600",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "4C8N9XK73Y8RT8P8DGAW2EQ9A4",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "PENDING_TRANSACTION_CONFIRMATION",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-05T22:36:16Z",
            "updated_at": "2025-12-05T22:36:16Z",
            "status": null,
            "checkout_url": "https://sandbox.checkout.dlocal.com/ppp-web-gateway-dlocal/cld/app/v2?vid=2156053984Yd376ebba0e944b7Ya389694f6a5ef9b"
        },
        "shipping_address": {
            "name": "Jane Doe",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/0F7V0EKHB59G586ZKQXM894TR8/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.checkout.dlocal.com/ppp-web-gateway-dlocal/cld/app/v2?vid=2156053984Yd376ebba0e944b7Ya389694f6a5ef9b",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "PENDING_TRANSACTION_CONFIRMATION",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-05T22:36:16Z",
            "updated_at": "2025-12-05T22:36:16Z",
            "status": null,
            "checkout_url": "https://sandbox.checkout.dlocal.com/ppp-web-gateway-dlocal/cld/app/v2?vid=2156053984Yd376ebba0e944b7Ya389694f6a5ef9b"
        },
        "payment_method": {
            "token": "4xDbfAULGPgYHoP198FQUJe84f9",
            "created_at": "2025-12-05T22:36:15Z",
            "updated_at": "2025-12-05T22:36:15Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Jane Doe",
            "first_name": "Jane",
            "last_name": "Doe",
            "payment_method_type": "oxxo",
            "errors": []
        }
    }
}

Refunds on Oxxo Transaction

API Request

POST /v1/transactions/{{transaction_token}}/credit.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

//For Partial Refund

{
  "transaction": {  
    "amount": 150,
    "currency_code": "MXN"
  }
}

//Status Code: 201 Created

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-04-14T11:55:48Z",
        "updated_at": "2026-04-14T11:55:52Z",
        "succeeded": false,
        "state": "processing",
        "token": "01KP5XJ0Z7VD6AEX1FDCPK18GR",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {},
        "gateway_specific_response_fields": {
            "d_local": {
                "calculated_amount": 1.5,
                "notification_url": "https://core.spreedly.com/transaction/01KP5XJ0Z7VD6AEX1FDCPK18GR/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1ktsaq8-b4st16a04h7jn2-cep3mc7odbbo",
        "sub_merchant_key": null,
        "gateway_latency_ms": 4121,
        "warning": null,
        "application_id": null,
        "risk_data": {},
        "merchant_metadata": {},
        "customer_data": {},
        "order_data": {},
        "workflow_key": null,
        "amount": 150,
        "local_amount": 1,
        "currency_code": "MXN",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "6EX6SHB1CS9CMAENBHC09JNZGB",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-04-14T11:55:52Z",
            "updated_at": "2026-04-14T11:55:52Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "01KP5XDR89C3R1RQRDA1Q4W2W2"
    }
}

Webhook Notifications (notification_url)

The gateways posts asynchronous updates to the Spreedly notification_url. After, we have update the transaction we will post updates to the callback_url

PagoEfectivo

PagoEfectivo is a cash payment method in Peru supported by dLocal. The merchant creates a voucher (ticket) that customers pay online or at locations that support PagoEfectivo. The transaction remains pending until payment gateway confirms payment (or it expires).

Key Capabilities

One-step purchase/capture: create a voucher and await offsite cash payment
Notifications: asynchronous updates via notification_url webhooks
Dlocal

Flows: DIRECT (merchant-hosted), REDIRECT (dLocal-hosted)
Refunds: full and partial refunds after payment is confirmed

Constraints

Country: PE (Peru) only; Currency: PEN only
Payment method id: EF (dLocal)
Voucher expiration: dLocal: configurable up to 5 days (actual policy may vary by contract)

Integration Checklist

dLocal account and sandbox credentials ready
notification_url reachable from dLocal for webhooks (this is set by Spreedly)
Callback/return URL configured if using REDIRECT
Server clock and idempotency safeguards to handle async updates

Create PagoEfectivo Payment Method

1) API Request

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "pago_efectivo",
    "country_code": "PE",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "12345678"
  }
}

Status Code: 201 Created

{
    "transaction": {
        "token": "Ft3FP24PecDskKeKQ2JX1aBOdv4",
        "created_at": "2025-11-18T13:43:35Z",
        "updated_at": "2025-11-18T13:43:35Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": true,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "VkwPFqbN34Nc5x4lr9iM2aEcD9u",
            "created_at": "2025-11-18T13:43:35Z",
            "updated_at": "2025-11-18T13:43:35Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "PE",
            "phone_number": "8522847035",
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "pago_efectivo",
            "errors": [],
            "document_id": "7737"
        }
    }
}

Response Fields:

payment-method -> token (string): Unique identifier for the payment method

Create PagoEfectivo Purchase (Voucher)

Gateway Specific Fields

payment_method_flow which can have a value of DIRECT and REDIRECT. Spreedly defaults to DIRECT.

DIRECT: you call dLocal’s API and render the returned ticket/barcode and reference number in your UI.

REDIRECT: you call API to obtain a checkout URL and send the customer to dLocal’s hosted page; dLocal displays the voucher and instructions.

"gateway_specific_fields": {
  "dlocal": {
    "payment_method_flow": "DIRECT"
  }
}

1) API Request (Purchase)

Endpoint:

POST /v1/gateways/{{gateway_token}}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{pago_efectivo_payment_method_token}}",
        "amount": 5000,
        "currency_code": "PEN",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com"
    }
}

Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-21T13:25:03Z",
        "updated_at": "2025-11-21T13:25:08Z",
        "succeeded": false,
        "state": "pending",
        "token": "2erbIHiLaA5TTTYUxDF8zIunXSH",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/2erbIHiLaA5TTTYUxDF8zIunXSH/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002555458",
                    "expiration_date": "2025-11-29T02:59:59.999+0000",
                    "id": "9900002555458",
                    "barcode": "963367063",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "image_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719",
                    "amount": 50
                },
                "country": "PE",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1ki0q1g-kppkmvgu5h3b1e-bfd4bmp7rquc",
        "sub_merchant_key": null,
        "gateway_latency_ms": 910,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "PEN",
        "reference": "D-15104-x1ki0q1g-kppkmvgu5h3b1e-bfd4bmp7rquc",
        "setup_verification": null,
        "expiration_date": "2025-11-29 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-21T13:25:04Z",
            "updated_at": "2025-11-21T13:25:07Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719"
        },
        "shipping_address": {
            "name": "Spreedly GWI",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/427FGCAX4Q9RZAH7045K3MH7R1/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-21T13:25:04Z",
            "updated_at": "2025-11-21T13:25:07Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-f7872832-c973-40f4-a9f6-a0b0c6786719"
        },
        "payment_method": {
            "token": "VkwPFqbN34Nc5x4lr9iM2aEcD9u",
            "created_at": "2025-11-18T13:43:35Z",
            "updated_at": "2025-11-21T12:02:00Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "pago_efectivo",
            "errors": []
        }
    }
}

Key fields:

callback_url: where Spreedly will posts status updates

redirect_url: where Spreedly will redirect the user

3) Webhook Notifications (notification_url)

The gateways posts asynchronous updates to the Spreedly notification_url. After, we have update the transaction we will post updates to the callback_url. Validate signatures per your contract if available, then update payment state in your system.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 80,
    "currency": "PEN",
    "order_id": null,
    "payment_method_id": "EF",
    "ticket": {
      "number": "9900002555582"
    }
  }
}

4) Status Mapping

Use this mapping to drive business logic (show voucher, confirm order, allow refunds).

Provider Status	Meaning	Typical Action
PENDING	Voucher generated; awaiting cash payment	Display voucher; await webhook
PAID	Customer paid at PagoEfectivo; funds confirmed by dLocal	Fulfill order; allow refunds
EXPIRED/REJECTED	Payment window expired or cancelled/failed	Release reservation; show new voucher option

Refunds (Full and Partial)

Refunds can be initiated only after the payment is confirmed as PAID. Attempting to refund PENDING or EXPIRED payments should fail.

1) API Request (Refund)

Endpoint:

POST v1/transactions/{{transaction_token}}/credit.json

{
    "transaction": {
        "amount": 5000,
        "currency_code": "PEN",
        "notification_url": "https://example.com"
    }
}

Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-21T13:37:03Z",
        "updated_at": "2025-11-21T13:37:07Z",
        "succeeded": false,
        "state": "processing",
        "token": "1LDR9ZUHToi6IeMSpYyRroZ7obe",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/1LDR9ZUHToi6IeMSpYyRroZ7obe/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1ki0qo0-qbdv1k0d9h2gbf-ahgje1e8955o",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1808,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 5000,
        "local_amount": 50,
        "currency_code": "PEN",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-21T13:37:04Z",
            "updated_at": "2025-11-21T13:37:07Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "2erbIHiLaA5TTTYUxDF8zIunXSH"
    }
}

3) Webhook Notifications (notification_url)

dLocal posts asynchronous updates to your notification_url. Validate signatures per your contract if available, then update payment state in your system.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 50,
    "currency": "PEN",
    "order_id": null,
    "payment_method_id": "EF"
  }
}

API Field Reference

dLocal Field	Type/Example	Notes
payment_method_id	"EF"	Use EF per dLocal docs
payment_method_flow	"DIRECT" \\| "REDIRECT"	Choose UX pattern; impacts response
notification_url	https://merchant.example.com/notifications/dlocal	Receive async status updates. This will be a Spreedly custom URL

PagoFacil

PagoFácil is a cash payment method where you create a voucher that the customer pays in person at an authorized location. The transaction remains pending until dLocal confirms the cash payment (or the voucher expires). You can implement either a DIRECT flow (render the voucher within your application) or a REDIRECT flow (send the customer to a dLocal-hosted voucher page).

Key Capabilities

One-step offsite cash purchase: create voucher, wait for payment confirmation via webhook
Flows: DIRECT (merchant-hosted UI) and REDIRECT (dLocal-hosted checkout)
Asynchronous notifications via notification_url webhooks
Refunds: full and partial (after payment reaches PAID)

Constraints

Supported market: Argentina (AR); currency: ARS
Payment Method Identifier (dLocal): use the provider-specific PagoFácil ID per your dLocal contract (e.g., PF); confirm with your dLocal account team
Voucher expiration: defined by dLocal/contract; ensure UI communicates the pay-by date and back end handles expiry via webhooks

Integration Checklist

dLocal sandbox and production credentials ready; confirm PagoFácil is enabled on your account
Publicly reachable notification_url (HTTPS) for webhooks; validate any signatures as per dLocal guidance
Return/callback URLs configured if using REDIRECT flow
Implement idempotency and replay-safe webhook processing

Create PagoFácil Payment Method

Endpoint:

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "pagofacil",
    "country_code": "AR",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "20123456789"
  }
}

{
    "transaction": {
        "token": "60Hj34GN65uloOyy4diVB06JQf4",
        "created_at": "2025-11-25T11:58:34Z",
        "updated_at": "2025-11-25T11:58:34Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": true,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "2YWHSZX5JhQZ2xHlL9OZUPP1QRB", //Store the returned payment method token securely to reference it for creating the voucher purchase
            "created_at": "2025-11-25T11:58:34Z",
            "updated_at": "2025-11-25T11:58:34Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "AR",
            "phone_number": "8522847035",
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "pago_facil",
            "errors": [],
            "document_id": "78"
        }
    }
}

Field	M/O	Description
payment_method_type	M	must be "pagofacil" (consult your processor mapping)
country_code	M	ISO-3166; use the market where PagoFácil is available for your account (e.g., AR)

Create PagoFácil Purchase (Voucher)

When to use DIRECT vs REDIRECT

DIRECT: Call the API and render the voucher (barcode/number, reference, instructions) in your application. Best when you control the UX and receipt printing.
REDIRECT: Obtain a checkout URL and send the customer to dLocal-hosted page where the voucher is displayed and instructions are managed by dLocal.

1) API Request (Purchase)

Endpoint:

POST /v1/gateways/{gateway_token}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{pagofacil_payment_method_token}}",
        "amount": 5100,
        "currency_code": "ARS",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com",
        "gateway_specific_fields": {
            "dlocal": {
                "payment_method_flow": "DIRECT"
            }
        }
    }
}

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-25T12:00:56Z",
        "updated_at": "2025-11-25T12:01:01Z",
        "succeeded": false,
        "state": "pending",
        "token": "T0ODCMJmZ4mgmhyXtJzWvCj0TXI",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/T0ODCMJmZ4mgmhyXtJzWvCj0TXI/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002563379",
                    "expiration_date": "2025-12-03T02:59:59.999+0000",
                    "id": "9900002563379",
                    "barcode": "454193228",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "image_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-a6328c16-45ce-46bb-9f8d-e56c5d0bed01",
                    "amount": 51.0
                },
                "country": "AR",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1kib6jp-jm9enfplk14938-5n09ije73le0",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1195,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5100,
        "local_amount": null,
        "currency_code": "ARS",
        "reference": "D-15104-x1kib6jp-jm9enfplk14938-5n09ije73le0",
        "setup_verification": null,
        "expiration_date": "2025-12-03 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T12:00:58Z",
            "updated_at": "2025-11-25T12:01:01Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-a6328c16-45ce-46bb-9f8d-e56c5d0bed01"
        },
        "shipping_address": {
            "name": "amit e",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-a6328c16-45ce-46bb-9f8d-e56c5d0bed01",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T12:00:58Z",
            "updated_at": "2025-11-25T12:01:01Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-a6328c16-45ce-46bb-9f8d-e56c5d0bed01"
        },
        "callback_url": null,
        "payment_method": {
            "token": "N6Uaj3UsEaXkb4I95cj0UPuAZ37",
            "created_at": "2025-11-25T12:00:56Z",
            "updated_at": "2025-11-25T12:00:57Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "amit e",
            "first_name": "amit",
            "last_name": "e",
            "payment_method_type": "pago_facil",
            "errors": []
        }
    }
}

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1kib6jp-jm9enfplk14938-5n09ije73le0",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 5100,
    "currency": "ARS",
    "payment_method_id": "PF",
    "ticket": { "number": "9900002563379" }
  }
}

Field	M/O	Description
payment_method_id	M	PagoFácil method code per dLocal (commonly PF); confirm exact code with dLocal
payment_method_flow	M	DIRECT or REDIRECT; affects whether you must render voucher details vs use checkout_url
callback_url / notification_url	M	endpoint for asynchronous updates

3) Status Mapping

Provider Status	Meaning	Typical Action
PENDING	Voucher generated; awaiting cash payment at PagoFácil outlet	Display voucher and pay-by instructions; wait for webhook
PAID	Customer completed cash payment; dLocal confirmed	Fulfill order; enable refunds
EXPIRED / REJECTED	Voucher expired or failed	Release reservation; offer new voucher

Refunds (Full and Partial)

Refunds are available only after the voucher reaches PAID. Attempting to refund while PENDING or after EXPIRED should fail. Support multiple partial refunds up to the captured amount.

1) API Request (Refund)

Endpoint:

POST /v1/transactions/{transaction_token}/credit.json

{
  "transaction": {
    "amount": 5100,
    "currency_code": "ARS",
    "notification_url": "https://merchant.example.com/dlocal/refunds/callback"
  }
}

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-25T12:05:15Z",
        "updated_at": "2025-11-25T12:05:20Z",
        "succeeded": false,
        "state": "processing",
        "token": "LbeoPE2dTBlabyvaG7eI72LqYJ8",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/LbeoPE2dTBlabyvaG7eI72LqYJ8/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kib6rt-j041q3ounl3rv8-pjqelgicpd98",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2026,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 5100,
        "local_amount": 51,
        "currency_code": "ARS",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T12:05:17Z",
            "updated_at": "2025-11-25T12:05:20Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "T0ODCMJmZ4mgmhyXtJzWvCj0TXI"
    }
}

2) Refund Webhook (example)

{
  "event": "payment.updated",
  "data": {
    "id": "Refund_Txn_98765",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 5100,
    "currency": "ARS",
    "payment_method_id": "PF"
  }
}

API Field Reference (PagoFácil/dLocal)

Field	Type/Example	Notes
payment_method_id	"PF"	Confirm exact value with your dLocal account; identifies PagoFácil
payment_method_flow	"DIRECT" \\| "REDIRECT"	Determines whether you render the voucher vs using dLocal-hosted page
notification_url	https://merchant.example.com/notifications/dlocal	Endpoint to receive async updates (PENDING, PAID, EXPIRED)

PSE

PSE (Pagos Seguros en Línea) is an online bank transfer payment system in Colombia that enables customers to make payments directly from their bank accounts in real time. When integrated through dLocal, PSE functions as a local offsite payment method (LPM). Customers are redirected from the merchant’s checkout to their selected bank’s portal to authorize the payment, after which the transaction result is communicated back to dLocal via asynchronous notifications.

Create Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
    "payment_method": {
        "email": "[email protected]",
        "payment_method_type": "pse",
        "full_name": "User- example test",
        "document_id": "12345678909",
        "country": "CO",
        "zip": "12345",
        "address1": "sample address test",
        "city": "Rio",
        "state": "CE",
        "phone_number": "1234567890"
    }
}

//Status Code: 201 Created

{
    "transaction": {
        "token": "LZ9TWyf8dfYwDOcFdTV2bGX0hUN",
        "created_at": "2025-12-16T11:04:43Z",
        "updated_at": "2025-12-16T11:04:43Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {                  
            "token": "W8JFqUoSWUj6HhP3r11BER2Semh",  //Unique identifier for the payment method
            "created_at": "2025-12-16T11:04:43Z",
            "updated_at": "2025-12-16T11:04:43Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "sample address test",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "CO",
            "phone_number": "1234567890",
            "full_name": "User- example test",
            "first_name": "User- example",
            "last_name": "test",
            "payment_method_type": "pse",
            "errors": [],
            "document_id": "8909"
        }
    }
}

Create PSE Purchase

API Request

POST /v1/gateways/{{gateway_token}}/purchase.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "transaction": {
      "payment_method_token": "{{payment_method_token_pse}}",
      "amount": 5000,
      "currency_code": "COP",
      "callback_url": "https://example.com",
      "redirect_url": "https://example.com",
      "gateway_specific_fields": {
          "d_local": {
            "bank_id": "1051"
          }
      }
  }
}

//Status Code: 201 Created

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-02-11T06:16:26Z",
        "updated_at": "2026-02-11T06:16:27Z",
        "succeeded": false,
        "state": "pending",
        "token": "WDNU9gXowvg5nCTC7uJD2GlUorc",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
              "bank_id": "1051"
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://ppathak.ngrok.dev/transactions/WDNU9gXowvg5nCTC7uJD2GlUorc/callback",
                "country": "CO",
                "status": "PENDING",
                "redirect_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-b57dec30-c748-47db-b2e5-1d55e015f4f2"
            }
        },
        "gateway_transaction_id": "R-15104-x1koo7lq-8qtftm8rvh1235-c1gk43k8ufb4",
        "sub_merchant_key": null,
        "gateway_latency_ms": 818,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "COP",
        "reference": "R-15104-x1koo7lq-8qtftm8rvh1235-c1gk43k8ufb4",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "617WTNXM8D9PPRBH5MH1D9XDSW",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-02-11T06:16:27Z",
            "updated_at": "2026-02-11T06:16:27Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-b57dec30-c748-47db-b2e5-1d55e015f4f2"
        },
        "shipping_address": {
            "name": "User- shubham wore test",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/22VMCYH7RK846THX8JMVCFJZ7F/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-b57dec30-c748-47db-b2e5-1d55e015f4f2",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-02-11T06:16:27Z",
            "updated_at": "2026-02-11T06:16:27Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-b57dec30-c748-47db-b2e5-1d55e015f4f2"
        },
        "payment_method": {
            "token": "PyG0lE465QXI5xyosIShxLieaW9",
            "created_at": "2026-02-11T05:51:34Z",
            "updated_at": "2026-02-11T05:51:34Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "User- shubham wore test",
            "first_name": "User- shubham wore",
            "last_name": "test",
            "payment_method_type": "pse",
            "errors": []
        }
    }
}

{
  "transaction": {
      "on_test_gateway": true,
      "created_at": "2025-12-16T11:10:21Z",
      "updated_at": "2025-12-16T11:10:28Z",
      "succeeded": false,
      "state": "failed",
      "token": "9XAbcP9kLmEwYt7qRz21",
      "transaction_type": "OffsitePurchase",
      "gateway_transaction_id": "D-15104-x1kk2f6l-b0619c85ul4g7e-failed",
      "gateway_latency_ms": 842,
      "amount": 168,
      "currency_code": "USD",
      "reference": "D-15104-x1kk2f6l-b0619c85ul4g7e-failed",
      "gateway_specific_fields": {
          "d_local": {
              "bank_id": "1051"
          }
      },
      "gateway_specific_response_fields": {
          "d_local": {
              "country": "CO",
              "status": "REJECTED",
              "error_code": "BANK_DECLINED",
              "error_message": "The transaction was rejected by the bank"
          }
      },
      "message_key": "messages.transaction_failed",
      "message": "Failed",
      "gateway_type": "d_local",
      "response": {
          "success": false,
          "message": "The payment was rejected by the bank.",
          "pending": false,
          "result_unknown": false,
          "cancelled": false,
          "error_code": "BANK_DECLINED",
          "error_detail": "Customer bank declined the transaction",
          "created_at": "2025-12-16T11:10:22Z",
          "updated_at": "2025-12-16T11:10:28Z"
      },
      "redirect_url": "https://example.com",
      "callback_url": "https://example.com",
      "payment_method": {
          "token": "W8JFqUoSWUj6HhP3r11BER2Semh",
          "payment_method_type": "pse",
          "email": "[email protected]",
          "full_name": "User- shubham wore test"
    }
  }
}

Key Fields:

Field	Type	Description
bank_id	M	ID of the bank selected by the customer. This value is used to redirect the customer to their respective bank page.

Refunds (Full and Partial)

Refunds can be initiated only after the payment is confirmed as PAID. Attempting to refund PENDING or EXPIRED payments should fail.

API Request

POST v1/transactions/{{transaction_token}}/credit.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
    "transaction": {
        "amount": 4360,
        "currency_code": "COP",
        "notification_url": "https://example.com/callback"
    }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-02-11T07:07:00Z",
        "updated_at": "2026-02-11T07:07:04Z",
        "succeeded": false,
        "state": "processing",
        "token": "9U1RUHw3ozNbcA4JiSE5rSP5n0j",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "http://core.spreedly.test/transaction/9U1RUHw3ozNbcA4JiSE5rSP5n0j/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kooakm-1iecq58jb94u1d-v7e04m6e0iuo",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2404,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 4360,
        "local_amount": 44,
        "currency_code": "COP",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "617WTNXM8D9PPRBH5MH1D9XDSW",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-02-11T07:07:03Z",
            "updated_at": "2026-02-11T07:07:04Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "IuOhD13oDXDsq26kBhvu9ji8iWF"
    }
}

Webhook Notifications

dLocal posts asynchronous updates to your notification_url. Validate signatures per your contract if available, then update payment state in your system.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 43.6,
    "currency": "COP",
    "order_id": null,
    "payment_method_id": "PC"
  }
}

Transaction States Mapping

State	Meaning
PENDING	Payment has been created and the customer has been redirected to their bank to complete the PSE payment
APPROVED	Payment completed successfully and confirmed by the bank
FAILED	Payment was rejected, canceled by the customer, or expired

RapiPago

RapiPago enables cash payments in Argentina. Your system creates a voucher (“ticket”) that the customer pays at a RapiPago location. The payment stays pending until dLocal confirms it asynchronously via webhook. You can implement either a DIRECT flow (you render the voucher details) or a REDIRECT flow (dLocal hosts the voucher page).

Key Capabilities

One-step offsite cash purchase: create voucher, await webhook confirmation
Flows: DIRECT (merchant-hosted UI) or REDIRECT (dLocal-hosted voucher)
Asynchronous notifications via notification_url webhooks
Refunds: full and partial after payment is confirmed

Constraints

Market: AR (Argentina) only; Currency: ARS
dLocal payment_method_id: RP (RapiPago) – confirm with your dLocal account/contract
Voucher expiration: commonly up to 28 days (contract-dependent). Handle expiry via webhooks and communicate the pay-by date in your UX.

Integration Checklist

dLocal sandbox and production credentials with RapiPago enabled
Public, secure notification_url (HTTPS) and signature validation if available
Return/callback URLs configured if using REDIRECT flow
Idempotency on server-side; replay-safe webhook processing with audit logs

Create RapiPago Payment Method

1) API Request

Endpoint:

POST /v1/payment_methods.json

{
  "payment_method": {
    "payment_method_type": "rapipago",
    "country_code": "AR",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "20123456789"
  }
}

{
    "transaction": {
        "token": "4PrSWva4ezLcT0bmr8cGv3aY3XV",
        "created_at": "2025-11-25T12:28:54Z",
        "updated_at": "2025-11-25T12:28:54Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": true,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "99nL7LceQxhcCy2Tb4X9a3IJGWB",
            "created_at": "2025-11-25T12:28:54Z",
            "updated_at": "2025-11-25T12:28:54Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "AR",
            "phone_number": "8522847035",
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "rapi_pago",
            "errors": [],
            "document_id": "6789"
        }
    }
}

Field	M/O	Description
payment_method_type	M	must be rapipago (matches the Spreedly/dLocal mapping for RapiPago).
document_id	M	customer’s tax ID (DNI/CUIL/CUIT) required by dLocal for AR cash vouchers.

Create RapiPago Purchase (Voucher)

When to use DIRECT vs REDIRECT

DIRECT: call the API and render the ticket number/barcode and instructions in your UI.
REDIRECT: obtain a checkout_url and send the customer to dLocal’s hosted voucher page.

1) API Request (Purchase)

Endpoint:

POST /v1/gateways/{{gateway_token}}/purchase.json

{
  "transaction": {
    "payment_method_token": "99nL7LceQxhcCy2Tb4X9a3IJGWB",
    "amount": 10000,
    "currency_code": "ARS",
    "callback_url": "https://merchant.example.com/dlocal/callbacks",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "dlocal": {
        "payment_method_flow": "DIRECT",
        "payment_method_id": "RP"
      }
    }
  }
}

Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-25T12:30:32Z",
        "updated_at": "2025-11-25T12:30:36Z",
        "succeeded": false,
        "state": "pending",
        "token": "XDpTiTOj7j6Ggfe7iqJbEbH6y2N",
        "transaction_type": "OffsitePurchase",
        "order_id": "34545sk3483kqw0",
        "ip": null,
        "description": "Tshirt",
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/XDpTiTOj7j6Ggfe7iqJbEbH6y2N/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002563723",
                    "expiration_date": "2025-12-03T02:59:59.999+0000",
                    "id": "9900002563723",
                    "barcode": "805578508",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "image_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-8ae7c247-b704-4bef-8464-6b5fd7ef58e9",
                    "amount": 100.0
                },
                "country": "AR",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1kib8b8-slbfdtede96572-6elrbhbtv6ic",
        "sub_merchant_key": null,
        "gateway_latency_ms": 997,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 10000,
        "local_amount": null,
        "currency_code": "ARS",
        "reference": "D-15104-x1kib8b8-slbfdtede96572-6elrbhbtv6ic",
        "setup_verification": null,
        "expiration_date": "2025-12-03 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T12:30:33Z",
            "updated_at": "2025-11-25T12:30:36Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-8ae7c247-b704-4bef-8464-6b5fd7ef58e9"
        },
        "shipping_address": {
            "name": "Spreedly GWI",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/427FGCAX4Q9RZAH7045K3MH7R1/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-8ae7c247-b704-4bef-8464-6b5fd7ef58e9",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T12:30:33Z",
            "updated_at": "2025-11-25T12:30:36Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-8ae7c247-b704-4bef-8464-6b5fd7ef58e9"
        },
        "payment_method": {
            "token": "99nL7LceQxhcCy2Tb4X9a3IJGWB",
            "created_at": "2025-11-25T12:28:54Z",
            "updated_at": "2025-11-25T12:28:54Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "retained",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Spreedly GWI",
            "first_name": "Spreedly",
            "last_name": "GWI",
            "payment_method_type": "rapi_pago",
            "errors": []
        }
    }
}

{
  "event": "payment.updated",
  "data": {
    "id": "D-AR-12345",
    "status": "SUCCESS",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 80.0,
    "currency": "ARS",
    "payment_method_id": "RP",
    "ticket": { "number": "9900002567781" }
  }
}

Field	Type/Example	Description
payment_method_id	M	RP (RapiPago) per dLocal
payment_method_flow	M	payment_method_flow: DIRECT or REDIRECT; affects whether you render ticket vs send shopper to checkout_url.
callback_url	M	where dLocal posts asynchronous status updates.

2) Status Mapping and Actions

Provider Status	Meaning	Typical Action
PENDING	Voucher created; awaiting cash payment at RapiPago	Display voucher; wait for webhook
SUCCESS/PAID	Customer paid; funds confirmed by dLocal	Fulfill order; enable refunds
EXPIRED/FAILED/REJECTED	Voucher expired or payment failed/cancelled	Release reservation; allow voucher regeneration

Refunds (Full and Partial)

Refunds can be initiated only after the payment is confirmed as PAID. Attempting to refund PENDING or EXPIRED payments should fail.

1) API Request (Refund)

Endpoint:

POST v1/transactions/{{transaction_token}}/credit.json

{
  "transaction": {
    "amount": 10000,
    "currency_code": "ARS",
    "notification_url": "https://merchant.example.com/dlocal/refund-callbacks"
  }
}

Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-11-25T12:34:12Z",
        "updated_at": "2025-11-25T12:34:14Z",
        "succeeded": false,
        "state": "processing",
        "token": "DKuGTmdRL15L8PCcR0bybM89CXE",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://9ea5dc2468af.ngrok.app/transaction/DKuGTmdRL15L8PCcR0bybM89CXE/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kib8i6-14gsvlsf390jtb-02c94u79m81k",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2085,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 10000,
        "local_amount": 100,
        "currency_code": "ARS",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "57MDGFMQFQ989BJRMYPMD47KZ3",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-11-25T12:34:14Z",
            "updated_at": "2025-11-25T12:34:14Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "XDpTiTOj7j6Ggfe7iqJbEbH6y2N"
    }
}

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9d782",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 100,
    "currency": "ARS",
    "order_id": null,
    "payment_method_id": "RP"
  }
}

API Field Reference

Field	Type/Example	Notes
payment_method_id	"RP"	Set to RapiPago in dLocal
payment_method_flow	"DIRECT" \\| "REDIRECT"	Determines UI ownership and response content
notification_url	https://merchant.example.com/notifications/dlocal	Receives async updates for payment and refund

SPEI

SPEI is a bank transfer payment method in Mexico supported by dLocal. The merchant initiates a SPEI payment instruction. The customer completes the transfer from their bank using the provided reference details. The transaction remains pending until dLocal confirms settlement (or it expires/rejects). Flows can be DIRECT (merchant-hosted) or REDIRECT (dLocal-hosted).

Constraints

Country: MX (Mexico) only; Currency: MXN only (per typical dLocal SPEI terms)
Payment method id: often SPEI/PE (per dLocal), final code may vary by contract
Expiration: payment window set by dLocal; after expiration, payment cannot be completed

Create SPEI Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "spei",
    "country_code": "MX",
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "document_id": "ABC1234567"
  }
}

//Status Code: 201 Created

{
  "transaction": {
    "token": "Ft3FP24PecDskKeKQ2JX1aBOdv4",
    "created_at": "2025-11-18T13:43:35Z",
    "updated_at": "2025-11-18T13:43:35Z",
    "succeeded": true,
    "transaction_type": "AddPaymentMethod",
    "retained": true,
    "state": "succeeded",
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "payment_method": {
      "token": "VkwPFqbN34Nc5x4lr9iM2aEcD9u",
      "created_at": "2025-11-18T13:43:35Z",
      "updated_at": "2025-11-18T13:43:35Z",
      "email": "[email protected]",
      "data": null,
      "storage_state": "retained",
      "test": false,
      "metadata": null,
      "callback_url": null,
      "address1": "Av. Siempre Viva 123",
      "address2": null,
      "city": "CDMX",
      "state": "CMX",
      "zip": "01234",
      "country": "MX",
      "phone_number": "+52 55 0000 0000",
      "full_name": "Spreedly GWI",
      "first_name": "Spreedly",
      "last_name": "GWI",
      "payment_method_type": "spei",
      "errors": [],
      "document_id": "ABC1234567"
    }
  }
}

Create SPEI Purchase

DIRECT: dLocal is called via Spreedly and render the returned SPEI transfer details (bank, CLABE/reference) in your UI.

REDIRECT: a checkout_url is obtained and sends the customer to dLocal’s hosted page; dLocal displays instructions and references.

API Request

POST /v1/gateways/{{gateway_token}}/purchase.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "transaction": {
    "payment_method_token": "{{spei_payment_method_token}}",
    "amount": 10000,
    "currency_code": "MXN",
    "callback_url": "https://merchant.example.com/callback",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_flow": "DIRECT"
      }
    }
  }
}

//Status Code: 201 Created

{
  "transaction": {
    "on_test_gateway": true,
    "created_at": "2025-11-21T13:25:03Z",
    "updated_at": "2025-11-21T13:25:08Z",
    "succeeded": false,
    "state": "pending",
    "token": "2erbIHiLaA5TTTYUxDF8zIunXSH",
    "transaction_type": "OffsitePurchase",
    "amount": 10000,
    "currency_code": "MXN",
    "gateway_specific_response_fields": {
      "d_local": {
        "notification_url": "https://callback.merchant.example.com/transaction/2erbIHiLaA5TTTYUxDF8zIunXSH/callback",
        "spei": {
          "reference": "0123456789",
          "clabe": "032180000118359719",
          "beneficiary_name": "DLOCAL MEXICO",
          "bank_name": "STP",
          "expiration_date": "2025-11-29T02:59:59.999+0000"
        },
        "country": "MX",
        "status": "PENDING"
      }
    },
    "gateway_transaction_id": "D-15104-abcdef-ghijk",
    "message_key": "messages.transaction_pending",
    "message": "Pending",
    "redirect_url": "https://merchant.example.com/return",
    "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-4790dbcb-6900-46c7-b16e-788cb332fc3a",
    "callback_url": "https://merchant.example.com/callback"
  }
}

Webhook Notifications

dLocal posts asynchronous updates to your notification_url.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 100,
    "currency": "MXN",
    "order_id": null,
    "payment_method_id": "SPEI",
    "spei": {
      "reference": "0123456789"
    }
  }
}

Status Mapping

Provider Status	Meaning	Typical Action
PENDING	Instruction created; awaiting customer bank transfer	Display instructions; await webhook
PAID	Transfer received and confirmed by dLocal	Fulfill order; allow refunds
EXPIRED/REJECTED	Payment window expired or failed	Release reservation; offer new instruction

Refunds (Full and Partial)

Refunds can be initiated only after the payment is confirmed as PAID. Attempting to refund PENDING or EXPIRED/REJECTED payments should fail. Support multiple partial refunds and track remaining refundable balance to prevent over-refund.

For partial refunds, include the "amount" in the payload. For full refunds, omit the amount.

API Request

POST /v1/transactions/{{transaction_token}}/credit.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "transaction": {
    "amount": 5000,
    "currency_code": "MXN",
    "notification_url": "https://merchant.example.com/callback",
  }
}

//Status Code: 201 Created

{
  "transaction": {
    "on_test_gateway": true,
    "created_at": "2025-11-21T13:37:03Z",
    "updated_at": "2025-11-21T13:37:07Z",
    "succeeded": false,
    "state": "processing",
    "token": "1LDR9ZUHToi6IeMSpYyRroZ7obe",
    "transaction_type": "Credit",
    "amount": 5000,
    "local_amount": 100,
    "currency_code": "MXN",
    "gateway_specific_response_fields": {
      "d_local": {
        "notification_url": "https://callback.merchant.example.com/transaction/1LDR9ZUHToi6IeMSpYyRroZ7obe/callback",
        "status": "PENDING"
      }
    },
    "gateway_transaction_id": "REF-15104-xyz",
    "message_key": "messages.transaction_processing",
    "message": "Processing",
    "reference_token": "2erbIHiLaA5TTTYUxDF8zIunXSH"
  }
}

Webhook notifications

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9drojl9411a13-hlfdb8i9fd88",
    "status": "SUCCESS",
    "status_detail": "Refund succeeded",
    "status_code": "200",
    "amount": 50,
    "currency": "MXN",
    "order_id": null,
    "payment_method_id": "SPEI"
  }
}

API field reference

Field	Type/Example	Notes
payment_method_id	"SPEI"	Use SPEI per dLocal docs
payment_method_flow	"DIRECT" \\| "REDIRECT"	Choose UX pattern; impacts response shape and checkout_url usage
notification_url	https://merchant.example.com/notifications/dlocal	Receive async status updates from dLocal

Boleto Bancario

Boleto Bancario is a widely used cash-based / ticket payment method in Brazil, where customers pay using a generated boleto (bank slip) through online banking, mobile apps, ATMs, or authorized payment locations.

Constraints

Country: BR (Brazil) only; Currency: BRL only
Payment method id: BL
Voucher expiration: Up to 8 days

Create Boleto Bancario Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
    "payment_method": {
        "email": "[email protected]",
        "payment_method_type": "boleto_bancario",
        "full_name": "test boleto",
        "document_id": "57534567889",
        "phone_number": "8522843035",
        "country": "BR"
    }
}

//Status Code: 201 Created

{
    "transaction": {
        "token": "0RS50X2BT893VTXH87GRFXPCAT",
        "created_at": "2025-12-29T02:56:46Z",
        "updated_at": "2025-12-29T02:56:46Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "OrCZUNCvTiMJEteya7LgiJF7QnX",
            "created_at": "2025-12-29T02:56:46Z",
            "updated_at": "2025-12-29T02:56:46Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": "BR",
            "phone_number": "8522843035",
            "full_name": "test boleto",
            "first_name": "test",
            "last_name": "boleto",
            "payment_method_type": "boleto_bancario",
            "errors": [],
            "document_id": "5678"
        }
    }
}

Create Boleto Bancario Purchase (Voucher)

API Request

POST /v1/gateways/{{gateway_token}}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{payment_method_token}}",
        "amount": 5000,
        "currency_code": "BRL"
        "callback_url": "https:example.com",
        "redirect_url": "https:example.com"
    }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-05T05:22:56Z",
        "updated_at": "2026-01-05T05:23:00Z",
        "succeeded": false,
        "state": "pending",
        "token": "IGDdMePOyrFSrDli1p3YhcCxRby",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "http://core.spreedly.test/transaction/IGDdMePOyrFSrDli1p3YhcCxRby/callback",
                "ticket": {
                    "type": "CUSTOM",
                    "format": "Code 128",
                    "number": "9900002663603",
                    "expiration_date": "2026-01-13T02:59:59.999+0000",
                    "id": "9900002663603",
                    "barcode": "243073620",
                    "company_name": "The Best Company",
                    "company_id": "112903",
                    "amount": 50
                },
                "country": "BR",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1klmilh-128u3nmkqh5gr3-dt58r2cce3gs",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1349,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5000,
        "local_amount": null,
        "currency_code": "BRL",
        "reference": "D-15104-x1klmilh-128u3nmkqh5gr3-dt58r2cce3gs",
        "setup_verification": null,
        "expiration_date": "2026-01-13 02:59:59 +0000",
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "6KKC461GAE888BZG5S4EB97P7Y",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-05T05:22:57Z",
            "updated_at": "2026-01-05T05:23:00Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-86824105-4c5b-4ef5-95db-02dc2eee8e85"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/2ZST97M3978WTB8RM1J6SWFS6H/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-86824105-4c5b-4ef5-95db-02dc2eee8e85",
        "callback_url": "https://example.com/callback",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-05T05:22:57Z",
            "updated_at": "2026-01-05T05:23:00Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-86824105-4c5b-4ef5-95db-02dc2eee8e85"
        },
        "payment_method": {
            "token": "Sa1erxgkqE4GzhzUCfvFmRpTHUD",
            "created_at": "2026-01-05T05:22:42Z",
            "updated_at": "2026-01-05T05:22:42Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "boleto_bancario",
            "errors": []
        }
    }
}

Gateway Specific Fields

payment_method_flow which can have a value of DIRECT and REDIRECT. Spreedly defaults to DIRECT.

DIRECT: you call dLocal’s API and render the returned ticket/barcode and reference number in your UI.
REDIRECT: you call API to obtain a checkout URL and send the customer to dLocal’s hosted page; dLocal displays the voucher and instructions.

"gateway_specific_fields": {
  "dlocal": {
    "payment_method_flow": "DIRECT"
  }
}

Webhook Notifications

The gateways posts asynchronous updates to the Spreedly notification_url. After, we have update the transaction we will post updates to the callback_url. Below is a dLocal example

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1klmilh-128u3nmkqh5gr3-dt58r2cce3gs",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 50,
    "currency": "BRL",
    "order_id": null,
    "payment_method_id": "BL",
    "ticket": {
      "number": "9900002555582"
    }
  }
}

Status Mapping

Use this mapping to drive business logic (show voucher, confirm order, allow refunds).

Provider Status	Meaning	Typical Action
PENDING	Voucher generated; awaiting cash payment	Display voucher; await webhook
PAID	Customer paid at Boleto; funds confirmed by dLocal	Fulfill order; allow refunds
EXPIRED/REJECTED	Payment window expired or cancelled/failed	Release reservation; show new voucher option

Refunds (Full and Partial)

Refunds can be initiated only after the payment is confirmed as PAID. Attempting to refund PENDING or EXPIRED payments should fail.

API Request

POST v1/transactions/{{successful_transaction_token}}/credit.json

{
    "transaction": {
        "amount": 5000,
        "currency_code": "BRL",
        "notification_url": "https://example.com/callback"
    }
}

//Status Code: 202 Accepted

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-05T06:58:21Z",
        "updated_at": "2026-01-05T06:58:24Z",
        "succeeded": false,
        "state": "processing",
        "token": "1N2GehRCxJTDTelZGfqnhk3V3dX",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "http://core.spreedly.test/transaction/1N2GehRCxJTDTelZGfqnhk3V3dX/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1klmo8e-rg78n8khgp6ib1-00fg227v91r8",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1888,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 5000,
        "local_amount": 50,
        "currency_code": "BRL",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "6KKC461GAE888BZG5S4EB97P7Y",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-05T06:58:23Z",
            "updated_at": "2026-01-05T06:58:24Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "1wSspZqTJ1sCWsfrddUZtkaTyZT"
    }
}

Webhook Notifications

dLocal posts asynchronous updates to your notification_url.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1klmilh-128u3nmkqh5gr3-dt58r2cce3gs",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 50,
    "currency": "BRL",
    "order_id": null,
    "payment_method_id": "BL"
  }
}

Nequi

Nequi is a popular digital wallet in Colombia. Through dLocal, one can Initiate one-time wallet payments, Optionally save a wallet token during a successful payment and Use the saved wallet token later for recurring/subsequent charges without requiring end-user approval each time.

Constraints

Country: CO (Colombia)
Currency: COP
Minimum amount: 100 COP (per dLocal MP capabilities)
Expiration window for authentication: ~45 minutes (per dLocal)
Flows: payment_method_flow: DIRECT or REDIRECT

Create Nequi Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
  "payment_method": {
    "payment_method_type": "nequi",
    "country_code": "CO",
    "full_name": "Demo User",
    "email": "[email protected]",
    "document_id": "123456789"
  }
}

//Status: 201 Created

{
    "transaction": {
        "token": "7AW9HD38B68FHR1CTT9G8VSN7S",
        "created_at": "2026-01-21T03:53:14Z",
        "updated_at": "2026-01-21T03:53:14Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "YbWPOpVjWefng2uyK6gUgsDEe1u",
            "created_at": "2026-01-21T03:53:13Z",
            "updated_at": "2026-01-21T03:53:14Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": "CO",
            "phone_number": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "nequi",
            "errors": [],
            "document_id": "8909"
        }
    }
}

Create Nequi Purchase

1) One-Time Purchase (No Recurring / No Token)

Use when you want a standard Nequi wallet payment, with no tokenization.

POST /v1/gateways/{gateway_token}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{nequi_payment_method_token}}",
        "amount": 5200,
        "currency_code": "COP",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com",
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "save": false
                }
            }
        }
    }
}

//Status: 202 Accepted, state = "pending"

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-21T05:22:50Z",
        "updated_at": "2026-01-21T05:22:54Z",
        "succeeded": false,
        "state": "pending",
        "token": "CyllriRQQ2iieXp7wHFLQ1K9caU",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {}
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://4317d4948222.ngrok.app/transaction/CyllriRQQ2iieXp7wHFLQ1K9caU/callback",
                "country": "CO",
                "status": "PENDING",
                "redirect_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-2b07c0d4-f507-4d77-8a6a-61eaf360d749"
            }
        },
        "gateway_transaction_id": "F-15104-x1kn0olc-et0ohsg0b14qv7-7gfen5l6c88k",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2180,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 5200,
        "local_amount": null,
        "currency_code": "COP",
        "reference": "F-15104-x1kn0olc-et0ohsg0b14qv7-7gfen5l6c88k",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "7S56X4P2QN94PA2Z767FBKT4G1",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-21T05:22:53Z",
            "updated_at": "2026-01-21T05:22:54Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-2b07c0d4-f507-4d77-8a6a-61eaf360d749"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/3CFJ0YDCYJ80NTGREHJ6VBEJPJ/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-2b07c0d4-f507-4d77-8a6a-61eaf360d749",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-21T05:22:53Z",
            "updated_at": "2026-01-21T05:22:54Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-2b07c0d4-f507-4d77-8a6a-61eaf360d749"
        },
        "payment_method": {
            "token": "XB4Sg4YElSoDb6OScS1rLUaxysw",
            "created_at": "2026-01-21T05:14:36Z",
            "updated_at": "2026-01-21T05:14:36Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "nequi",
            "errors": []
        }
    }
}

2) One-Time Purchase + Wallet Enrollment (Save Token)

Use when you want the customer to complete a one-time nequi payment and you want dLocal/Spreedly to return a wallet token for future recurring purchases.

{
  "transaction": {
    "payment_method_token": "{{nequi_payment_method_token}}",
    "amount": 5000,
    "currency_code": "COP",
    "callback_url": "https://merchant.example.com/return",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_flow": "REDIRECT",
        "wallet": {
          "save": true
        }
      }
    }
  }
}

Success behavior

User completes the payment in Nequi
On successful approval, dLocal returns a wallet token in its response / notification

3) Recurring Purchase via Wallet Token

Use when you already have a valid Nequi wallet token from a prior enrollment and want to charge the customer without another approval step.

{
  "transaction": {
    "payment_method_token": "{{nequi_payment_method_token}}",
    "amount": 5000,
    "currency_code": "COP",
    "description": "200",
    "callback_url": "https://merchant.example.com/return",
    "redirect_url": "https://merchant.example.com/return",
    "gateway_specific_fields": {
      "d_local": {
        "payment_method_flow": "DIRECT",
        "wallet": {
          "token": "{{nequi_wallet_token}}",
          "save": false
        }
      }
    }
  }
}

Webhook Notifications

dLocal sends asynchronous updates for Nequi payments to your notification/callback URL.

For wallet-based flows, you should:

Verify the webhook (signature mechanism per your dLocal contract)
Locate the corresponding Spreedly transaction and internal order/subscription
Update state based on dLocal’s status and status_code
Store wallet token if this was a save: true enrollment flow

A typical dLocal webhook payload for a successful APM payment looks like:

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9dr-mqp123456",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 5000,
    "currency": "COP",
    "order_id": "your-order-id-123",
    "payment_method_id": "QP",
    "wallet": {
      "token": "nequi_wallet_token_abc123",
      "name": "Jane Doe"
    }
  }
}

Status Mapping

Status	Meaning	Typical Action
PENDING	Payment created; waiting for Nequi approval/processing	Display pending; wait for webhook; no fulfillment
PAID / APPROVED	Customer authorized, payment captured	Fulfill order; enable service; allow refunds
REJECTED	Customer declined, auth failed, or error in Nequi	Mark payment failed; prompt retry / new method
EXPIRED	Authorization window (≈5 min) expired	Mark payment failed; offer to initiate new payment

Refunds (Full and Partial)

1) Refund One-Time Purchase

POST /v1/transactions/{transaction_token}/credit.json

{
  "transaction": {
    "amount": 5000,
    "currency_code": "COP",
    "callback_url": "https://merchant.example.com/refund-callback"
  }
}

//Typical Response: Processing

{
  "transaction": {
    "token": "1LDR9ZUHToi6IeMSpYyRroZ7mpR",
    "transaction_type": "Credit",
    "state": "processing",
    "amount": 5000,
    "currency_code": "COP",
    "gateway_specific_response_fields": {
      "d_local": {
        "status": "PENDING",
        "notification_url": "https://merchant.example.com/refund-callback"
      }
    },
    "message": "Processing"
  }
}

{
  "event": "payment.updated",
  "data": {
    "id": "REF-15104-x1ki0qo0-xyz-mp",
    "status": "SUCCESS",
    "status_detail": "Succeeded!",
    "status_code": "200",
    "amount": 5000,
    "currency": "COP",
    "payment_method_id": "QP"
  }
}

2) Partial Refund on Recurring Purchase

Identify the settled recurring charge (transaction token).
Call credit.json with partial amount less than or equal to original.
Track remaining refundable balance for that transaction in your system.
Enforce rules:
1. No refunds on PENDING / REJECTED / EXPIRED transactions
2. Sum of refunds ≤ original captured amount

API Field Reference

Field	Example/Type	Notes
currency / currency_code	"COP"	Must match dLocal’s MP configuration
wallet.save	true / false	true → request wallet token; false → no token
wallet.token	"nequi_wallet_token_abc123"	Required for recurring charges
callback_url / redirect_url	https://merchant.example.com/return	Where dLocal redirects / sends customer after payment
notification_url	https://merchant.example.com/webhook	dLocal posts status changes (payment.updated)
description	"200"	Required for recurring purchases via wallet token

Khipu

Khipu is an online bank transfer payment method in Chile that allows customers to pay directly from their bank accounts using secure bank authentication. When integrated via dLocal, Khipu enables merchants to accept real-time bank payments without cards.

Khipu is widely used in Chile for e-commerce, digital services, subscriptions, and bill payments due to its strong banking coverage and high consumer trust.

Create Khipu Payment Method

API Request

POST https://core.spreedly.test/v1/payment_methods.json

{
  "payment_method": {
      "payment_method_type": "khipu", //Must be khipu
      "country": "CL",
      "email": "[email protected]",
      "full_name": "John Doe",
      "document_id": "12345678", //National ID
      "phone_number": "7563126", //Customer phone number
      "address1": "Av. Principal 5940",
      "city": "Santiago",
      "state": "Santiago",
      "zip": "8858"
  }
}

//Success response

{
    "transaction": {
        "token": "4KSP4M4KZF8299T8CHVSPAMB5X",
        "created_at": "2026-01-08T11:23:45Z",
        "updated_at": "2026-01-08T11:23:45Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "15tHGWSjdrIMkspObx4B5d31QhP",  //Unique identifier for the Khipu payment method
            "created_at": "2026-01-08T11:23:45Z",
            "updated_at": "2026-01-08T11:23:45Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "Av. Principal 5940",
            "address2": null,
            "city": "Santiago",
            "state": "Santiago",
            "zip": "8858",
            "country": "CL",
            "phone_number": "7563126",
            "full_name": "John Doe",
            "first_name": "John",
            "last_name": "Doe",
            "payment_method_type": "khipu",
            "errors": [],
            "document_id": "5678"
        }
    }
}

Create Khipu Purchase Transaction

API Request

POST /v1/gateways/{gateway_token}/purchase.json

{
  "transaction": {     //Transaction Type: AUTHORIZATION_AND_CAPTURE
    "payment_method_token": "{{payment_method_token}}", //Token from Khipu payment method
    "amount": 2000,
    "currency_code": "CLP",
    "callback_url": "https://example.com/callback",
    "redirect_url": "https://example.com/redirect"  //Customer return URL
  }
}

//Status Code: 201 Created and Transaction state: pending

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-08T11:24:00Z",
        "updated_at": "2026-01-08T11:24:09Z",
        "succeeded": false,
        "state": "pending",
        "token": "DfVm6UlD2yezapn7e7vkDEJzE1z",
        "transaction_type": "OffsitePurchase",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://nicky-inductile-ferne.ngrok-free.dev/transaction/DfVm6UlD2yezapn7e7vkDEJzE1z/callback",
                "country": "CL",
                "status": "PENDING",
                "redirect_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c612fdeb-9d40-4593-900b-bebafa4ef6ac"
            }
        },
        "gateway_transaction_id": "R-15104-x1klv4ul-upvcpua66t4fl0-2i6r4k7pkgn4",
        "sub_merchant_key": null,
        "gateway_latency_ms": 6135,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 2000,
        "local_amount": null,
        "currency_code": "CLP",
        "reference": "R-15104-x1klv4ul-upvcpua66t4fl0-2i6r4k7pkgn4",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "5E1RY9YFD68K6TQ4JKTH0ZWQXV",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-08T11:24:06Z",
            "updated_at": "2026-01-08T11:24:09Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c612fdeb-9d40-4593-900b-bebafa4ef6ac"
        },
        "shipping_address": {
            "name": "John Doe",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/0Y8ARAN8268YC9HY3E9E4D15S8/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com/redirect",
        "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c612fdeb-9d40-4593-900b-bebafa4ef6ac",
        "callback_url": "https://example.com/callback",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-08T11:24:06Z",
            "updated_at": "2026-01-08T11:24:09Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/gmf-apm/payments/N-c612fdeb-9d40-4593-900b-bebafa4ef6ac"
        },
        "payment_method": {
            "token": "15tHGWSjdrIMkspObx4B5d31QhP",
            "created_at": "2026-01-08T11:23:45Z",
            "updated_at": "2026-01-08T11:23:45Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "John Doe",
            "first_name": "John",
            "last_name": "Doe",
            "payment_method_type": "khipu",
            "errors": []
        }
    }
}

transaction.response.checkout_url

Refunds

Initiate Refund Transaction

POST /v1/transactions/{{successful_transaction}}/credit.json

Authorization: Basic {{base64(environment_key:access_secret)}}
Content-Type: application/json

{
  "transaction": {
    "amount": 1000,
    "currency_code": "CLP"
  }
}

//Status code 201 Created. Refunds are not immediate. A successful API request returns a transaction in a processing or pending state

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-08T11:26:06Z",
        "updated_at": "2026-01-08T11:26:09Z",
        "succeeded": false,
        "state": "processing",
        "token": "2HSEdqHjAlE33M1ihehBy0l61VW",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "calculated_amount": 10,
                "notification_url": "http://core.spreedly.test/transaction/2HSEdqHjAlE33M1ihehBy0l61VW/callback",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "REF-15104-x1klv52f-eikf8l1rft1jt6-o9mll5p10t8g",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2123,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 1000,
        "local_amount": 10,
        "currency_code": "CLP",
        "message_key": "messages.transaction_processing",
        "message": "Processing",
        "gateway_token": "5E1RY9YFD68K6TQ4JKTH0ZWQXV",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-08T11:26:08Z",
            "updated_at": "2026-01-08T11:26:09Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "DfVm6UlD2yezapn7e7vkDEJzE1z"
    }
}

Refund Status Mapping

State	Meaning
processing / pending	Refund request accepted and awaiting bank confirmation
approved	Refund completed successfully
failed	Refund rejected or could not be completed

Yape

Yape is a popular Peruvian digital wallet. Through dLocal, you can Initiate one-time. Yape payments, Optionally save a wallet token on a successful payment and Use the saved wallet token for recurring charges without new customer approval.

Constraints

Country: PE (Peru)
Currency: PEN
Flows: payment_method_flow = "REDIRECT" for most one time flows and "DIRECT" for token‑based recurring

Create Yape Payment Method

API Request

POST /v1/payment_methods.json

Content-Type: application/json
Authorization: Basic Auth Username {{enviroment}}
                          Password {{access_secret}}

{
    "payment_method": {
        "email": "[email protected]",
        "payment_method_type": "yape",
        "full_name": "Demo User",
        "document_id": "12345678909",
        "country": "PE",
        "currency_code": "PEN",
        "zip": "12345",
        "phone_number": "1234567890"
    }
}

{
    "transaction": {
        "token": "5AB13WFEVG8A2AM015WMW8T2J9",
        "created_at": "2026-01-19T06:28:44Z",
        "updated_at": "2026-01-19T06:28:44Z",
        "succeeded": true,
        "transaction_type": "AddPaymentMethod",
        "retained": false,
        "state": "succeeded",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "payment_method": {
            "token": "NIwC70nRJFSZSehXmnMq0W3y95Q",
            "created_at": "2026-01-19T06:28:44Z",
            "updated_at": "2026-01-19T06:28:44Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "address1": "1234 test ave",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "PE",
            "phone_number": "1234567890",
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "yape",
            "errors": [],
            "document_id": "8909"
        }
    }
}

Create Yape Purchase

1) One‑Time Purchase (No Recurring / No Token)

POST /v1/gateways/{gateway_token}/purchase.json

{
    "transaction": {
        "payment_method_token": "{{yape_payment_method_token}}",
        "amount": 200,
        "currency_code": "PEN",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com",
        "order_id": "5346523564",        
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]",
                    "save": false
                }
            }
        }
    }
}

//Pending response

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-19T06:45:16Z",
        "updated_at": "2026-01-19T06:45:28Z",
        "succeeded": false,
        "state": "pending",
        "token": "OQ4uN59y1lj2CAnH7PSwxY90rGf",
        "transaction_type": "OffsitePurchase",
        "order_id": "5346523564",
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]"
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/OQ4uN59y1lj2CAnH7PSwxY90rGf/callback",
                "country": "PE",
                "status": "PENDING",
                "redirect_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80"
            }
        },
        "gateway_transaction_id": "F-15104-x1kmrknt-c0h06lro1d6o55-iupupnvnkreo",
        "sub_merchant_key": null,
        "gateway_latency_ms": 977,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 200,
        "local_amount": null,
        "currency_code": "PEN",
        "reference": "F-15104-x1kmrknt-c0h06lro1d6o55-iupupnvnkreo",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T06:45:25Z",
            "updated_at": "2026-01-19T06:45:28Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/22VMCYH7RK846THX8JMVCFJZ7F/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T06:45:25Z",
            "updated_at": "2026-01-19T06:45:28Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80"
        },
        "payment_method": {
            "token": "PO74DVgtTI02Be1OOGOIBTtEbFQ",
            "created_at": "2026-01-16T13:33:24Z",
            "updated_at": "2026-01-16T13:33:24Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "yape",
            "errors": []
        }
    }
}

//After success

{
    "transaction": {
        "on_test_gateway": false,
        "created_at": "2026-01-19T06:45:16Z",
        "updated_at": "2026-01-19T06:49:34Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "OQ4uN59y1lj2CAnH7PSwxY90rGf",
        "transaction_type": "OffsitePurchase",
        "order_id": "5346523564",
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]"
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/OQ4uN59y1lj2CAnH7PSwxY90rGf/callback",
                "country": "PE",
                "status": "PAID",
                "redirect_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]"
                }
            }
        },
        "gateway_transaction_id": "F-15104-x1kmrknt-c0h06lro1d6o55-iupupnvnkreo",
        "sub_merchant_key": null,
        "gateway_latency_ms": null,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 200,
        "local_amount": null,
        "currency_code": "PEN",
        "reference": "F-15104-x1kmrknt-c0h06lro1d6o55-iupupnvnkreo",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment was successfully completed.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": false,
            "created_at": "2026-01-19T06:49:34Z",
            "updated_at": "2026-01-19T06:49:34Z",
            "status": null
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/22VMCYH7RK846THX8JMVCFJZ7F/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T06:45:25Z",
            "updated_at": "2026-01-19T06:49:34Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-6ec08ffb-7549-4e48-bb50-7647d52cdc80"
        },
        "callback_response": {
            "success": true,
            "message": "The payment was successfully completed.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": false,
            "created_at": "2026-01-19T06:49:34Z",
            "updated_at": "2026-01-19T06:49:34Z",
            "status": null
        },
        "payment_method": {
            "token": "PO74DVgtTI02Be1OOGOIBTtEbFQ",
            "created_at": "2026-01-16T13:33:24Z",
            "updated_at": "2026-01-16T13:33:24Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "yape",
            "errors": []
        }
    }
}

2) One‑Time Purchase + Wallet Enrollment (Save Token)

{
    "transaction": {
        "payment_method_token": "{{yape_payment_method_token}}",
        "amount": 2200,
        "currency_code": "PEN",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com",
        "order_id": "5346523567",        
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]",                  
                    "save": true
                }
            }
        }
    }
}

//Typical pending response

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-19T07:16:21Z",
        "updated_at": "2026-01-19T07:16:26Z",
        "succeeded": false,
        "state": "pending",
        "token": "82fcVATat2dKPq49ZtRq05j7suH",
        "transaction_type": "OffsitePurchase",
        "order_id": "5346523567",
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]",
                    "save": true
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/82fcVATat2dKPq49ZtRq05j7suH/callback",
                "country": "PE",
                "status": "PENDING",
                "redirect_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519"
            }
        },
        "gateway_transaction_id": "F-15104-x1kmrmi5-vusfrueoh14qt7-ok8ail4argnk",
        "sub_merchant_key": null,
        "gateway_latency_ms": 860,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 2200,
        "local_amount": null,
        "currency_code": "PEN",
        "reference": "F-15104-x1kmrmi5-vusfrueoh14qt7-ok8ail4argnk",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_pending",
        "message": "Pending",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:16:23Z",
            "updated_at": "2026-01-19T07:16:26Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519"
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/22VMCYH7RK846THX8JMVCFJZ7F/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:16:23Z",
            "updated_at": "2026-01-19T07:16:26Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519"
        },
        "payment_method": {
            "token": "ZoBZBAGclwxeaqrRMmlCTTVcrgz",
            "created_at": "2026-01-19T07:14:47Z",
            "updated_at": "2026-01-19T07:14:47Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "yape",
            "errors": []
        }
    }
}

//After Success

{
    "transaction": {
        "on_test_gateway": false,
        "created_at": "2026-01-19T07:16:21Z",
        "updated_at": "2026-01-19T07:18:42Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "82fcVATat2dKPq49ZtRq05j7suH",
        "transaction_type": "OffsitePurchase",
        "order_id": "5346523567",
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "REDIRECT",
                "wallet": {
                    "username": "Test1",
                    "email": "[email protected]",
                    "save": true
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/82fcVATat2dKPq49ZtRq05j7suH/callback",
                "country": "PE",
                "status": "PAID",
                "redirect_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519",
                "wallet": {
                    "token": "cef2e888-97f7-4ee9-b7fe-7f5df858dca4",
                    "username": "Test1",
                    "email": "[email protected]"
                }
            }
        },
        "gateway_transaction_id": "F-15104-x1kmrmi5-vusfrueoh14qt7-ok8ail4argnk",
        "sub_merchant_key": null,
        "gateway_latency_ms": null,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 2200,
        "local_amount": null,
        "currency_code": "PEN",
        "reference": "F-15104-x1kmrmi5-vusfrueoh14qt7-ok8ail4argnk",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment was successfully completed.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": false,
            "created_at": "2026-01-19T07:18:42Z",
            "updated_at": "2026-01-19T07:18:42Z",
            "status": null
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/22VMCYH7RK846THX8JMVCFJZ7F/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:16:23Z",
            "updated_at": "2026-01-19T07:18:42Z",
            "status": null,
            "checkout_url": "https://sandbox.dlocal.com/playground-ui/enrollment/N-18fe21c7-01e6-4e32-a391-39ce1acfe519"
        },
        "callback_response": {
            "success": true,
            "message": "The payment was successfully completed.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": false,
            "created_at": "2026-01-19T07:18:42Z",
            "updated_at": "2026-01-19T07:18:42Z",
            "status": null
        },
        "payment_method": {
            "token": "ZoBZBAGclwxeaqrRMmlCTTVcrgz",
            "created_at": "2026-01-19T07:14:47Z",
            "updated_at": "2026-01-19T07:14:47Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "cached",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "yape",
            "errors": []
        }
    }
}

3) Recurring Purchase via Wallet Token

{
    "transaction": {
        "payment_method_token": "{{yape_payment_method_token}}",
        "amount": 2300,
        "currency_code": "PEN",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com",
        "order_id": "5346523567",
        "description": "200",
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "DIRECT",
                "wallet": {                    
                    "token": "cef2e888-97f7-4ee9-b7fe-7f5df858dca4"                    
                }
            }
        }
    }
}

//Success Response

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-19T07:21:09Z",
        "updated_at": "2026-01-19T07:21:13Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "3dFNF6SodmNbc6syW8IjU0ed1XK",
        "transaction_type": "OffsitePurchase",
        "order_id": "5346523567",
        "ip": null,
        "description": "200",
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {
            "d_local": {
                "payment_method_flow": "DIRECT",
                "wallet": {
                    "token": "cef2e888-97f7-4ee9-b7fe-7f5df858dca4"
                }
            }
        },
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/3dFNF6SodmNbc6syW8IjU0ed1XK/callback",
                "country": "PE",
                "status": "PAID"
            }
        },
        "gateway_transaction_id": "F-15104-x1kmrmr7-n0h1if22r52993-h43k96m7kn0s",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2210,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 2300,
        "local_amount": 23,
        "currency_code": "PEN",
        "reference": "F-15104-x1kmrmr7-n0h1if22r52993-h43k96m7kn0s",
        "setup_verification": null,
        "expiration_date": null,
        "stored_credential_initiator": null,
        "stored_credential_reason_type": null,
        "stored_credential_alternate_gateway": null,
        "stored_credential_final_payment": false,
        "retain_on_success": false,
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment was paid.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:21:12Z",
            "updated_at": "2026-01-19T07:21:13Z",
            "status": null
        },
        "shipping_address": {
            "name": "Demo User",
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [
            {
                "callback_conversations": [
                    "http://core.spreedly.test/v1/callbacks/22VMCYH7RK846THX8JMVCFJZ7F/conversations.xml"
                ]
            }
        ],
        "redirect_url": "https://example.com",
        "callback_url": "https://example.com",
        "attempt_3dsecure": false,
        "challenge_url": null,
        "required_action": "none",
        "three_ds_context": null,
        "payment_method": {
            "token": "ZoBZBAGclwxeaqrRMmlCTTVcrgz",
            "created_at": "2026-01-19T07:14:47Z",
            "updated_at": "2026-01-19T07:18:42Z",
            "email": "[email protected]",
            "data": null,
            "storage_state": "used",
            "test": false,
            "metadata": null,
            "callback_url": null,
            "full_name": "Demo User",
            "first_name": "Demo",
            "last_name": "User",
            "payment_method_type": "yape",
            "errors": []
        }
    }
}

4) Webhook Notifications

dLocal sends asynchronous payment.updated events to your notification_url.

Verify authenticity (signature/secret per dLocal contract).
Match the webhook to your Spreedly transaction & internal order/subscription.
Update state based on dLocal status / status_code.
Persist wallet token when present and save: true was used.

{
  "event": "payment.updated",
  "data": {
    "id": "D-15104-x1ki0rmd-a9dr-yape123456",
    "status": "PAID",
    "status_detail": "The payment was successfully completed.",
    "status_code": "200",
    "amount": 5000,
    "currency": "PEN",
    "order_id": "your-order-id-123",
    "payment_method_id": "YAPE",
    "wallet": {
      "token": "yape_wallet_token_abc123",
      "name": "Juan Perez",
      "email": "[email protected]"
    }
  }
}

Status Mapping

Status	Meaning	Typical Action
PENDING	Created; awaiting Yape approval/result	Show pending; wait for webhook; don’t fulfill
PAID / APPROVED	Payment captured successfully	Fulfill order; enable usage; allow refunds
REJECTED	Declined / error / invalid token	Mark failed; offer retry/new payment method
EXPIRED	Customer did not complete in time	Mark failed; allow new payment attempt

Refunds (Full and Partial)

1) Full Refund

POST /v1/transactions/{transaction_token}/credit.json

{
  "transaction": {
    "amount": 5000,
    "currency_code": "PEN",
    "notification_url": "https://merchant.example.com/refund-callback"
  }
}

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-19T07:43:19Z",
        "updated_at": "2026-01-19T07:43:29Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "PuBWfPofU0pG8Vs3eTriUVnN8Q2",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": {},
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/PuBWfPofU0pG8Vs3eTriUVnN8Q2/callback",
                "status": "SUCCESS"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kmro4p-aqq4o091rh66d9-hjvp8h8son28",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2142,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 200,
        "local_amount": 2,
        "currency_code": "PEN",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund was paid.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:43:26Z",
            "updated_at": "2026-01-19T07:43:29Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "OQ4uN59y1lj2CAnH7PSwxY90rGf"
    }
}

2) Partial Refund on Recurring Purchase

Identify the settled recurring Yape charge (transaction token).
Call credit.json with a partial amount.
Track refundable balance in your system.
Enforce:
1. No refunds on PENDING / REJECTED / EXPIRED.
2. Sum of refunds ≤ original captured amount.

//Request Body for 1st Partial Refund (total amount 2400)

{
  "transaction": {
    "amount": 1300,
    "currency_code": "PEN",
    "notification_url": "https://merchant.example.com/refund-callback"
  }
}

//Success Response 1st Partial Refund

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-19T07:45:35Z",
        "updated_at": "2026-01-19T07:45:40Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "7GEhQY10Au89EZQufZblzPUIgxI",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/7GEhQY10Au89EZQufZblzPUIgxI/callback",
                "status": "SUCCESS"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kmro91-v0p3ehm34l2tn3-12k14r8pu2r8",
        "sub_merchant_key": null,
        "gateway_latency_ms": 2601,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 1300,
        "local_amount": 13,
        "currency_code": "PEN",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund was paid.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:45:39Z",
            "updated_at": "2026-01-19T07:45:40Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "3dFNF6SodmNbc6syW8IjU0ed1XK"
    }
}

//Request Body for 2nd Partial Refund (total amount 2400)

{
  "transaction": {
    "amount": 1000,
    "currency_code": "PEN",
    "notification_url": "https://merchant.example.com/refund-callback"
  }
}

//Success Response 2nd Partial Refund

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2026-01-19T07:46:18Z",
        "updated_at": "2026-01-19T07:46:24Z",
        "succeeded": true,
        "state": "succeeded",
        "token": "XjMAl9czYZtgmvuDr6QbbduK2LL",
        "transaction_type": "Credit",
        "order_id": null,
        "ip": null,
        "description": null,
        "email": null,
        "merchant_name_descriptor": null,
        "merchant_location_descriptor": null,
        "merchant_profile_key": null,
        "gateway_specific_fields": null,
        "gateway_specific_response_fields": {
            "d_local": {
                "notification_url": "https://a19ec2204731.ngrok.app/transaction/XjMAl9czYZtgmvuDr6QbbduK2LL/callback",
                "status": "SUCCESS"
            }
        },
        "gateway_transaction_id": "REF-15104-x1kmroab-e6g2ik1vh12ur1-1j9psq9o1ego",
        "sub_merchant_key": null,
        "gateway_latency_ms": 1935,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "amount": 1000,
        "local_amount": 10,
        "currency_code": "PEN",
        "message_key": "messages.transaction_succeeded",
        "message": "Succeeded!",
        "gateway_token": "3VV9ZXCQGV9ZBVNPSNB7CWJCR6",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The refund was paid.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": false,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2026-01-19T07:46:21Z",
            "updated_at": "2026-01-19T07:46:24Z",
            "status": null
        },
        "shipping_address": {
            "name": null,
            "address1": null,
            "address2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone_number": null
        },
        "api_urls": [],
        "reference_token": "3dFNF6SodmNbc6syW8IjU0ed1XK"
    }
}

API Field Reference

Field	Example / Type	Notes
payment_method_type	"YAPE"	Use when creating Spreedly payment method (confirm value)
payment_method_id	"YAPE"	dLocal identifier for Yape (confirm in dLocal docs)
payment_method_flow	"DIRECT" / "REDIRECT"	REDIRECT for one‑shot; DIRECT for tokenized recurring
country	"PE"	Requried
currency / currency_code	"PEN"	Must match dLocal Yape configuration
wallet.save	true / false	true → return wallet token (on approval)
wallet.token	"yape_wallet_token_abc123"	Required for recurring purchases
callback_url / redirect_url	https://merchant.example.com/return	Customer redirection / completion
notification_url	https://merchant.example.com/webhook	Webhook endpoint for payment.updated
description	"200"	Mandatory for Recurring Purchase

Additional resources

📘
If you need support with this gateway, please contact Support at [email protected].

📘
dLocal documentation: dLocal official site, dLocal Payins API reference