EBANX gateway guide
Additional notes |
|---|
EBANX has specific requirements to successfully run certain transactions: |
|
Adding an EBANX gateway
To add an EBANX gateway:
curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODK4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>ebanx</gateway_type>
<integration_key>Your integration_key</integration_key>
</gateway>'<gateway>
<token>K0ditDqMruKYmuHLe74EeqSG1ms</token>
<gateway_type>ebanx</gateway_type>
<name>EBANX</name>
<description nil="true"/>
<merchant_profile_key nil="true"/>
<sub_merchant_key nil="true"/>
<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">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<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">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</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">false</supports_inquire_by_gateway_transaction_id>
<supports_inquire_by_order_id type="boolean">false</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>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>document</gateway_specific_field>
<gateway_specific_field>description</gateway_specific_field>
<gateway_specific_field>birth_date</gateway_specific_field>
<gateway_specific_field>instalments</gateway_specific_field>
<gateway_specific_field>country</gateway_specific_field>
<gateway_specific_field>person_type</gateway_specific_field>
<gateway_specific_field>responsible_name</gateway_specific_field>
<gateway_specific_field>responsible_document</gateway_specific_field>
<gateway_specific_field>responsible_birth_date</gateway_specific_field>
<gateway_specific_field>include_capture_amount</gateway_specific_field>
<gateway_specific_field>device_id</gateway_specific_field>
<gateway_specific_field>metadata</gateway_specific_field>
<gateway_specific_field>processing_type</gateway_specific_field>
<gateway_specific_field>soft_descriptor</gateway_specific_field>
<gateway_specific_field>payment_type_code</gateway_specific_field>
<gateway_specific_field>notification_url</gateway_specific_field>
<gateway_specific_field>merchant_payment_code</gateway_specific_field>
<gateway_specific_field>payment_taxes_iva_co</gateway_specific_field>
<gateway_specific_field>merchant_enrollment_code</gateway_specific_field>
<gateway_specific_field>subscription_name</gateway_specific_field>
<gateway_specific_field>expiration_date</gateway_specific_field>
<gateway_specific_field>frequency</gateway_specific_field>
<gateway_specific_field>retry</gateway_specific_field>
<gateway_specific_field>max_amount_floor</gateway_specific_field>
<gateway_specific_field>fixed_amount</gateway_specific_field>
<gateway_specific_field>start_date</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>third_party_token</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-01-04T20:07:40Z</created_at>
<updated_at type="dateTime">2023-01-04T20:07:40Z</updated_at>
</gateway>Gateway specific fields
When making a transaction, you can specify a number of gateway specific fields (GSFs). Some are required in certain situations:
The processing_type field is used to denote whether a transaction is a cross-border payment. Use this field with a value of local to indicate that the transaction is not a cross-border payment. This can be used with any money moving transaction type.
For any transactions in Colombia, Brazil, Chile, or Argentina, EBANX requires a taxpayer identification number sent in the document field. If the customer is a company rather than an individual, the person_type gateway specific field must be sent as business, and the responsible_name must be provided.
By default, the amount is not sent to EBANX for capture requests, and the full amount reserved from the authorization is captured. To have the capture amount included, send an include_capture_amount gateway specific field with the value true with the capture request. This is necessary for partial captures (only available in Brazil).
When refunding with EBANX, a description field is necessary. Spreedly does not support a default description like with purchase or authorize for refund requests so it must be passed as a gateway specific field.
When storing a card with EBANX, a two-letter country code must be sent in the country gateway specific field.
The device_id field can be used for device fingerprinting, which is used by anti-fraud tools.
The soft_descriptor field can optionally be sent with purchase or authorize requests.
A number of payment instalments can be sent with the instalments gateway specific field.
The payment_type_code field can be used to indicate the credit card scheme. Optional examples: amex, aura, diners, discover, elo, hipercard, mastercard, visa.
The notification_url field can be used to send notifications for this payment. If this field is filled, EBANX will notify using this URL instead of the configured one.
The merchant_payment_code is an optional field that specifies the Merchant Payment Code (unique merchant ID). In the absence of an explicit merchant_payment_code field, Spreedly will supply the transaction's order_id in its place.
The payment_taxes_iva_co field can be used to send Colombia Local Tax details.
Local payment method Gateway Specific Fields
These gateway specific fields are used when transacting with a Local Payment Method (LPM). For more information, please refer to the specific section for that payment method type.
The merchant_enrollment_codeis a unique enrollment code that should be passed by the merchant when generating enrollment and then on each subsequent purchase. Required for Pix Automatico and NuPay (Recurrent).
void_enrollmentshould be sent with value true on a void transaction if you are looking to cancel an enrollment of a recurring payment method instead of a single payment.
Pix Automatico has several fields:
Subscriptionis an object that contains the following GSFs:
frequency: The billing cycle of the enrollment. Available frequencies are:weekly,monthly,quarterly,halfyearly,yearly.retry: Determines whether the merchant will retry payments that fail on the expected billing day. The available retry policies are:not_allowedfor no additional attempts orallow_3R_7Dfor up to three retries within seven days after the first payment
GSF Formats
These fields can be sent as below:
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>
<ebanx>
<document>taxpayer ID</document>
<birth_date>01/01/1990</birth_date>
<instalments>3</instalments>
<description>Reason for Refund</description>
<person_type>business</person_type>
<responsible_name>Responsible Person</responsible_name>
<responsible_document>Responsible Document Number</responsible_document>
<responsible_birth_date>dd/mm/yyyy</responsible_birth_date>
<device_id>34c376b2767</device_id>
<gateway_specific_field>merchant_enrollment_code</gateway_specific_field>
<subscription_name>subscription_name</subscription_name>
<expiration_date>expiration_date</expiration_date>
<retry>retry</retry>
<max_amount_floor>max_amount_floor</max_amount_floor>
<fixed_amount>fixed_amount</fixed_amount>
<start_date>start_date</start_date>
<metadata>
<metadata_1>test</metadata_1>
<metadata_2>test2</metadata_2>
</metadata>
<processing_type>local</processing_type>
<soft_descriptor>Spreedly</soft_descriptor>
<payment_type_code>visa</payment_type_code>
<notification_url>https://notify.example.com/</notification_url>
<merchant_payment_code>12345</merchant_payment_code>
</ebanx>
</gateway_specific_fields>
</transaction>'Gateway specific response fields
A response from the gateway may contain the following gateway specific response fields:
For refund transactions, the additional refund_id may be returned as a gateway specific response field.
<transaction>
<token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
<transaction_type>Purchase</transaction_type>
<gateway_specific_response_fields>
<ebanx>
<pix_qr_code>123456</pix_qr_code>
<oxxo_barcode>123456</oxxo_barcode>
<boleto_barcode_raw>123456</boleto_barcode_raw>
<boleto_barcode>123456</boleto_barcode>
<payment_type_code>creditcard</payment_type_code>
<enrollment_status>enrollment_status</enrollment_status>
<pix_automatico_qr_code>pix_automatico_qr_code</pix_automatico_qr_code>
<amount_br>5.45</amount_br>
<amount_ext>1.00</amount_ext>
<amount_iof>0.18</amount_iof>
<currency_rate>5.2700</currency_rate>
<currency_ext>USD</currency_ext>
<payment_status>PE</payment_status>
<transaction_status>
<description>Accepted<description>
<code>OK<code>
<authcode>12345<authcode>
<acquirer>EBANX<acquirer>
</transaction_status>
</ebanx>
</gateway_specific_response_fields>
</transaction>Syncing transactions
Spreedly supports updating the status of transactions that have been initiated at the Ebanx gateway. Ebanx currently only supports using gateway_transaction_id for updates which would be the id of the transaction. See our documentation for more information.
Local payment methods
Spreedly supports a variety of payment methods through Ebanx. Each may require unique parameters and flows. Please expand each payment method's details to find implementation information. Gateway Specific Fields that are denoted only for the local payment method are detailed in each section, but the general Gateway Specific Fields may also be able to be utilized in combination with each payment method.
For most LPMs, the examples show creating a payment method and then a transaction as separate steps. However, the “pass in method” may be used by directly passing in the payment method information to the initial transaction. If using that method, make sure you record both the payment method token and the transaction token in the response.
Most of these payment methods rely on asynchronous action from the end user. The transactions will remain ‘pending’ until Spreeldy has been notified of a completion event. If you do not pass a callback URL and rely only on notifications directly from Ebanx, transactions in Spreedly will remain pending.
OXXO
Oxxo
Spreedly supports payments using Oxxo on Ebanx.
Payment Transaction Flow
- Create Payment Method: Customer details stored in Spreedly
- Initiate Purchase: Customer redirected to the Oxxo voucher
- Customer Pays: Your customer visits any OXXO store, presents the barcode (either printed or on their mobile device), and pays in cash or with a debit/credit card.
- Callback: Transaction status updated via webhook and you are notified Confirmation may take up to 3 business days.
Create a Payment Method
The first step is to create an Oxxo payment method. Required Fields:
- country
- full_name or first_name and last_name
- phone_number
POST 'https://core.spreedly.com/v1/payment_methods.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG9mejMyWkJlVUZ=' \
--body '{
"payment_method": {
"email": "[email protected]",
"payment_method_type": "oxxo",
"full_name": "Manuela E. Beyer Rocabado",
"country": "MX",
"zip": "48822",
"address1": "Oyono, 882",
"city": "Hermosillo",
"state": "Sonora",
"phone_number": "(040) 577-7687"
}
}'Create a Purchase Request
Create a request to the Purchase endpoint. Show the voucher by redirecting to response.checkout_url.
The transaction will remain pending until actioned by the user, at which point a callback will be sent by Spreedly. When testing, you may need to log in to your Ebanx dashboard and action the payment manually to complete.
POST 'https://core.spreedly.com/v1/gateways/{Gateway Token}/purchase.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG9mejMyWkJ3VNdVQ=' \
--body '{
"transaction": {
"payment_method_token": "payment method token",
"amount": 600,
"currency_code": "MXN",
"callback_url": "url where you want to receive callbacks",
"redirect_url": "url where you want the user to be returned to",
"gateway_specific_fields": {
"ebanx": {
}
}
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-12-11T21:20:04Z",
"updated_at": "2025-12-11T21:20:05Z",
"succeeded": false,
"state": "pending",
"token": "01KC7MJ3KZ67ZDA2TE972TYHGR",
"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": {
"ebanx": {}
},
"gateway_specific_response_fields": {
"ebanx": {
"oxxo_barcode": "00000000000000000000000000000000",
"amount_br": "6.00",
"amount_ext": "6.00",
"amount_iof": "0.00",
"currency_rate": "1.0000",
"currency_ext": "MXN",
"payment_status": "PE"
}
},
"gateway_transaction_id": "693b3584b75d46e98dcd8e785e497d879d788f8e8204997e",
"sub_merchant_key": null,
"gateway_latency_ms": 548,
"warning": null,
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"protection_parameters": {},
"amount": 600,
"local_amount": null,
"currency_code": "MXN",
"reference": "693b3584b75d46e98dcd8e785e497d879d788f8e8204997e",
"setup_verification": null,
"expiration_date": "2025-12-14 00:00:00 +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": "7DPQMT82S88DRVEW0ZCGTZYMVH",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Setup completed",
"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-11T21:20:05Z",
"updated_at": "2025-12-11T21:20:05Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/print/oxxo?hash=693b3584b75d46e98dcd8e785e497d879d788f8e8204997e"
},
"shipping_address": {
"name": "Manuela E. Beyer Rocabado",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml"
]
}
],
"redirect_url": "https://spreedly.com",
"checkout_url": "https://sandbox.ebanx.com/print/oxxo?hash=693b3584b75d46e98dcd8e785e497d879d788f8e8204997e",
"callback_url": "https://webgrab.requestcatcher.com/",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "Setup completed",
"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-11T21:20:05Z",
"updated_at": "2025-12-11T21:20:05Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/print/oxxo?hash=693b3584b75d46e98dcd8e785e497d879d788f8e8204997e"
},
"payment_method": {
"token": "01KC7MGJDD44XT63PMMD1NGYXE",
"created_at": "2025-12-11T21:19:14.349Z",
"updated_at": "2025-12-11T21:19:14.349Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Manuela E. Beyer Rocabado",
"first_name": "Manuela E. Beyer",
"last_name": "Rocabado",
"bic": null,
"payment_method_type": "oxxo",
"errors": []
}
}
}POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Content-Length: 6250
Content-Type: application/xml
Traceparent: 00-693b3a82000000001a8bb6a921b70a53-1e6c0c966223c05c-00
Tracestate: dd=p:1e6c0c966223c05c;s:0
User-Agent: Ruby
X-Datadog-Parent-Id: 2192140958653726812
X-Datadog-Sampling-Priority: 0
X-Datadog-Tags: _dd.p.tid=693b3a8200000000
X-Datadog-Trace-Id: 1912823304280279635
<transactions>
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2025-12-11T21:29:46Z</created_at>
<updated_at type="dateTime">2025-12-11T21:41:22Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>01KC7MJ3KZ67ZDA2TE972TYHGR</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>
<ebanx>
</ebanx>
</gateway_specific_fields>
<gateway_specific_response_fields>
<ebanx>
<amount_br>6.00</amount_br>
<amount_ext>6.00</amount_ext>
<amount_iof>0.00</amount_iof>
<currency_rate>1.0000</currency_rate>
<currency_ext>MXN</currency_ext>
<payment_status>PE</payment_status>
<payment_type_code>oxxo</payment_type_code>
</ebanx>
</gateway_specific_response_fields>
<gateway_transaction_id>693b37ca38f20b4075de5687075cb9193c9deb8f0b930a91</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">222</gateway_latency_ms>
<warning nil="true"/>
<application_id nil="true"/>
<risk_data>
</risk_data>
<merchant_metadata>
</merchant_metadata>
<customer_data>
</customer_data>
<order_data>
</order_data>
<workflow_key nil="true"/>
<protection_parameters>
</protection_parameters>
<amount type="integer">600</amount>
<local_amount nil="true"/>
<currency_code>MXN</currency_code>
<reference>693b37ca38f20b4075de5687075cb9193c9deb8f0b930a91</reference>
<setup_verification nil="true"/>
<expiration_date>2025-12-14 00:00:00 +0000</expiration_date>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<stored_credential_final_payment type="boolean">false</stored_credential_final_payment>
<retain_on_success type="boolean">false</retain_on_success>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>7DPQMT82S88DRVEW0ZCGTZYMVH</gateway_token>
<gateway_type>ebanx</gateway_type>
<shipping_address>
<name>Manuela E. Beyer Rocabado</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>The payment was successfully completed.</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">2025-12-11T21:41:21Z</created_at>
<updated_at type="dateTime">2025-12-11T21:41:22Z</updated_at>
<status nil="true"/>
</response>
<api_urls>
<callback_conversations>https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml</callback_conversations>
</api_urls>
<signed>
<signature>11ffed4c51333f5bddf81850f613ecf7c3f86a33</signature>
<fields>amount created_at currency_code ip local_amount on_test_gateway order_id state succeeded token transaction_type updated_at</fields>
<algorithm>sha1</algorithm>
</signed>
<payment_method>
<token>01KC7MGJDD44XT63PMMD1NGYXE</token>
<created_at>2025-12-11T21:19:14.349Z</created_at>
<updated_at>2025-12-11T21:29:37.264Z</updated_at>
<email>[email protected]</email>
<data nil="true"/>
<storage_state>used</storage_state>
<test type="boolean">false</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<full_name>Manuela E. Beyer Rocabado</full_name>
<first_name>Manuela E. Beyer</first_name>
<last_name>Rocabado</last_name>
<bic nil="true"/>
<payment_method_type>oxxo</payment_method_type>
<errors>
</errors>
</payment_method>
<callback_url>callback</callback_url>
<callback_response>
<success type="boolean">true</success>
<message>The payment was successfully completed.</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">2025-12-11T21:41:21Z</created_at>
<updated_at type="dateTime">2025-12-11T21:41:22Z</updated_at>
<status nil="true"/>
</callback_response>
<redirect_url>https://spreedly.com</redirect_url>
<checkout_url>https://sandbox.ebanx.com/print/oxxo?hash=693b37ca38f20b4075de5687075cb9193c9deb8f0b930a91</checkout_url>
<callback_url>callback url/</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>Setup completed</message>
<error_code nil="true"/>
<checkout_url>https://sandbox.ebanx.com/print/oxxo?hash=693b37ca38f20b4075de5687075cb9193c9deb8f0b930a91</checkout_url>
<created_at type="dateTime">2025-12-11T21:29:47Z</created_at>
<updated_at type="dateTime">2025-12-11T21:29:47Z</updated_at>
</setup_response>
</transaction>
</transactions>Boleto Bancario
Boleto Bancario
Spreedly supports payments using Boleto on Ebanx.
Payment Transaction Flow
- Create Payment Method: Customer details stored in Spreedly
- Initiate Purchase: Customer redirected to the Boleto slip
- Customer Pays: The customer pays the Boleto at a bank, ATM, or through their banking app using the barcode
- Callback: Transaction status updated via webhook Confirmation may take up to 3 business days.
Create a Payment Method
The first step is to create a Boleto bancario payment method. Required Fields:
- country
- full_name or first_name and last_name
- zip
- address1
- city
- state
- phone_number
- document_id
POST 'https://core.spreedly.com/v1/payment_methods.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Og==' \
--body '{
"payment_method": {
"email": "[email protected]",
"payment_method_type": "boleto_bancario",
"full_name": "Ana Santos Araujo", //either full_name or first_name and last_name
"document_id": "853.513.468-93",
"country": "BR",
"zip": "12345",
"address1": "Rua E, 1040",
"city": "Maracanaú",
"state": "CE",
"phone_number": "8522847035"
}
}'Create a Purchase transaction
Create a request to the Purchase endpoint. Then choose one of the following to show the voucher:
- show the voucher by redirecting to response.checkout_url
- Display the barcode directly using the value in gateway_specific_response_fields.ebanx.boleto_barcode For each of these options, refer to best practices and brand requirements The transaction will remain pending until actioned by the user, at which point a callback will be sent by Spreedly. When testing, you may need to log in to your Ebanx dashboard and action the payment manually to complete.
POST 'https://core.spreedly.com/v1/gateways/{Gateway token}/purchase.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG9mejMyWkJlVUZpa' \
--body '{
"transaction": {
"payment_method_token": "{{payment method token}}",
"amount": 100,
"currency_code": "BRL",
"callback_url": "url where you want to receive callbacks",
"redirect_url": "url where you want the user to be returned to",
"gateway_specific_fields": {
"ebanx": {
// "due_date" //optional boleto expiry date in the format dd/mm/yyyy
}
}
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-12-11T20:31:43Z",
"updated_at": "2025-12-11T20:31:44Z",
"succeeded": false,
"state": "pending",
"token": "01KC7HSJKM9S3MT6ZYJZSK2T6S",
"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": {
"ebanx": {}
},
"gateway_specific_response_fields": {
"ebanx": {
"boleto_barcode_raw": "34197129500000001041760041698803721424574000",
"boleto_barcode": "34191760074169880372714245740007712950000000104", //barcode for display
"amount_br": "1.04",
"amount_ext": "1.00",
"amount_iof": "0.04",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"payment_status": "PE"
}
},
"gateway_transaction_id": "693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d",
"sub_merchant_key": null,
"gateway_latency_ms": 656,
"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": "BRL",
"reference": "693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d",
"setup_verification": null,
"expiration_date": "2025-12-14 00:00:00 +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": "7DPQMT82S88DRVEW0ZCGTZYMVH",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Setup completed",
"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-11T20:31:44Z",
"updated_at": "2025-12-11T20:31:44Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/print?hash=693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d" // send the customer here
},
"shipping_address": {
"name": "Ana Santos Araujo",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml"
]
}
],
"redirect_url": "https://spreedly.com",
"checkout_url": "https://sandbox.ebanx.com/print?hash=693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d",
"callback_url": "https://webgrab.requestcatcher.com/",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "Setup completed",
"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-11T20:31:44Z",
"updated_at": "2025-12-11T20:31:44Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/print?hash=693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d"
},
"payment_method": {
"token": "01KC7HS44PX6SPBBY3JEW1648H",
"created_at": "2025-12-11T20:31:28.918Z",
"updated_at": "2025-12-11T20:31:28.918Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "boleto_bancario",
"errors": []
}
}
}POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Content-Length: 6231
Content-Type: application/xml
Traceparent: 00-693b2c30000000002139b34d759c640d-072f51c5dbc1fb45-00
Tracestate: dd=p:072f51c5dbc1fb45;s:0
User-Agent: Ruby
X-Datadog-Parent-Id: 517722392408226629
X-Datadog-Sampling-Priority: 0
X-Datadog-Tags: _dd.p.tid=693b2c3000000000
X-Datadog-Trace-Id: 2394141822191166477
<transactions>
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2025-12-11T20:31:43Z</created_at>
<updated_at type="dateTime">2025-12-11T20:40:16Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state> //payment was successful
<token>01KC7HSJKM9S3MT6ZYJZSK2T6S</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>
<ebanx>
</ebanx>
</gateway_specific_fields>
<gateway_specific_response_fields>
<ebanx>
<amount_br>1.04</amount_br>
<amount_ext>1.00</amount_ext>
<amount_iof>0.04</amount_iof>
<currency_rate>1.0000</currency_rate>
<currency_ext>BRL</currency_ext>
<payment_status>PE</payment_status>
<payment_type_code>boleto</payment_type_code>
</ebanx>
</gateway_specific_response_fields>
<gateway_transaction_id>693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">165</gateway_latency_ms>
<warning nil="true"/>
<application_id nil="true"/>
<risk_data>
</risk_data>
<merchant_metadata>
</merchant_metadata>
<customer_data>
</customer_data>
<order_data>
</order_data>
<workflow_key nil="true"/>
<protection_parameters>
</protection_parameters>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>BRL</currency_code>
<reference>693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d</reference>
<setup_verification nil="true"/>
<expiration_date>2025-12-14 00:00:00 +0000</expiration_date>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<stored_credential_final_payment type="boolean">false</stored_credential_final_payment>
<retain_on_success type="boolean">false</retain_on_success>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>7DPQMT82S88DRVEW0ZCGTZYMVH</gateway_token>
<gateway_type>ebanx</gateway_type>
<shipping_address>
<name>Ana Santos Araujo</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>The payment was successfully completed.</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">2025-12-11T20:40:16Z</created_at>
<updated_at type="dateTime">2025-12-11T20:40:16Z</updated_at>
<status nil="true"/>
</response>
<api_urls>
<callback_conversations>https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml</callback_conversations>
</api_urls>
<signed>
<signature>b5f8792709cdf46a1d8ccd83e7e9c5cb68c71e6a</signature>
<fields>amount created_at currency_code ip local_amount on_test_gateway order_id state succeeded token transaction_type updated_at</fields>
<algorithm>sha1</algorithm>
</signed>
<payment_method>
<token>01KC7HS44PX6SPBBY3JEW1648H</token>
<created_at>2025-12-11T20:31:28.918Z</created_at>
<updated_at>2025-12-11T20:31:28.918Z</updated_at>
<email>[email protected]</email>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">false</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<full_name>Ana Santos Araujo</full_name>
<first_name>Ana Santos</first_name>
<last_name>Araujo</last_name>
<bic nil="true"/>
<payment_method_type>boleto_bancario</payment_method_type>
<errors>
</errors>
</payment_method>
<callback_url>https://webgrab.requestcatcher.com/</callback_url>
<callback_response>
<success type="boolean">true</success>
<message>The payment was successfully completed.</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">2025-12-11T20:40:16Z</created_at>
<updated_at type="dateTime">2025-12-11T20:40:16Z</updated_at>
<status nil="true"/>
</callback_response>
<redirect_url>https://spreedly.com</redirect_url>
<checkout_url>https://sandbox.ebanx.com/print?hash=693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d</checkout_url>
<callback_url>https://webgrab.requestcatcher.com/</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>Setup completed</message>
<error_code nil="true"/>
<checkout_url>https://sandbox.ebanx.com/print?hash=693b2a2f53b1036ca4a5501bf543d8fbac2c8f9e8f9cf70d</checkout_url>
<created_at type="dateTime">2025-12-11T20:31:44Z</created_at>
<updated_at type="dateTime">2025-12-11T20:31:44Z</updated_at>
</setup_response>
</transaction>
</transactions>Mercado Pago Recurring
Mercado Pago Recurring
Mercado Pago Recurring
Spreedly supports Mercado Pago recurring payments using Ebanx. The general steps are as follows:
Step 1: Enrollment
This is an example request body to perform an enrollment agreement required by Mercado Pago. The recurring field indicates that this a recurring payment method and is only available for Mercado Pago.
In the response, Spreedly returns a checkout_url and the merchant must redirect their customer to that Mercado Pago checkout URL to accept or deny the enrollment agreement.
To cancel the enrollment the merchant must perform a void request on this Verification.
curl https://core.spreedly.com/v1/gateways/{Gateway token}/verify.json \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/json' \
-d '{
{
"transaction": {
"payment_method": {
"email": "[email protected]",
"payment_method_type": "mercado_pago",
"full_name": "Full Name",
"document_id": "71575743221",
"country": "BR",
"zip": "12345",
"address1": "1234 test ave",
"city": "Rio",
"state": "CE",
"phone_number": "8522847035",
"recurring": true
},
"gateway_specific_fields": {
"ebanx": {
"merchant_enrollment_code": "12345"
}
}
}
}
}'Step 2: Purchase
curl https://core.spreedly.com/v1/gateways/{Gateway Token}/purchase.json \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '{
{
"transaction": {
"payment_method_token": "{Payment method token}",
"amount": 100,
"currency_code": "USD",
"callback_url": "https://example.com",
"redirect_url": "https://example.com"
}
}
}'Pix
Pix
One time Pix payments follow a separate flow from Pix Automatico. These payments do not need enrollment.
Payment Transaction Flow
- Create Payment Method: Customer details stored in Spreedly
- Initiate Purchase: Redirect the user using the checkout url to display the Pix Voucher and QR code
- Customer Pays: Customer utilizes the QR Code to complete the payment
- Callback: Transaction status updated via webhook and you are notified
Create a Payment Method
The first step is to create a Pix payment method. Required Fields:
- country
- full_name or first_name and last_name
- zip
- address1
- city
- state
- phone_number
- document_id
POST 'https://core.spreedly.com/v1/payment_methods.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG9mejMyWkJlVUZ=' \
--body '{
"payment_method": {
"email": "[email protected]",
"payment_method_type": "pix",
"full_name": "Ana Santos Araujo", //either full_name or first_name and last_name
"document_id": "853.513.468-93",
"country": "BR",
"zip": "12345",
"address1": "Rua E, 1040",
"city": "Maracanaú",
"state": "CE",
"phone_number": "8522847035"
}
}'Create a Purchase Request
Create a request to the Purchase endpoint. Show the voucher by redirecting to response.checkout_url.
The transaction will remain pending until actioned by the user, at which point a callback will be sent by Spreedly. When testing, you may need to log in to your Ebanx dashboard and action the payment manually to complete.
POST 'https://core.spreedly.com/v1/gateways/7DPQS88DRVEW0ZCGTZYMVH/purchase.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG9mejMyWkJlVUZpa' \
--body '{
"transaction": {
"payment_method_token": "{{payment method token}}",
"amount": 100,
"currency_code": "BRL",
"callback_url": "url where you want to recieve callbacks",
"redirect_url": "url where you want the user to be returned to",
"gateway_specific_fields": {
"ebanx": {
// "expiration_time_in_seconds" //optional if you want the payment to expire at a specific time
}
}
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-12-11T19:42:29Z",
"updated_at": "2025-12-11T19:42:30Z",
"succeeded": false,
"state": "pending",
"token": "01KC7EZDMHW4H1D5DAGJ0TBVJY",
"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": {
"ebanx": {
"document": "853.513.468-93"
}
},
"gateway_specific_response_fields": {
"ebanx": {
"pix_qr_code": "00020101021226780014br.gov.bcb.pix2556fake-pix.com.br/qr/v2/ACA4311F88661BC0D48200487EF1BCD95204000053039865802BR5910FAKEPIX Ltda6008CURITIBA62070503***93610",
"amount_br": "5.45",
"amount_ext": "1.00",
"amount_iof": "0.18",
"currency_rate": "5.2700",
"currency_ext": "USD",
"payment_status": "PE",
"redirect_url": "https://sandbox.ebanx.com/pix/checkout?hash=693b1ea50599841fa9a4956094e860b195ec7f5ef603b3b1"
}
},
"gateway_transaction_id": "693b1ea50599841fa9a4956094e860b195ec7f5ef603b3b1",
"sub_merchant_key": null,
"gateway_latency_ms": 509,
"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": "USD",
"reference": "693b1ea50599841fa9a4956094e860b195ec7f5ef603b3b1",
"setup_verification": null,
"expiration_date": "2025-12-11 00:00:00 +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": "7DPQMT82S88DRVEW0ZCGTZYMVH",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Setup completed",
"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-11T19:42:30Z",
"updated_at": "2025-12-11T19:42:30Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/pix/checkout?hash=693b1ea50599841fa9a4956094e860b195ec7f5ef603b3b1" //send the user here
},
"shipping_address": {
"name": "Ana Santos Araujo",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml"
]
}
],
"redirect_url": "https://spreedly.com",
"checkout_url": "https://sandbox.ebanx.com/pix/checkout?hash=693b1ea50599841fa9a4956094e860b195ec7f5ef603b3b1",
"callback_url": "https://webgrab.requestcatcher.com/",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "Setup completed",
"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-11T19:42:30Z",
"updated_at": "2025-12-11T19:42:30Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/pix/checkout?hash=693b1ea50599841fa9a4956094e860b195ec7f5ef603b3b1"
},
"payment_method": {
"token": "01KC7EVB98EGG1KGQMG503TKZE",
"created_at": "2025-12-11T19:40:16.040Z",
"updated_at": "2025-12-11T19:40:16.040Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "pix",
"errors": []
}
}
}
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Content-Length: 6670
Content-Type: application/xml
Traceparent: 00-693b265a00000000322a2802f30d0d18-1dd6ab3fd8c2fa15-01
Tracestate: dd=p:1dd6ab3fd8c2fa15;s:1;t.dm:-1
User-Agent: Ruby
X-Datadog-Parent-Id: 2150094162823936533
X-Datadog-Sampling-Priority: 1
X-Datadog-Tags: _dd.p.dm=-1,_dd.p.tid=693b265a00000000
X-Datadog-Trace-Id: 3614745644051008792
<transactions>
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2025-12-11T20:07:47Z</created_at>
<updated_at type="dateTime">2025-12-11T20:15:22Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state> // the payment succeeded
<token>01KC7GDQWQBZ5PG0EVNHGE0CAZ</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>
<ebanx>
</ebanx>
</gateway_specific_fields>
<gateway_specific_response_fields>
<ebanx>
<pix_qr_code>00020101021226780014br.gov.bcb.pix2556fake-pix.com.br/qr/v2/ACA4311F88661BC0D48200487EF1BCD95204000053039865802BR5910FAKEPIX Ltda6008CURITIBA62070503***50385</pix_qr_code>
<amount_br>1.04</amount_br>
<amount_ext>1.00</amount_ext>
<amount_iof>0.04</amount_iof>
<currency_rate>1.0000</currency_rate>
<currency_ext>BRL</currency_ext>
<payment_status>PE</payment_status>
<payment_type_code>pix</payment_type_code>
<transaction_status>
<acquirer>EBANX</acquirer>
<code>OK</code>
<description>Payment successfully paid</description>
<description_code>ACCEPTED</description_code>
</transaction_status>
</ebanx>
</gateway_specific_response_fields>
<gateway_transaction_id>693b2493f002e63b6a9784530e4241545c89a984ee19f6bd</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">219</gateway_latency_ms>
<warning nil="true"/>
<application_id nil="true"/>
<risk_data>
</risk_data>
<merchant_metadata>
</merchant_metadata>
<customer_data>
</customer_data>
<order_data>
</order_data>
<workflow_key nil="true"/>
<protection_parameters>
</protection_parameters>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>BRL</currency_code>
<reference>693b2493f002e63b6a9784530e4241545c89a984ee19f6bd</reference>
<setup_verification nil="true"/>
<expiration_date>2025-12-11 00:00:00 +0000</expiration_date>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<stored_credential_final_payment type="boolean">false</stored_credential_final_payment>
<retain_on_success type="boolean">false</retain_on_success>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>7DPQMT82S88DRVEW0ZCGTZYMVH</gateway_token>
<gateway_type>ebanx</gateway_type>
<shipping_address>
<name>Ana Santos Araujo</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>The payment was successfully completed.</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>OK</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2025-12-11T20:15:22Z</created_at>
<updated_at type="dateTime">2025-12-11T20:15:22Z</updated_at>
<status nil="true"/>
</response>
<api_urls>
<callback_conversations>https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml</callback_conversations>
</api_urls>
<signed>
<signature>a822320df9ba1b8a01149e1b6c46ed03dbb867c3</signature>
<fields>amount created_at currency_code ip local_amount on_test_gateway order_id state succeeded token transaction_type updated_at</fields>
<algorithm>sha1</algorithm>
</signed>
<payment_method>
<token>01KC7GDJMR3DH8J9A8C7T5MQ4X</token>
<created_at>2025-12-11T20:07:41.976Z</created_at>
<updated_at>2025-12-11T20:07:41.976Z</updated_at>
<email>[email protected]</email>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">false</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<full_name>Ana Santos Araujo</full_name>
<first_name>Ana Santos</first_name>
<last_name>Araujo</last_name>
<bic nil="true"/>
<payment_method_type>pix</payment_method_type>
<errors>
</errors>
</payment_method>
<callback_url>https://webgrab.requestcatcher.com/</callback_url>
<callback_response>
<success type="boolean">true</success>
<message>The payment was successfully completed.</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>OK</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2025-12-11T20:15:22Z</created_at>
<updated_at type="dateTime">2025-12-11T20:15:22Z</updated_at>
<status nil="true"/>
</callback_response>
<redirect_url>https://spreedly.com</redirect_url>
<checkout_url>https://sandbox.ebanx.com/pix/checkout?hash=693b2493f002e63b6a9784530e4241545c89a984ee19f6bd</checkout_url>
<callback_url>https://webgrab.requestcatcher.com/</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>Setup completed</message>
<error_code nil="true"/>
<checkout_url>https://sandbox.ebanx.com/pix/checkout?hash=693b2493f002e63b6a9784530e4241545c89a984ee19f6bd</checkout_url>
<created_at type="dateTime">2025-12-11T20:07:47Z</created_at>
<updated_at type="dateTime">2025-12-11T20:07:47Z</updated_at>
</setup_response>
</transaction>
</transactions>
Pix Automatico
Pix Automatico
Pix Automatico
Spreedly supports Pix Automatico recurring payments using Ebanx. Make sure you have Pix Automatico configured as a supported payment method with your Ebanx account, including notifications of enrollment. The general steps are as follows:
Step 1: Enrollment
This is an example request body to perform an enrollment agreement required by Pix Automatico. Spreedly supports both Fixed and Variable Enrollments as well as Instant Payment + Enrollment.
In the response, Spreedly returns a checkout_url along with a Raw QR Code GSRF. The merchant can redirect their customer to the Pix Automatico checkout URL to accept or deny the enrollment agreement or display the QR code to their user to scan with their banking app.
Once the user accepts the enrollment agreement, EBANX sends the updated enrollment transaction status to Spreedly via a webhook Spreedly then updates the transaction with the latest status and, after doing so, delivers the updated transaction response via the callback_url provided in the original enrollment transaction to notify the merchant.
To cancel the enrollment the merchant must perform a void request on this Verification.
Step 1: Enrollment Request Using Verify
//JSON
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/verify.json \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqynYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/json' \
-d '{
{
"transaction": {
"payment_method": {
"payment_method_type": "pix_automatico",
"full_name": "full name",
"document_id": "12335",
"country_code": "BR",
"email": "[email protected]"
},
"gateway_specific_fields": {
"ebanx": {
"merchant_enrollment_code": "123-456-789-dfdfdfd",// mandatory
"subscription": {
"subscription_name": "Descriptor of the subscription.",// mandatory
"expiration_date": "2025-12-30",// optional
"frequency": "monthly",// mandatory
"retry": "allow_3R_7D",// mandatory
"fixed_amount": 100.00, // mandatory field for fixed amount enrollment
"max_amount_floor": 100.00, // mandatory field for variable amount enrollment
"start_date": "2025-10-02"
}
}
},
"callback_url": "https://your-domain.com/callback"
}
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-09-29T04:35:51Z",
"updated_at": "2025-09-29T04:35:55Z",
"succeeded": false,
"state": "processing",
"token": "FSgW16Q9OXLG4QHCwLWyOTpDWpx",
"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": {
"ebanx": {
"merchant_enrollment_code": "123-456-789-dfdfdfd",
"subscription": {
"subscription_name": "Descriptor of the subscription.",
"expiration_date": "2025-12-30",
"frequency": "monthly",
"retry": "allow_3R_7D",
"max_amount_floor": 100,
"start_date": "2025-10-02"
},
"notification_url": "http://core.spreedly.test/transaction/FSgW16Q9OXLG4QHCwLWyOTpDWpx/callback"
}
},
"gateway_specific_response_fields": {
"ebanx": {
"pix_automatico_qr_code": "00020101021226780014br.gov.bcb.pix2556fake-pix.com.br/qr/v2/ACA4311F88661BC0D48200487EF1BCD95204000053039865802BR5910FAKEPIX Ltda6008CURITIBA62070503***18663",
"enrollment_status": "pending"
}
},
"gateway_transaction_id": null, # NO gateway transaction ID in this case
"gateway_latency_ms": 1184,
"currency_code": null,
"retain_on_success": false,
"payment_method_added": false,
"stored_credential_final_payment": false,
"message_key": "messages.transaction_processing",
"message": "Processing",
"gateway_token": "29TBCAD7P18WVV1E5G0DANV3YT",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Finish enrolling by responding to the enrollment agreement.",
"pending": true,
...
"checkout_url": "https://sandbox.ebanx.com/ewallet/recurrency-agreement?return_url=https%3A%2F%2Fsandbox.ebanx.com%2Fws%2Fcustomerenrollment-finish%2Ffake%3Fenrollment%3DNDYxMDM6MTIzLTQ1Ni03ODktZGZkZmRmZA%253D%253D&enrollment_uuid=DNKmaBb6M3jVybFpdgBge2"
},
"shipping_address": {
"name": "full name",
},
"redirect_url": "https://your-domain.com/success",
"callback_url": "https://your-domain.com/callback",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"payment_method": {
...
}
}
}Step 2: Payment Using Purchase
To create a payment, utilize the Purchase endpoint.
//JSON
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '{
{
transaction: {
payment_method_token: "{{pm_token}}",
amount: 100,
currency_code: "BRL",
gateway_specific_fields: {
ebanx: {
merchant_payment_code: "123-456-678", //unique payment code from merchant
merchant_enrollment_code: "mer", //Merchant enrollment code which was used during initial enrollement
due_date: "17/10/2025", //this has an alternative date format to be aware of
}
},
callback_url: 'https://example.com',
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-09-29T08:49:21Z",
"updated_at": "2025-09-29T08:49:23Z",
"succeeded": false,
"state": "processing",
"token": "ko7N87f4g9jzpflhnt3Megx2ri",
"transaction_type": "OffsitePurchase",
"gateway_specific_fields": {
"ebanx": {
"document": "98765432100",
"merchant_payment_code": "123-456-678",
"merchant_enrollment_code": "123-456-789-dfdfdfd",
"due_date": "02/10/2025"
}
},
"gateway_specific_response_fields": {
"ebanx": {
"amount_br": "1.04",
"amount_ext": "1.00",
"amount_iof": "0.04",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"retries": {
"retry_status": "LOCKED",
"available_retries": 3,
"payment_attempts": [
{
"attempted_at": "2025-09-29 09:00:54",
"attempt_response": "PENDING"
}
]
},
}
},
"gateway_transaction_id": "68da481403386311ae327dedf2e3a493e467b73407cbd2f4",
"sub_merchant_key": null,
"gateway_latency_ms": 1179,
"amount": 100,
"local_amount": null,
"currency_code": "BRL",
"reference": "68da481403386311ae327dedf2e3a493e467b73407cbd2f4",
"setup_verification": null,
"expiration_date": "2025-10-02 00:00:00 +0530",
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_processing",
"message": "Processing",
"gateway_token": "29TBCAD7P18WVV1E5G0DANV3YT",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Setup completed",
...
"checkout_url": "https://sandbox.ebanx.com/ws/redirect?hash=68da481403386311ae327dedf2e3a493e467b73407cbd2f4"
},
"api_urls": [],
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "Setup completed",
...
"checkout_url": "https://sandbox.ebanx.com/ws/redirect?hash=68da481403386311ae327dedf2e3a493e467b73407cbd2f4"
},
"callback_url": null,
"payment_method": {
...
}
}
}
Instant Payment + Enrollment
To create an Instant Payment + Enrollment pass gateway specific fields merchant_enrollment_code & subscription in the Payment (Purchase) request with Spreedly. A standard Payment does not require enrollment details like subscription.
//JSON
{
"transaction": {
"payment_method_token": "P9SWFjDZ4fuzntaprDIcpNiTOir",
"gateway_specific_fields": {
"ebanx": {
"merchant_payment_code": "123-456-789-111",// mandatory
"merchant_enrollment_code": "123-456-789-aaa",
"subscription": {
"subscription_name": "Descriptor of the subscription.",// mandatory
"expiration_date": "2025-12-30",// optional
"frequency": "monthly",// mandatory
"retry": "allow_3R_7D",// mandatory
"fixed_amount": 1000, // mandatory field for fixed amount enrollment
"max_amount_floor": 1000, // mandatory field for variable amount enrollment
"start_date": "2025-10-02"// mandatory
},
"due_date": "02/10/2025"
}
},
"callback_url": "https://your-domain.com/callback"
}
}{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-10-15T10:56:59Z",
"updated_at": "2025-10-15T10:57:00Z",
"succeeded": false,
"state": "processing",
"token": "3xWJaV80XkWCDQvyQoeBiOzr1yK",
"transaction_type": "OffsitePurchase",
...
"gateway_specific_fields": {
"ebanx": {
"merchant_payment_code": "123-456-789-111",
"merchant_enrollment_code": "123-456-789-aaa",
"subscription": {
"subscription_name": "Descriptor of the subscription.",
"expiration_date": "2025-12-30",
"frequency": "monthly",
"retry": "allow_3R_7D",
"max_amount_floor": 10000,
"start_date": "2025-10-17"
},
"due_date": "17/10/2025"
}
},
"gateway_specific_response_fields": {
"ebanx": {
"amount_br": "1.04",
"amount_ext": "1.00",
"amount_iof": "0.04",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"enrollment_status": "pending",
"payment_status": "PE"
}
},
"gateway_transaction_id": "68ef7dfbafaea50911d22829ae2fe8935964006934a0ffa7",
...
"amount": 100,
"local_amount": null,
"currency_code": "BRL",
"reference": "68ef7dfbafaea50911d22829ae2fe8935964006934a0ffa7",
...
"retain_on_success": false,
"message_key": "messages.transaction_processing",
"message": "Processing",
"gateway_token": "4RCFFMFQAF9EZBKGPDX0T9PSC3",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Setup completed",
...
"status": null,
"checkout_url": "https://sandbox.ebanx.com/ws/simulator/confirm?hash=68ef7dfbafaea50911d22829ae2fe8935964006934a0ffa7"
},
"shipping_address": {
...
},
...
"setup_response": {
"success": true,
"message": "Setup completed",
...
"status": null,
"checkout_url": "https://sandbox.ebanx.com/ws/simulator/confirm?hash=68ef7dfbafaea50911d22829ae2fe8935964006934a0ffa7"
},
"callback_url": null,
"payment_method": {
...
}
}
}Void
In the case of Instant Payment + Enrollment, pass the gateway-specific field void_enrollment to void the enrollment.
If this field is not passed, the payment will be voided instead.
NuPay and NuPay Recurrent
NuPay
NuPay (One-off Payments)
NuPay is ideal for single transactions where customers pay once without setting up recurring payments.
One-off Payment Transaction Flow
- Create Payment Method: Customer details stored in Spreedly
- Initiate Purchase: Customer redirected to Nubank app
- Callback: Transaction status updated via webhook
- Completion: Customer redirected back to merchant
Creating a NuPay Payment Method
Required Fields:
- country
- full_name or first_name and last_name
- phone_number
- document_id
POST 'https://core.spreedly.com/v1/payment_methods.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG9' \
--body '{
"payment_method": {
"email": "[email protected]",
"payment_method_type": "nupay",
"full_name": "Ana Santos Araujo",
"document_id": "853.513.468-93",
"country": "BR",
"phone_number": "8522847035"
}
}'{
"transaction": {
"token": "3D3RK3K51G9BKB1BFP80W65TDX",
"created_at": "2025-12-22T14:40:43Z",
"updated_at": "2025-12-22T14:40:43Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KD382RQKNX4YP2M0P8Y6K9QK",
"created_at": "2025-12-22T14:40:43.251Z",
"updated_at": "2025-12-22T14:40:43.251Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "BR",
"phone_number": "8522847035",
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "nupay",
"errors": [],
"document_id": "8-93"
}
}
}Processing a NuPay Purchase
Create a request to the Purchase endpoint and redirect the user to the checkout_url. When the user has completed the interaction they will be returned to the url supplied as the redirect_url. Spreedly will send a callback with the result of the transaction.
POST 'https://core.spreedly.com/v1/gateways/{Gateway Token}/purchase.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeG' \
--body '{
"transaction": {
"payment_method_token": "{Payment Method Token}",
"amount": 100,
"currency_code": "BRL",
"callback_url": "{call back URL}",
"redirect_url": "{redirect URL}", // maps to redirect_url
"gateway_specific_fields": {
"ebanx": {}
}
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-12-22T14:41:15Z",
"updated_at": "2025-12-22T14:41:15Z",
"succeeded": false,
"state": "processing",
"token": "01KD383QZ7M0EPMEPTDVX18XCY",
"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": {
"ebanx": {}
},
"gateway_specific_response_fields": {
"ebanx": {
"amount_br": "1.04",
"amount_ext": "1.00",
"amount_iof": "0.04",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"payment_status": "PE",
"redirect_url": "https://sandbox.ebanx.com/ws/redirect?hash=6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68"
}
},
"gateway_transaction_id": "6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68",
"sub_merchant_key": null,
"gateway_latency_ms": 625,
"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": "BRL",
"reference": "6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68",
"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_processing",
"message": "Processing",
"gateway_token": "7DPQMT82S88DRVEW0ZCGTZYMVH",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Setup completed",
"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-22T14:41:15Z",
"updated_at": "2025-12-22T14:41:15Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/ws/redirect?hash=6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68" //send the user here
},
"shipping_address": {
"name": "Ana Santos Araujo",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml"
]
}
],
"redirect_url": "https://spreedly.com",
"callback_url": "https://webgrab.requestcatcher.com/",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"setup_response": {
"success": true,
"message": "Setup completed",
"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-22T14:41:15Z",
"updated_at": "2025-12-22T14:41:15Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/ws/redirect?hash=6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68"
},
"payment_method": {
"token": "01KD382RQKNX4YP2M0P8Y6K9QK",
"created_at": "2025-12-22T14:40:43.251Z",
"updated_at": "2025-12-22T14:40:43.251Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "nupay",
"errors": []
}
}
}POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Content-Length: 6363
Content-Type: application/xml
Traceparent: 00-69495af1000000001e5b9023a458b9f0-09f373022738e3bd-01
Tracestate: dd=p:09f373022738e3bd;s:1;t.dm:-1
User-Agent: Ruby
X-Datadog-Parent-Id: 717043218767209405
X-Datadog-Sampling-Priority: 1
X-Datadog-Tags: _dd.p.dm=-1,_dd.p.tid=69495af100000000
X-Datadog-Trace-Id: 2187500526774041072
<transactions>
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2025-12-22T14:41:15Z</created_at>
<updated_at type="dateTime">2025-12-22T14:51:29Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>01KD383QZ7M0EPMEPTDVX18XCY</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>
<ebanx>
</ebanx>
</gateway_specific_fields>
<gateway_specific_response_fields>
<ebanx>
<amount_br>1.04</amount_br>
<amount_ext>1.00</amount_ext>
<amount_iof>0.04</amount_iof>
<currency_rate>1.0000</currency_rate>
<currency_ext>BRL</currency_ext>
<payment_status>PE</payment_status>
<payment_type_code>nupay</payment_type_code>
<transaction_status>
<acquirer>EBANX</acquirer>
<code>OK</code>
<description>Payment successfully paid</description>
<description_code>ACCEPTED</description_code>
</transaction_status>
</ebanx>
</gateway_specific_response_fields>
<gateway_transaction_id>6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68</gateway_transaction_id>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">415</gateway_latency_ms>
<warning nil="true"/>
<application_id nil="true"/>
<risk_data>
</risk_data>
<merchant_metadata>
</merchant_metadata>
<customer_data>
</customer_data>
<order_data>
</order_data>
<workflow_key nil="true"/>
<protection_parameters>
</protection_parameters>
<amount type="integer">100</amount>
<local_amount nil="true"/>
<currency_code>BRL</currency_code>
<reference>6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68</reference>
<setup_verification nil="true"/>
<expiration_date nil="true"/>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<stored_credential_final_payment type="boolean">false</stored_credential_final_payment>
<retain_on_success type="boolean">false</retain_on_success>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>7DPQMT82S88DRVEW0ZCGTZYMVH</gateway_token>
<gateway_type>ebanx</gateway_type>
<shipping_address>
<name>Ana Santos Araujo</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>The payment was successfully completed.</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>OK</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2025-12-22T14:51:28Z</created_at>
<updated_at type="dateTime">2025-12-22T14:51:28Z</updated_at>
<status nil="true"/>
</response>
<api_urls>
<callback_conversations>https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml</callback_conversations>
</api_urls>
<signed>
<signature>bfcf35f1773571b682463fcf6e21e6183814c91b</signature>
<fields>amount created_at currency_code ip local_amount on_test_gateway order_id state succeeded token transaction_type updated_at</fields>
<algorithm>sha1</algorithm>
</signed>
<payment_method>
<token>01KD382RQKNX4YP2M0P8Y6K9QK</token>
<created_at>2025-12-22T14:40:43.251Z</created_at>
<updated_at>2025-12-22T14:40:43.251Z</updated_at>
<email>[email protected]</email>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">false</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<full_name>Ana Santos Araujo</full_name>
<first_name>Ana Santos</first_name>
<last_name>Araujo</last_name>
<bic nil="true"/>
<payment_method_type>nupay</payment_method_type>
<errors>
</errors>
</payment_method>
<callback_url>https://webgrab.requestcatcher.com/</callback_url>
<redirect_url>https://spreedly.com</redirect_url>
<checkout_url nil="true"/>
<callback_url>https://webgrab.requestcatcher.com/</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>Setup completed</message>
<error_code nil="true"/>
<checkout_url>https://sandbox.ebanx.com/ws/redirect?hash=6949588b3f6976f40d88a72ec3e57ff60131f0ccb2f40e68</checkout_url>
<created_at type="dateTime">2025-12-22T14:41:15Z</created_at>
<updated_at type="dateTime">2025-12-22T14:41:15Z</updated_at>
</setup_response>
<redirect_response>
<success type="boolean">true</success>
<message>The payment was successfully completed.</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>OK</error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2025-12-22T14:51:28Z</created_at>
<updated_at type="dateTime">2025-12-22T14:51:28Z</updated_at>
<status nil="true"/>
</redirect_response>
</transaction>
</transactions>NuPay Recurrent (Subscription Payments)
NuPay Recurrent enables merchants to process recurring payments after a one-time customer enrollment. Unlike Pix Automatico, there is no option to create an enrollment and accept the first payment in the same step.
Recurrent Payment Transaction Flow
- Create Payment Method: Customer details stored in Spreedly
- Enroll Payment Method: Enroll the NuPay Recurrent payment method in a subscription
- Initiate Purchase: Customer redirected to Nubank app
- Callback: Transaction status updated via webhook
- Completion: Customer redirected back to merchant
- Void: Void a NuPay Recurrent enrollment
NuPay Recurrent Flow Types
App-to-App Flow
- Use Case: Mobile app to mobile app
- Required:
redirect_urlfor success/failure callbacks - Experience: Direct redirect between apps
- Trigger: Omit the
document_idand provide thecallback_urlto Spreedly in thepurchase
Web-to-App Flow
- Use Case: Website to mobile app
- Required:
document_id(CPF) for customer verification - Experience: Push notification to customer's phone
- Trigger: Provide the
document_idon the payment method to trigger this flow
Our implementation supports both flows automatically based on the provided fields.
Step 1: Creating a NuPay Recurrent Payment Method
Required Fields:
- country
- full_name or first_name and last_name
- phone_number
POST 'https://core.spreedly.com/v1/payment_methods.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlN' \
--body '{
"payment_method": {
"email": "[email protected]",
"payment_method_type": "nupay_recurrent",
"full_name": "Ana Santos Araujo",
"document_id": "853.513.468-93", //invokes the web-to-app flow when included
"country": "BR",
"phone_number": "8522847035"
}
}'{
"transaction": {
"token": "3P42CB2CWS9699XNECVHJXX27M",
"created_at": "2025-12-22T14:57:50Z",
"updated_at": "2025-12-22T14:57:50Z",
"succeeded": true,
"transaction_type": "AddPaymentMethod",
"retained": false,
"state": "succeeded",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"payment_method": {
"token": "01KD3923V965AMPYB8FAV73FH3",
"created_at": "2025-12-22T14:57:50.441Z",
"updated_at": "2025-12-22T14:57:50.441Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": "BR",
"phone_number": "8522847035",
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "nupay_recurrent",
"errors": [],
"document_id": "8-93"
}
}
}Step 2: Customer Enrollment
Before processing recurring payments, customers must complete an enrollment process. Create a 'verification' request using the payment method. Redirect the user to the checkout_url. Spreedly will send a callback with the status of the enrollment, or you can check the status using Sync as described below.
POST 'https://core.spreedly.com/v1/gateways/{Gateway Token}/verify.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjdVQ=' \
--body '{
"transaction": {
"payment_method_token": "{Payment Method Token}",
"callback_url": "{callback URL}",
"redirect_url": "{redirect URL}",
"gateway_specific_fields": {
"ebanx": {
"merchant_enrollment_code": "4bdcd91a-deb6-4285-8110-4ae7a23f3c6c" //unique enrollment code generated for this request and used in all purchases related to this enrollment
}
}
,
"retain_on_success": true // to use this payment method more than once, it will need to be retained at spreedly
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-12-22T15:01:45Z",
"updated_at": "2025-12-22T15:01:46Z",
"succeeded": false,
"state": "processing",
"token": "01KD3999W9SFYDHK3QZK61XPK2",
"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": {
"ebanx": {
"merchant_enrollment_code": "4bdcd91a-deb6-4285-8110-4ae7a23f3c6c"
}
},
"gateway_specific_response_fields": {
"ebanx": {
"redirect_url": "https://sandbox.ebanx.com/ewallet/recurrency-agreement?return_url=https%3A%2F%2Fsandbox.ebanx.com%2Fws%2Fcustomerenrollment-finish%2Ffake%3Fenrollment%3DODM5MDY6NGJkY2Q5MWEtZGViNi00Mjg1LTgxMTAtNGFlN2EyM2YzYzZj&enrollment_uuid=FKRsjrK1GdvUGyEQAoW2w5"
}
},
"gateway_transaction_id": null,
"sub_merchant_key": null,
"gateway_latency_ms": 355,
"warning": null,
"application_id": null,
"risk_data": {},
"merchant_metadata": {},
"customer_data": {},
"order_data": {},
"workflow_key": null,
"protection_parameters": {},
"currency_code": null,
"payment_method_added": false,
"retain_on_success": true,
"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": "7DPQMT82S88DRVEW0ZCGTZYMVH",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Finish enrolling by responding to the enrollment agreement.",
"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-22T15:01:46Z",
"updated_at": "2025-12-22T15:01:46Z",
"status": null,
"checkout_url": "https://sandbox.ebanx.com/ewallet/recurrency-agreement?return_url=https%3A%2F%2Fsandbox.ebanx.com%2Fws%2Fcustomerenrollment-finish%2Ffake%3Fenrollment%3DODM5MDY6NGJkY2Q5MWEtZGViNi00Mjg1LTgxMTAtNGFlN2EyM2YzYzZj&enrollment_uuid=FKRsjrK1GdvUGyEQAoW2w5" //send the user here
},
"shipping_address": {
"name": "Ana Santos Araujo",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml"
]
}
],
"redirect_url": "https://spreedly.com",
"callback_url": "https://webgrab.requestcatcher.com/",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"payment_method": {
"token": "01KD3923V965AMPYB8FAV73FH3",
"created_at": "2025-12-22T14:57:50.441Z",
"updated_at": "2025-12-22T14:57:50.441Z",
"email": "[email protected]",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "nupay_recurrent",
"errors": []
}
}
}POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Content-Length: 5270
Content-Type: application/xml
Traceparent: 00-69495e2b000000003ddb479ebb52e34b-310ec72a264d0eb8-01
Tracestate: dd=p:310ec72a264d0eb8;s:1;t.dm:-1
User-Agent: Ruby
X-Datadog-Parent-Id: 3534981741377556152
X-Datadog-Sampling-Priority: 1
X-Datadog-Tags: _dd.p.dm=-1,_dd.p.tid=69495e2b00000000
X-Datadog-Trace-Id: 4457235003286414155
<transactions>
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2025-12-22T15:01:45Z</created_at>
<updated_at type="dateTime">2025-12-22T15:05:15Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>01KD3999W9SFYDHK3QZK61XPK2</token>
<transaction_type>Verification</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>
<ebanx>
<merchant_enrollment_code>4bdcd91a-deb6-4285-8110-4ae7a23f3c6c</merchant_enrollment_code>
</ebanx>
</gateway_specific_fields>
<gateway_specific_response_fields>
<ebanx>
<enrollment_status>accepted</enrollment_status>
</ebanx>
</gateway_specific_response_fields>
<gateway_transaction_id nil="true"/>
<sub_merchant_key nil="true"/>
<gateway_latency_ms type="integer">159</gateway_latency_ms>
<warning nil="true"/>
<application_id nil="true"/>
<risk_data>
</risk_data>
<merchant_metadata>
</merchant_metadata>
<customer_data>
</customer_data>
<order_data>
</order_data>
<workflow_key nil="true"/>
<protection_parameters>
</protection_parameters>
<currency_code nil="true"/>
<payment_method_added type="boolean">false</payment_method_added>
<retain_on_success type="boolean">true</retain_on_success>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<stored_credential_alternate_gateway nil="true"/>
<stored_credential_final_payment type="boolean">false</stored_credential_final_payment>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>7DPQMT82S88DRVEW0ZCGTZYMVH</gateway_token>
<gateway_type>ebanx</gateway_type>
<shipping_address>
<name>Ana Santos Araujo</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>accepted</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">2025-12-22T15:05:15Z</created_at>
<updated_at type="dateTime">2025-12-22T15:05:15Z</updated_at>
<status nil="true"/>
</response>
<api_urls>
<callback_conversations>https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml</callback_conversations>
</api_urls>
<signed>
<signature>641d695eb7324a250e3dfb76ea5e9de737ddfdc9</signature>
<fields>amount created_at currency_code ip local_amount on_test_gateway order_id state succeeded token transaction_type updated_at</fields>
<algorithm>sha1</algorithm>
</signed>
<payment_method>
<token>01KD3923V965AMPYB8FAV73FH3</token>
<created_at>2025-12-22T14:57:50.441Z</created_at>
<updated_at>2025-12-22T14:57:50.441Z</updated_at>
<email>[email protected]</email>
<data nil="true"/>
<storage_state>cached</storage_state>
<test type="boolean">false</test>
<metadata nil="true"/>
<callback_url nil="true"/>
<full_name>Ana Santos Araujo</full_name>
<first_name>Ana Santos</first_name>
<last_name>Araujo</last_name>
<bic nil="true"/>
<payment_method_type>nupay_recurrent</payment_method_type>
<errors>
</errors>
</payment_method>
<callback_url>https://webgrab.requestcatcher.com/</callback_url>
<callback_response>
<success type="boolean">true</success>
<message>accepted</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">2025-12-22T15:05:15Z</created_at>
<updated_at type="dateTime">2025-12-22T15:05:15Z</updated_at>
<status nil="true"/>
</callback_response>
<redirect_url>https://spreedly.com</redirect_url>
<checkout_url nil="true"/>
<callback_url>callback.com/</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"/>
</transaction>
</transactions>Step 3: Check Enrollment Status (Optional)
If you did not provide a callback_url, in order for the verification transaction at Spreedly to be updated, the merchant would need to perform a transaction sync operation to get the most recent status of the enrollment.
curl -X PATCH https://core.spreedly.com/v1/transactions/TRANSACTION_TOKEN.json \
-H "Content-Type: application/json" \
-u "ENVIRONMENT_KEY:ACCESS_SECRET"Step 4: Process Recurring Payment
After successful enrollment utilize the Purchase endpoint and the merchant enrollment identifier. Please note that if doing installments with Nupay Recurrant, the location and spelling of 'installments' differs from when working with credit cards per the instructions from Ebanx in step 6. You must also supply the funding source in the metadata Gateway Specific Field. There is no redirection for this payment.
POST 'https://core.spreedly.com/v1/gateways/{Gateway Token}/purchase.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VlNjeGQ=' \
--body '{
"transaction": {
"payment_method_token": "{Payment Method Token}",
"amount": 100,
"currency_code": "BRL",
"gateway_specific_fields": {
"ebanx": {
"merchant_enrollment_code": "4bdcd91a-deb6-4285-8110-4ae7a23f3c6c", //must provide the ID of the enrollment
"metadata": {
"funding_source": "credit", //The source of funds for the payment. Can be debit or credit.
"installments": "1" //note this location and spelling. Only applicable when funding_source is credit.
}
}
}
}
}'{
"transaction": {
"on_test_gateway": true,
"created_at": "2025-12-22T15:10:55Z",
"updated_at": "2025-12-22T15:10:57Z",
"succeeded": true,
"state": "succeeded",
"token": "01KD39T2G3YNF7SJ6D60A9DATS",
"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": {
"ebanx": {
"merchant_enrollment_code": "4bdcd91a-deb6-4285-8110-4ae7a23f3c6c"
}
},
"gateway_specific_response_fields": {
"ebanx": {
"payment_type_code": "nupay-recurrent",
"transaction_status": {
"acquirer": "EBANX",
"code": "OK",
"description": "Payment successfully paid",
"description_code": "ACCEPTED"
},
"amount_br": "1.04",
"amount_ext": "1.00",
"amount_iof": "0.04",
"currency_rate": "1.0000",
"currency_ext": "BRL",
"payment_status": "CO"
}
},
"gateway_transaction_id": "69495f7f82cc140b6ac32dee426aa799572c63939846820b",
"sub_merchant_key": null,
"gateway_latency_ms": 1069,
"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": "BRL",
"reference": "69495f7f82cc140b6ac32dee426aa799572c63939846820b",
"setup_verification": null,
"expiration_date": null,
"stored_credential_initiator": null,
"stored_credential_reason_type": null,
"stored_credential_alternate_gateway": null,
"stored_credential_final_payment": false,
"retain_on_success": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "7DPQMT82S88DRVEW0ZCGTZYMVH",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Payment successfully paid",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "OK",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2025-12-22T15:10:56Z",
"updated_at": "2025-12-22T15:10:56Z",
"status": null
},
"shipping_address": {
"name": "Ana Santos Araujo",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"callback_conversations": [
"https://core.spreedly.com/v1/callbacks/34JBPMSBSG87YADPSE4D2Q6XDJ/conversations.xml"
]
}
],
"callback_url": "callback url",
"attempt_3dsecure": false,
"challenge_url": null,
"required_action": "none",
"three_ds_context": null,
"payment_method": {
"token": "01KD3923V965AMPYB8FAV73FH3",
"created_at": "2025-12-22T14:57:50.441Z",
"updated_at": "2025-12-22T15:05:15.452Z",
"email": "[email protected]",
"data": null,
"storage_state": "retained",
"test": false,
"metadata": null,
"callback_url": null,
"full_name": "Ana Santos Araujo",
"first_name": "Ana Santos",
"last_name": "Araujo",
"bic": null,
"payment_method_type": "nupay_recurrent",
"errors": []
}
}
}Step 5: Void an Enrollment (Optional)
To cancel an enrollment:
curl -X POST https://core.spreedly.com/v1/transactions/VERIFY_TOKEN/void.json \
-H "Content-Type: application/json" \
-u "ENVIRONMENT_KEY:ACCESS_SECRET" \
-d '{
"transaction": {
"gateway_specific_fields": {
"ebanx": {
"void_enrollment": true
}
}
}
}Technical Notes
Testing
Please see Ebanx section on Mock Customer Data for testing values and refer to the API Error Codes for explanations on specific error messages.
Redirect and Callback URL's
Spreedly's redirect_url and callback_url are used in the Enrollment of LPM's and also are used in the one-off purchase for each.
For Pix Automatico and NuPay Recurrent enrollments, Spreedy's callback_url and redirect_url are mapped to Ebanx enrollment.notification_url and enrollment.redirect_url, respectively.
For NuPay Recurrent "app-to-app" transaction flow, the Spreedly callback_url and redirect_url are mapped to the back_url's for success and failure, respectively.
Enrollment and Verify
Recurring use cases of Mercado Pago, NuPay, and Pix (Automatico) require that the merchant perform an enrollment step through the gateway before being able to process transactions with the given payment method. Spreedly does not have a distinct enrollment endpoint to support this operation, but the method signature and transaction behavior works much like a verify call would for a traditional credit card payment method. Merchants can use verify as it is described in the examples above, to perform this enrollment step.
Updated 12 days ago