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, and status 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>
       </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

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: Bearer {access_token}

{
  "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": {
        "payment_method_token": "{{efecty_payment_method_token}}",
        "amount": 5000,
        "currency_code": "COP",
        "callback_url": "https://example.com",
        "redirect_url": "https://example.com"
    }
}

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

PSE

Overview

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. It is widely adopted across Colombian e-commerce and digital services due to its security, reliability, and strong banking coverage.

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.

dLocal acts as the payment gateway, managing the interaction with the PSE network and participating banks, handling redirects, validating transaction states, and normalizing responses for downstream systems.

This integration is commonly used for one-time payments in Colombia, particularly for e-commerce, utilities, and digital services, where card penetration may be lower and bank transfers are preferred.

Key Features of PSE via dLocal

1. Bank-Based Online Transfers

Customers pay directly from their bank accounts
Supports major Colombian banks
No need for cards or digital wallets

2. Offsite Redirect Payment Flow

dLocal redirects the customer to the selected bank’s PSE flow
Payment authorization occurs on the bank’s secure interface
Customer is redirected back to the merchant after completion

3. No Card Required

Direct bank-to-bank payment
No card number, CVV, or expiration date
Reduced card-related fraud exposure

4. Multiple Transaction States

PSE payments transition through well-defined states such as:

pending – payment initiated, awaiting bank confirmation
approved – payment successfully completed
rejected / failed – payment declined or canceled

Final status is confirmed via asynchronous callbacks/webhooks

Create Gateway Method

1. API Request

Endpoint:

POST /v1/gateways.json

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

{
    "gateway": {
        "gateway_type": "d_local",
        "login": "4SWxffHav8",
        "trans_key": "MThCMjLZND",
        "secret_key": "vlSh218OE0NN3JkgU0JYx8YR6YbS15LmE",
        "payment_country": "BR",
        "sandbox": true
    }
}

Status Code: 201 Created

{
    "gateway": {
        "token": "0MSENVGMP481TV6ZTF4G5GM18W",
        "gateway_type": "d_local",
        "description": null,
        "merchant_profile_key": null,
        "sub_merchant_key": null,
        "payment_methods": [
            "credit_card",
            "pix",
            "third_party_network_token",
            "apple_pay",
            "efecty",
            "rapi_pago",
            "pago_facil",
            "webpay",
            "pago_efectivo",
            "oxxo",
            "pse"
        ],
        "state": "retained",
        "created_at": "2025-12-16T11:04:16Z",
        "updated_at": "2025-12-16T11:04:16Z",
        "name": "dLocal",
        "login": "4SWxffHav8",
        "characteristics": [
            "purchase",
            "authorize",
            "capture",
            "partial_capture",
            "credit",
            "partial_credit",
            "void",
            "verify",
            "offsite_purchase",
            "3dsecure_2_mpi_purchase",
            "3dsecure_2_mpi_authorize",
            "network_tokenization",
            "inquire_by_gateway_transaction_id",
            "inquire_by_order_id",
            "transaction_retry",
            "stored_credentials",
            "card_scheme_ntid"
        ],
        "credentials": [
            {
                "name": "login",
                "value": "4SWxffHav8"
            }
        ],
        "gateway_settings": {},
        "gateway_specific_fields": [
            "document",
            "document2",
            "birth_date",
            "user_reference",
            "dynamic_descriptor",
            "notification_url",
            "installments",
            "installments_id",
            "idempotency_key",
            "additional_data",
            "device_id",
            "force_type",
            "original_order_id",
            "payment_method_id",
            "payment_method_flow",
            "save",
            "description",
            "country",
            "original_amount",
            "original_taxed_amount",
            "original_tax_type"
        ],
        "redacted": false,
        "sandbox": true,
        "mode": "default"
    }
}

Field	Type/Example	Description
payment_method_type	String	Must be "d_local"
payment-method -> token	String	Unique identifier for the payment method

Create Payment Method

1. API Request

Endpoint:

POST /v1/payment_methods.json

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

{
    "payment_method": {
        "email": "[email protected]",
        "payment_method_type": "pse",
        "full_name": "User- shubham wore test",
        "document_id": "12345678909",
        "country": "CO",
        "zip": "12345",
        "address1": "shubham wore 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",
            "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": "shubham wore test",
            "address2": null,
            "city": "Rio",
            "state": "CE",
            "zip": "12345",
            "country": "CO",
            "phone_number": "1234567890",
            "full_name": "User- shubham wore test",
            "first_name": "User- shubham wore",
            "last_name": "test",
            "payment_method_type": "pse",
            "errors": [],
            "document_id": "8909"
        }
    }
}

