dLocal Gateway Guide

dLocal fact sheet

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.

Adding a dLocal gateway

To add a dLocal gateway:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -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>'

<gateway>
  <token>LAynfqGFs6oWO2s3Q0MtxOQXnWY</token>
  <gateway_type>d_local</gateway_type>
  <name>dLocal</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <login>Your login</login>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">true</supports_offsite_purchase>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
    <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <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_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_inquire type="boolean">true</supports_inquire>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>Your login</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>document</gateway_specific_field>
    <gateway_specific_field>document2</gateway_specific_field>
    <gateway_specific_field>birth_date</gateway_specific_field>
    <gateway_specific_field>user_reference</gateway_specific_field>
    <gateway_specific_field>dynamic_descriptor</gateway_specific_field>
    <gateway_specific_field>notification_url</gateway_specific_field>
    <gateway_specific_field>installments</gateway_specific_field>
    <gateway_specific_field>installments_id</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>additional_data</gateway_specific_field>
    <gateway_specific_field>device_id</gateway_specific_field>
    <gateway_specific_field>force_type</gateway_specific_field>
    <gateway_specific_field>original_order_id</gateway_specific_field>
    <gateway_specific_field>country</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>pix</payment_method>
    <payment_method>apple_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-02-07T15:03:40Z</created_at>
  <updated_at type="dateTime">2023-02-07T15:03:40Z</updated_at>
</gateway>