Initiate PSE Purchase

1. API Request

Endpoint:

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

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

{
  "transaction": {
    "payment_method_token": "{{payment_method_token}}",
    "amount": 168,
    "currency_code": "USD",
    "callback_url": "https://example.com",
    "redirect_url": "https://example.com"
  }
}

Status Code: 201 Created

{
    "transaction": {
        "on_test_gateway": true,
        "created_at": "2025-12-16T11:04:52Z",
        "updated_at": "2025-12-16T11:04:56Z",
        "succeeded": false,
        "state": "pending",
        "token": "7LxbpTjcHmcha69Otdt0DU7Q3J2",
        "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/7LxbpTjcHmcha69Otdt0DU7Q3J2/callback",
                "country": "CO",
                "status": "PENDING"
            }
        },
        "gateway_transaction_id": "D-15104-x1kk2f6l-b0619c85ul4g7e-ipag1qtphm48",
        "sub_merchant_key": null,
        "gateway_latency_ms": 905,
        "warning": null,
        "application_id": null,
        "risk_data": null,
        "merchant_metadata": null,
        "customer_data": null,
        "order_data": null,
        "workflow_key": null,
        "protection_parameters": null,
        "amount": 168,
        "local_amount": null,
        "currency_code": "USD",
        "reference": "D-15104-x1kk2f6l-b0619c85ul4g7e-ipag1qtphm48",
        "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": "0MSENVGMP481TV6ZTF4G5GM18W",
        "gateway_type": "d_local",
        "response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-16T11:04:53Z",
            "updated_at": "2025-12-16T11:04:56Z",
            "status": null
        },
        "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/6BKGQ7V7CJ9FCVNTWA6HDXERN4/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,
        "setup_response": {
            "success": true,
            "message": "The payment is pending.",
            "avs_code": null,
            "avs_message": null,
            "cvv_code": null,
            "cvv_message": null,
            "pending": true,
            "result_unknown": false,
            "error_code": null,
            "error_detail": null,
            "cancelled": false,
            "fraud_review": null,
            "created_at": "2025-12-16T11:04:53Z",
            "updated_at": "2025-12-16T11:04:56Z",
            "status": null
        },
        "payment_method": {
            "token": "W8JFqUoSWUj6HhP3r11BER2Semh",
            "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,
            "full_name": "User- shubham wore test",
            "first_name": "User- shubham wore",
            "last_name": "test",
            "payment_method_type": "pse",
            "errors": []
        }
    }
}

Parameters:

gateway_token required from previous request

payment_method_token required from previous request

2. Failure Response

This response represents a failed PSE transaction, which may occur if the customer cancels the payment on the bank page, the bank declines the transaction, or a validation error occurs.

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

Payment Flow

Create the PSE payment method
Call the purchase (offsite) endpoint
Receive transaction token and redirect URL
Redirect customer to the bank’s PSE payment page
Customer authenticates and completes payment on bank portal
dLocal sends asynchronous status update to the callback_url

Possible Transaction States

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

Notes

Always rely on asynchronous callback/webhook notifications from dLocal for the final payment status, as the initial transaction response is typically pending.

PSE payments do not use QR codes; customers complete the payment on their bank’s secure portal after redirection.

Summary

The dLocal PSE integration enables bank-based offsite payments in Colombia by creating a PSE payment method and initiating an offsite purchase transaction. Customers are redirected to their selected bank to authorize the payment, and transactions are initialized in a pending state. The final transaction outcome (approved or failed) is determined asynchronously via dLocal callback/webhook notifications.

WebPay

Webpay via dLocal – Overview

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: Bearer {access_token}