Third-party 3D Secure 2 auth data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Dlocal. For more information about how to use this feature, see the [3DS2 Third-party Authentication Guide](To be Added). Spreedly fields map to the relevant Dlocal fields as described in the following table. Please see Dlocal’s transaction variable documentation for detailed descriptions of each of these fields and when to use them.

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`

Gateway specific fields

When interacting with a dLocal gateway to run transactions, there are a number of gateway specific fields you can specify. See below for usage notes for certain fields, and dLocal’s documentation for more information.

document the customer’s national identification number, required for Auths and Purchases.
Passing notification_url for refunds will allow dLocal to send http POST notices of the refund’s finalization to that url, if the refund is not immediate.
birth_date is expected in the format DD-MM-YYYY
idempotency_key is for safely retrying requests without accidentally performing the same operation twice.
device_iddLocal device ID used in fraud prevention. Described as event_uuid in dLocal docs
additional_data open ended object used in fraud prevention. Described as additional_risk_data in dLocal docs
force_type is an optional field that indicates the card type in cases where the card can act as either debit or credit. This field only applies for transactions in Brazil. Possible values are: CREDIT or DEBIT.
original_order_id is an ID given by the merchant in their system for the original transaction in the event it is rejected and needs to be retried.
save is an optional boolean field. When set to true on a purchase, authorize, or verify, it will save the card to the merchant’s dLocal account, and will also generate the saved_card_type gateway specific response field.
country is optional and can be added to a transaction to override the Country field of the billing address during the transaction.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
  <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
  <amount>100</amount>
  <currency_code>USD</currency_code>
  <gateway_specific_fields>
    <d_local>
      <document>1234567890</document>
      <document2>0987654321</document2>
      <birth_date>01-01-1980</birth_date>
      <user_reference>1357924680</user_reference>
      <dynamic_descriptor>dynamic description</dynamic_descriptor>
      <notification_url>http://example.com</notification_url>
      <installments>3</installments>
      <installments_id>INS54434</installments_id>
      <idempotency_key>key</idempotency_key>
      <device_id>123</device_id>
      <force_type>DEBIT</force_type>
      <original_order_id>ABC123</original_order_id>
      <save>true</save>
      <additional_data>
        <submerchant>
          <item>socks</item>
        </submerchant>
      </additional_data>
      <country>Mexico</country
    </d_local>
  </gateway_specific_fields>
</transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2023-06-20T16:20:47Z</created_at>
  <updated_at type="dateTime">2023-06-20T16:20:47Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>CXAzQtugF1GOgr1hkY3lXJhyXhY</token>
  <transaction_type>Purchase</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <d_local>
      <document>1234567890</document>
      <document2>0987654321</document2>
      <birth_date>01-01-1980</birth_date>
      <user_reference>1357924680</user_reference>
      <dynamic_descriptor>dynamic description</dynamic_descriptor>
      <notification_url>http://example.com</notification_url>
      <installments>3</installments>
      <installments_id>INS54434</installments_id>
      <idempotency_key>key</idempotency_key>
      <device_id>123</device_id>
      <force_type>DEBIT</force_type>
      <original_order_id>ABC123</original_order_id>
      <save>true</save>
      <additional_data>
        <submerchant>
          <item>socks</item>
        </submerchant>
      </additional_data>
      <country>Mexico</country
    </d_local>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>67</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <local_amount nil="true"/>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <stored_credential_gateway_override nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Newfirst Newlast</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2023-06-20T16:20:47Z</created_at>
    <updated_at type="dateTime">2023-06-20T16:20:47Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2023-06-16T13:48:47Z</updated_at>
    <email>[email protected]</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>string value</key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <issuer_identification_number nil="true"/>
    <click_to_pay type="boolean">false</click_to_pay>
    <managed nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
    <stored_credential_usage>
      <test>
        <original_network_transaction_id>37be5367d6dbe4a88c9d</original_network_transaction_id>
        <network_transaction_id>37be5367d6dbe4a88c9d</network_transaction_id>
      </test>
    </stored_credential_usage>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

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 documentation for more information.

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.

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.

For example, a transaction could have something like this:

  <transaction>
    <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</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>

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 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.

The user can complete the payment using any Home Banking or Ewallet App, by copying and pasting a Transaction ID or scanning a QR code. For more information about PIX see Pix dLocal documentation.

Available country code	BR

Parameters:

FIELD NAME	M/O	DESCRIPTION
payment_method_id	M	Pix unique identifier
payment_method_flow	M	Specify the type of flow to use
notification_url	M	Notification URL to receive changes about the transaction state
offsite_sync	O	Identify the transaction as synchronous, default is false

Pix Transactions

The Spreedly integration with dLocal Gateway offers one mode of transacting via PIX using Direct PIX payment

For offsite transaction it is necessary to reach out to your dLocal account manager to ensure your account is properly configured.

Create Pix Payment Method and Pending Transaction

curl https://core.spreedly.com/v1/payment_methods.xml \
  -u 'JK2TAjqm7aDifCK74iN178aPQmg:e671vkMEWTi1saL1lGu15y6MIA56WrbeWquqvX41zx63gs7cjly4GkJ6l1PqejEx' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
    <payment_method>
        <payment_method_id>PIX</payment_method_id>
        <payment_method_flow>DIRECT</payment_method_flow>
        <first_name>Joe</first_name>
        <last_name>Doe</last_name>
        <payment_method_type>pix</payment_method_type>
        <country>BR</country>
        <document_id>71575743221</document_id>
    </payment_method>
    <amount>1000</amount> 
    <currency_code>BRL</currency_code>
    <redirect_url>https://example.com/redirect</redirect_url>
    <callback_url>https://example.com/callback</callback_url>
</transaction>

Response:

<transaction>
    <on_test_gateway type="boolean">true</on_test_gateway>
    <created_at type="dateTime">2025-06-16T12:37:25Z</created_at>
    <updated_at type="dateTime">2025-06-16T12:37:26Z</updated_at>
    <succeeded type="boolean">false</succeeded>
    <state>pending</state>
    <token>ACewFm6CVQLYKdM2hOn5Jz0OpRb</token>
    <transaction_type>OffsitePurchase</transaction_type>
    <order_id nil="true"/>
    <ip nil="true"/>
    <description nil="true"/>
    <email nil="true"/>
    <merchant_name_descriptor nil="true"/>
    <merchant_location_descriptor nil="true"/>
    <merchant_profile_key nil="true"/>
    <gateway_specific_fields nil="true"/>
    <gateway_specific_response_fields>
        <d_local>
            <ticket>
                <type>CUSTOM</type>
                <format>Code 128</format>
                <number>9900002143135</number>
                <expiration_date>2025-06-22T23:59:00.000+0000</expiration_date>
                <id>9900002143135</id>
                <barcode>656559618</barcode>
                <company_name>The Best Company</company_name>
                <company_id>112903</company_id>
                <image_url>https://sandbox.dlocal.com/gmf-apm/payments/M-7fa3123c-54f4-4a83-b7f2-436bffcf7c88</image_url>
                <amount type="float">10.0</amount>
            </ticket>
            <country>BR</country>
            <status>PENDING</status>
        </d_local>
    </gateway_specific_response_fields>
    <gateway_transaction_id>D-15104-8b66c6ff-eff8-4bc8-aca9-b9800dc9a73a</gateway_transaction_id>
    <sub_merchant_key nil="true"/>
    <gateway_latency_ms type="integer">1208</gateway_latency_ms>
    <warning nil="true"/>
    <application_id nil="true"/>
    <risk_data nil="true"/>
    <merchant_metadata nil="true"/>
    <customer_data nil="true"/>
    <order_data nil="true"/>
    <workflow_key nil="true"/>
    <protection_parameters nil="true"/>
    <amount type="integer">1000</amount>
    <local_amount nil="true"/>
    <currency_code>BRL</currency_code>
    <reference>D-15104-8b66c6ff-eff8-4bc8-aca9-b9800dc9a73a</reference>
    <setup_verification nil="true"/>
    <expiration_date>2025-06-22 23:59:00 +0000</expiration_date>
    <message key="messages.transaction_pending">Pending</message>
    <gateway_token>0AXPW50NFM9MCVHPY19DE9PAG4</gateway_token>
    <gateway_type>d_local</gateway_type>
    <shipping_address>
        <name nil="true"/>
        <address1 nil="true"/>
        <address2 nil="true"/>
        <city nil="true"/>
        <state nil="true"/>
        <zip nil="true"/>
        <country nil="true"/>
        <phone_number nil="true"/>
    </shipping_address>
    <response>
        <success type="boolean">true</success>
        <message>The payment is pending.</message>
        <error_code nil="true"/>
        <checkout_url nil="true"/>
        <created_at type="dateTime">2025-06-16T12:37:26Z</created_at>
        <updated_at type="dateTime">2025-06-16T12:37:26Z</updated_at>
    </response>
    <api_urls>
        <callback_conversations>https://core.spreedly.com/v1/callbacks/4FXPCCWGPN8FYTANA6G736M2SN/conversations.xml</callback_conversations>
    </api_urls>
    <payment_method>
        <token>01JXWBX52MAGN5AX6R0QKD5CBK</token>
        <created_at>2025-06-16T12:37:25.204Z</created_at>
        <updated_at>2025-06-16T12:37:25.204Z</updated_at>
        <email nil="true"/>
        <data nil="true"/>
        <storage_state>cached</storage_state>
        <test type="boolean">false</test>
        <metadata nil="true"/>
        <callback_url nil="true"/>
        <full_name>Joe Doe</full_name>
        <first_name>Joe</first_name>
        <last_name>Doe</last_name>
        <payment_method_type>pix</payment_method_type>
        <errors>
    </errors>
    </payment_method>
    <callback_url>https://example.com/callback</callback_url>
    <redirect_url>https://example.com/redirect</redirect_url>
    <checkout_url nil="true"/>
    <callback_url>https://example.com/callback</callback_url>
    <attempt_3dsecure type="boolean">false</attempt_3dsecure>
    <checkout_form>
  </checkout_form>
    <device_fingerprint_form>
  </device_fingerprint_form>
    <challenge_form>
  </challenge_form>
    <challenge_url nil="true"/>
    <required_action>none</required_action>
    <three_ds_context nil="true"/>
    <setup_response>
        <success type="boolean">true</success>
        <message>The payment is pending.</message>
        <error_code nil="true"/>
        <checkout_url nil="true"/>
        <created_at type="dateTime">2025-06-16T12:37:26Z</created_at>
        <updated_at type="dateTime">2025-06-16T12:37:26Z</updated_at>
    </setup_response>
</transaction>

The customer should be sent to the URL in the image_url value to complete the Pix transcation.

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).

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.

Callback

Spreedly’s callback system handles situations where a customer runs an asynchronous transaction and the result is not immediately available to return to them. When Spreedly receives a status update on an asynchronous transaction that alters the state of the Spreedly transaction, Spreedly will send a notification to the callback_url specified in the transaction.

Notification

Whenever dLocal updates the state of a pending transaction, they can notify Spreedly through the webhook mentioned above to update the transaction status. The merchants have to configure the notification_url in their dLocal dashboard.

For more information on callbacks, see Spreedly’s Offsite Payments documentation./

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

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": {
      "dlocal": {
        "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

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",
            "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"
  }
}

//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": null,
        "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_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"
    }
  }
}

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