{
  "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 via dLocal

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: Bearer {access_token}

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

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",
    "callback_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 (RapiPago/dLocal)

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

Mercado Pago

MercadoPago via dLocal – Overview

This page provides end-to-end technical documentation for integrating Mercado Pago (MP) wallet via dLocal in Colombia. It explains:

The one-shot (non-recurring) wallet payment flow
The tokenized / recurring wallet flow using dLocal’s wallet object
API patterns (payment method create, purchase)
Request/response examples
Webhook handling and status mapping
Refunds for one-shot and recurring wallet transactions

Mercado Pago is a popular digital wallet in Colombia and other LATAM markets. Through dLocal, you can:

Initiate one-shot (one-time) wallet payments
Optionally save a wallet token during a successful payment
Use the saved wallet token later for recurring / subsequent charges without requiring end-user approval each time

In dLocal’s Colombia spec, Mercado Pago is modeled as:

payment_method_id: MP
payment_method_type: BANK_TRANSFER (per dLocal docs)
Flows: DIRECT and REDIRECT
Category: Wallet (per dLocal documentation and marketing)

Your integration will rely on offsite redirects and dLocal webhooks for asynchronous status updates.

1.1 Key Capabilities

One-shot wallet payments

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

Wallet tokenization & recurring

Use dLocal’s wallet object in the purchase call:

wallet.save = true to receive a wallet token
Future purchases can use wallet.token for recurring charges

Internal QA confirms:

save: false → no token returned

save: true → token returned after approval

Recurring via token does not prompt the payer again

Refunds

Full and partial refunds supported once payment is PAID/APPROVED

1.2 Constraints

Country: CO (Colombia)

Currency: COP

Minimum amount: 100 COP (per dLocal MP capabilities)

Expiration window for authentication: ~5 minutes (per dLocal)

Flows:

payment_method_flow: DIRECT or REDIRECT

Most wallet implementations use REDIRECT for one-shot

DIRECT may be used in some tokenized scenarios (you still rely on dLocal for auth)

Verify final enablement and any country/currency restrictions with your dLocal account team.

1.3 Integration Checklist

Before coding:

dLocal account with Mercado Pago wallet enabled for Colombia

Spreedly gateway token for dLocal

Public, HTTPS-accessible notification_url / callback_url to receive dLocal status updates

Application-level:

Logic to persist wallet token on successful save: true enrollment

Logic to use stored wallet token for recurring purchases

Safe retry & idempotency for:

Purchase API calls

Webhook processing

Refund workflow tied to PAID state only

2) Create Mercado Pago Payment Method

From Spreedly’s perspective, you first create a Spreedly payment method representing the MP payer, then use it when initiating the dLocal MP purchase.

Note: Spreedly’s payment_method_type is mercado_pago (internal mapping). dLocal’s own payment_method_id (MP) is sent via gateway_specific_fields.

2.1 API Request

Endpoint:

POST /v1/payment_methods.json

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

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

Status: 201 Created

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

Type/Example	Description
payment_method_type	must be "mercado_pago"
full_name, email, document_id:	used for payer context and normalization
country_code: "CO"

You will use payment_method.token (MPwPFqbN34Nc5x4lr9iM2aEcD9u) in purchase calls.

3) Create Mercado Pago Purchase

This section covers two core flows:

3.1 One-time purchase (no wallet token)

3.2 One-time purchase + wallet enrollment (save token)

3.3 Recurring purchase via saved wallet token

Internally, these correspond to the tests captured here: Mercado Pago Wallet on DLocal

On dLocal, Mercado Pago parameters align with the wallet spec for Colombia:

payment_method_id: "MP"

payment_method_flow: "DIRECT" or "REDIRECT"

wallet object: save, token, etc. (pattern similar to Nequi wallet in the same doc)

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

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

Endpoint:

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

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

Status: 202 Accepted, state = "pending"

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

Next step:

Redirect the customer to transaction.checkout_url for the MP experience.

Final status will be provided asynchronously via webhook.

Notes:

payment_method_id: "MP" – dLocal’s identifier for Mercado Pago in Colombia

payment_method_flow: "REDIRECT" – dLocal will host MP auth page & redirect back

wallet.save: false – explicitly indicates this is not an enrollment; no token returned

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

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

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

Behavior:

User completes the payment in MP

On successful approval, dLocal returns a wallet token in its response / notification

Internal tests (see MP Wallet on DLocal page) confirm:

Purchase (One Time) + Recurring with save: true → wallet token created

You should:

Listen for the webhook that includes wallet info / token

Persist that wallet token against the customer record in your system

3.3 Recurring Purchase via Wallet Token

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

Per internal test matrix (MP Wallet on DLocal):

“Recurring Purchase via Wallet Token … It should not ask for payment approval”

Note: it is mandatory to send "description": 200 in the request payload

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

Key points:

wallet.token: required – this is the token you received during enrollment

save: false: no new token created; we’re simply using the existing one

payment_method_flow: "DIRECT" often used for tokenized flows, but align with dLocal settings for your contract

description: "200" is mandatory (per your MP Wallet on dLocal QA notes) – treat this as a fixed integration requirement

3.4 Failure / Invalid Token Cases

From MP Wallet on DLocal QA:

Recurring Purchase with Invalid Token:

Result should be failed, status rejected

Ensure your integration:

Validates the token format before calling dLocal if possible

Handles rejected status gracefully and fails the order/renewal with retry / user-notification strategy

4) Webhook Notifications (notification_url / callback_url)

dLocal sends asynchronous updates for MP 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 (pattern from Efecty/Nequi) looks like:

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

Handling logic:

status = "PENDING": show “processing” to the customer; do not ship / fulfill

status = "PAID" or equivalent approved status:

Mark order as paid
If wallet.token present and save: true was used → persist token

status = "REJECTED" or EXPIRED:

Mark payment as failed
Do not store wallet token

5) Status Mapping

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

Always treat webhook status as source of truth instead of the initial purchase response.

6) Refunds (Full and Partial)

Refund behavior for Mercado Pago via dLocal is consistent with other dLocal APMs:

You can refund one-time and recurring payments after they reach PAID

6.1 Refund One-Time Purchase

Endpoint

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

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

{
  "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": "MP"
  }

6.2 Partial Refund on Recurring Purchase

Flow:

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

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

7) API Field Reference – Mercado Pago Wallet (dLocal)

Field	Example/Type	Notes
payment_method_type (Spreedly)	"mercado_pago"	Use this when creating the Spreedly payment method
payment_method_id (dLocal)	"MP"	dLocal identifier for Mercado Pago in Colombia
payment_method_flow	"DIRECT" / "REDIRECT"	REDIRECT for one-shot; DIRECT often for tokenized flows
country	"CO"	Required for dLocal APM calls
currency / currency_code	"COP"	Must match dLocal’s MP configuration
wallet.save	true / false	true → request wallet token; false → no token
wallet.token	"mp_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 (per internal QA)

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: Bearer {access_token}

{
  "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",
    "callback_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)

Oxxo

Oxxo via dLocal - Overview

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

Key Capabilities

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

Constraints

Country: MX (Mexico) only; Currency: MXN only

Payment method id: OTHERS_CASH_MX

Voucher expiration: Customer can set their own expiration date that is earlier than the default 10-12 days (dLocal)

Integration Checklist

callback_url to get updates from Spreedly
redirect_url to be redirect to customer website in case of REDIRECT
Server clock and idempotency safeguards to handle async updates

Create Oxxo Payment Method

1. API Request

Endpoint

POST /v1/payment_methods.json

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

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

Status Code: 201 Created

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

Field	Type/Example	Description
payment_method_type	String	Must be "oxxo"
country	String	Must be "MX" or “mx'
payment-method -> token	String	Unique identifier for the payment method

Create Oxxo Purchase (Voucher)

Gateway Specific Fields

expiration_date which needs a date value in YYYY-MM-DDTHH:MM:SS format.

Maximum date and time that the payer has to make the payment. This has to be earlier than the default value of 7 days will ignore it and set the default value instead.

"gateway_specific_fields": {
  "payu_latam": {
    "expiration_date": "2021-06-12T16:07:11.586"
  }
}

1. API Request (Purchase)

Endpoint

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

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

Status Code: 202 Accepted

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

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

Pix Automatico

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

This document explains:

The API endpoint for creating an enrollment
Required request/response fields
(GSF / GSRF) requirements
Example request and response

Create Payment Method

1. API Request

Endpoint:

POST /v1/payment_methods.json

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

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

Status Code: 201 Created

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

Field	Type/Example	Description
payment-method -> token	String	Unique identifier for the payment method
payment_method_type	String	Must be "pix_automatico"

Create Enrollments

GSF (Gateway Specific Fields)

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

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

GSRF (Gateway Specific Response Fields)

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

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

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

Common GSRF Parameters:

status (string): Status of enrollment

Enrollment API Request

Endpoint

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

Fixed Amount Enrollment Request:

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

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

Status Code: 202 Accepted

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

Parameters:

Field	Description	Type/Example
callback_url	Webhook URL for status notifications	String
redirect_url	Redirect URL for end user to redirect once action on enrollment has been taken	String
gateway_specific_fields	Gateway-specific parameters as key/value pairs	Object

Create Payment Request for Enrollments

2. GSF (Gateway Specific Fields)

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

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

3. GSRF (Gateway Specific Response Fields)

Gateway Specific Response Fields for payment responses.

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

4. API Request(s)

Manual Payment Request:

Endpoint:

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

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

Status Code: 202 Accepted

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

Field	Type/Example	Description
payment_method_token	String	Active enrollment identifier
currency_code	String
amount	Object	Payment amount (must not exceed max_value)
gateway_specific_fields	Object	Gateway-specific parameters as key/value pair

Create Enrollment + Initial Payment

1. GSF (Gateway Specific Fields)

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

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

2. GSRF (Gateway Specific Response Fields)

Gateway Specific Response Fields for payment responses.

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

3. API Request(s)

Manual Payment Request:

Endpoint:

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

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

Status Code: 202 Accepted

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

Void Enrollment

Endpoint:

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

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

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

Refund Payment

Endpoint:

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

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