This guide will walk you through the steps to integrate EBANX with Spreedly, enabling you to leverage Spreedly’s payment orchestration platform to manage and route payments through the EBANX API. You’ll learn how to securely tokenize customer payment information, handle payments, manage installment options, and issue refunds.
Features:
- Multiple payment gateways - Expand your payment processing options by integrating with Spreedly.
- Payment tokenization - Securely store and reuse customer payment methods via Spreedly.
- Installments and refunds - Easily manage installment payments and refunds through the EBANX API.
How it works
- 1Add EBANX as a payment gateway within your Speedly account.
- 2Create a tokenized payment method on Spreedly.
- 3Use the gateway token and payment method to operate EBANX API via Spreedly.
Requirements
Before starting the integration, ensure you have the following:
- Spreedly API Credentials - Ensure you have your Spreedly API key. If not, signup at Spreedly.
- EBANX API Credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Instructions
Follow the steps below.
Add EBANX as a payment gateway
To add EBANX as a payment gateway within Spreedly, use the following endpoint to obtain a gateway token.
- Endpoint - https://core.spreedly.com/v1/gateways.json
- Authorization - Basic
environment_key
:access_secret_key
- Header - Content-Type: application/json
- Method - POST
Sample request
Gather required parameters for your request.
Parameter Description environment_key
Obtain from your Speedly account. access_secret_key
Obtain from your Speedly account. gateway_type
This should be set to ebanx . integration_key
Your EBANX integration key. Use the following as an example.
curl -X POST \
--location 'https://core.spreedly.com/v1/gateways.json' \
--header 'Authorization: Basic {{environment_key}} : {{access_secret_key}} ' \
--header 'Content-Type: application/json' \
--data '{
"gateway": {
"gateway_type": "ebanx",
"integration_key": "your_ebanx_integration_key"
}
}'Sample response
On success, Spreedly returns a gateway_token, which you will use to interact with EBANX.
{
"gateway": {
"token": "52THAMCzd27iwRl9N1Onlp7xkYk", // Spreedly gateway token.
"gateway_type": "test",
"description": null,
"payment_methods": [
"android_pay",
"apple_pay",
"bank_account",
"boleto_bancario",
"credit_card",
"google_pay",
"mercado_pago",
"oxxo,"
"pix"
"sepa_direct_debit"
"sprel",
"third_party_token",
],
"state": "retained",
"created_at": "2019-12-23T19:49:47Z",
"updated_at": "2019-12-23T19:49:47Z",
"name": "EBANX",
"characteristics": [
"purchase",
"authorize",
"capture",
"credit",
"general_credit",
"void",
"adjust",
"verify",
"reference_purchase",
"purchase_via_preauthorization",
"offsite_purchase",
"offsite_authorize",
"3dsecure_purchase",
"3dsecure_authorize",
"store",
"remove",
"reference_authorization",
"3dsecure_2_purchase",
"3dsecure_2_authorize"
],
"credentials": [],
"gateway_settings": {},
"gateway_specific_fields": [],
"redacted": false
}
}
Tokenized Payment Methods
Create a payment method
After adding the EBANX gateway, the next step is to tokenize customer payment information, which allows secure transactions without storing sensitive card details.
Create a request.
- Endpoint: https://core.spreedly.com/v1/payment_methods.json
- Authorization: Basic
environment_key
:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Parameters:
Parameter Description payment_method.credit_card.first_name
Customer first name payment_method.credit_card.last_name
Customer last Name payment_method.credit_card.number
Credit card number payment_method.credit_card.verification_value
Credit card security code (CVV) payment_method.credit_card.month
Credit card expiration month payment_method.credit_card.year
Credit card expiration year payment_method.credit_card.phone_number
Customer phone number payment_method.credit_card.email
Customer email address payment_method.credit_card.address1
Customer address
Street number, then street name.payment_method.credit_card.address2
Additional address info.
(e.g. Apartment 302)
Optionalpayment_method.credit_card.city
Customer city payment_method.credit_card.state
Customer state.
For Brazil, it must be the 2-letter code.payment_method.credit_card.zip
Customer zip code payment_method.credit_card.country
2 letter country code. Accepted values are:
br
Brazil,
mx
Mexico,
pe
Peru,
co
Colombia,
cl
Chile,
ar
Argentinapayment_method.credit_card.retain_on_success
Flag to retain payment method.
Booleanpayment_method.email
Customer email. payment_method.metadata
Metadata
OptionalSample request
Use the following as an example.
curl -X POST \
--location 'https://core.spreedly.com/v1/payment_methods.json' \
--header 'Authorization: Basic {{base64_encoded_environment_key}} : {{access_secret_key}}' \
--header 'Content-Type: application/json' \
--data '{
"payment_method": {
"credit_card": {
"first_name": "John",
"last_name": "Doe",
"number": "4111111111111111",
"verification_value": "123",
"month": 12,
"year": 2024,
"phone_number": "5551999887766"
"email": "john.doe@example.com",
"address1": "123 Main St",
"city": "Curitiba",
"state": "PR",
"zip": "12345",
"country": "BR",
},
"retained": true
}
}'Response
Upon success, Spreedly generates a payment_method_token.
{
"payment_method_token": "FqqnAg5zkZ28L16Ip5hgW0UPMvL" // Example
}This token can be used for charging the customer in future transactions.
Congratulations!
You've created your first tokenized payment method with Spreedly.
Continue to the next section to use your tokenized payment-method to create a charge.
Using tokenized payment methods
With the newly-created tokenized payment-method, you can charge the customer’s credit card.
Charging a customer
To charge the customer’s credit card, follow the steps below.
Create a request.
- Endpoint: https://core.spreedly.com/v1/gateways/{{gateway_token}}/purchase.json
- Authorization: Basic
environment_key
:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Basic parameters:
Parameter Description transaction.payment_method_token
Spreedly payment_method_token
(from previous step)transaction.amount
Amount to be charged. No decimals.
i.e. to charge 0.5, send the amount as 50transaction.currency_code
3 letter currency code.
Accepted values:
ARS
Argentinian Pesos
BRL
Brazilian Reais
CLP
Chilean Pesos
COP
Colombian Pesos
MXN
Mexican Pesos
PEN
Peruvian Soles
USD
US Dollarstransaction.retain_on_success
Store a payment method for future charges.
BooleanEBANX
transaction.gateway_specific_fields.ebanx.document
Customer document ID
(required in Argentina, Brazil)EBANX
transaction.gateway_specific_fields.ebanx.instalments
Number of installments.
Accepted values:
Argentina: 1,2,3,6,9,12
Brazil: 1 – 12
Chile: 1 – 48
Colombia: 1 – 36
Mexico: 1,3,6,9,12
Peru: 1 – 48
Default = 1Aditional parameters (by country).
*** Sent inside the transaction node.Country Name* Email* Document** Address* Country* Amt*** Currency*** Argentina check_circle_outline check_circle_outline check_circle_outline check_circle_outline check_circle_outline check_circle_outline check_circle_outline Brazil check_circle_outline check_circle_outline check_circle_outline check_circle_outline check_circle_outline check_circle_outline check_circle_outline Chile check_circle_outline check_circle_outline highlight_off check_circle_outline check_circle_outline check_circle_outline check_circle_outline Colombia check_circle_outline check_circle_outline highlight_off check_circle_outline check_circle_outline check_circle_outline check_circle_outline Mexico check_circle_outline check_circle_outline highlight_off check_circle_outline check_circle_outline check_circle_outline check_circle_outline Peru check_circle_outline check_circle_outline highlight_off check_circle_outline check_circle_outline check_circle_outline check_circle_outline
** Sent inside the transaction gateway_specific_fields.ebanx node.
* Stored when creating a payment method.- Address information is stored only when it is required.
- Example - when purchasing physical goods
- Address fields:
address1
address2
city
state
zip
- Other fields:
email
country_code
Sample request
- Replace gateway_token and payment_method_token with tokens you received in previous steps.
- Amount is in cents (i.e., 1000 represents 10 BRL).
curl -X POST \
--location 'https://core.spreedly.com/v1/gateways/{{gateway_token}}/purchase.json' \
--header 'Authorization: Basic {{environment_key}} : {{access_secret_key}}' \
--header 'Content-Type: application/json' \
--data '{
"transaction": {
"payment_method_token": "FqqnAg5zkZ28L16Ip5hgW0UPMvL",
"amount": 1000,
"currency_code": "BRL",
"retain_on_success": "true",
"gateway_specific_fields": {
"ebanx": {
"document": "05912050023",
"instalments": 6
}
}
}
}'Sample response
Each request returns a response similar to the example below.
{
"transaction": {
"on_test_gateway": false,
"created_at": "2019-12-26T13:33:23Z",
"updated_at": "2019-12-26T13:33:25Z",
"succeeded": true,
"state": "succeeded",
"token": "S4nGYs7R1Eg1ecXxsdasd2231vSa54LS7QpnOv",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
"ebanx": {
"document": "05912050023",
"instalments": 6 }
},
"gateway_specific_response_fields": {},
"gateway_transaction_id": "5e04b6a4f58cbf41221e718fbe34edf01011c12d5c666b8bf1e131",
"gateway_latency_ms": 2045,
"warning": null,
"amount": 1000,
"currency_code": "BRL",
"retain_on_success": false,
"payment_method_added": false,
"dynamically_routed": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6UBEDxgdqxj2oi5rMN6ojUvOGYhmV5pL",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Accepted",
"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": "2019-12-26T13:33:25Z",
"updated_at": "2019-12-26T13:33:25Z"
},
"shipping_address": {
"name": "Andre Peixoto",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": []
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "FqqnAg5zkZ28L16Ip5hgW0UPMvL",
"created_at": "2019-12-26T13:33:07Z",
"updated_at": "2019-12-26T13:33:07Z",
"email": "username@domain.com",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": {
"key": "H2jhkn328903n",
"another_key": 123,
"final_key": true
},
"callback_url": null,
"last_four_digits": "6571",
"first_six_digits": "523284",
"card_type": "master",
"first_name": "firstName",
"last_name": "lastName",
"month": 3,
"year": 2026,
"address1": "2323 Rua E",
"address2": "ap 508",
"city": "Curitiba",
"state": "PR",
"zip": "82590100",
"country": "br",
"phone_number": null,
"company": null,
"full_name": "firstName lastName",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [],
"fingerprint": "32f7843658f578df1f702c14d524def4f594",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}Congratulations!
You have charged your first customer using a tokenized payment-method with Spreedly.
Two-step payments
A two-step payment is a process where a payment is first pre-authorized to confirm the availability of funds, and then later captured to finalize the charge and transfer the funds.
Pre-authorize a payment
Pre-authorization uses a different endpoint.
- Endpoint: https://core.spreedly.com/v1/gateways/{{gateway_token}}/authorize.json
- Authorization: Basic
environment_key
:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Sample request
curl -X POST \
--location 'https://core.spreedly.com/v1/gateways/{{gateway_token}}/authorize.json' \
--header 'Authorization: Basic {{environment_key}} : {{access_secret_key}}' \
--header 'Content-Type: application/json' \
--data '{
"transaction": {
"payment_method_token": "KvDbD9YT6KadLFXroDTKCz7PNuL",
"amount": 200,
"currency_code": "BRL",
"retain_on_success": "true",
"gateway_specific_fields": {
"ebanx": {
"document": "05912050023",
"instalments": 6
}
}
}
}'Sample response
{
"transaction": {
"on_test_gateway": false,
"created_at": "2019-12-23T17:57:55Z",
"updated_at": "2019-12-23T17:57:57Z",
"succeeded": true,
"state": "succeeded",
"token": "JK7QJjyAOITvjHnhwAg9at5JD28",
"transaction_type": "Authorization",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
"ebanx": {
"document": "05912058905",
"instalments": 1
}
},
"gateway_specific_response_fields": {},
"gateway_transaction_id": "5e0100243571c1ad2a80862c809c6008b1abc2d01fa5e129",
"gateway_latency_ms": 2072,
"warning": null,
"amount": 200,
"currency_code": "BRL",
"retain_on_success": false,
"payment_method_added": false,
"dynamically_routed": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6UBEDxgdq5rMN41f6ojUvOGYhmV5pL",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Accepted",
"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": "2019-12-23T17:57:57Z",
"updated_at": "2019-12-23T17:57:57Z"
},
"shipping_address": {
"name": "firstName lastName",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": []
}
],
"attempt_3dsecure": false,
"payment_method": {
"token": "KvDbD9YT6KadLFXroDTKCz7PNuL",
"created_at": "2019-12-23T17:57:48Z",
"updated_at": "2019-12-23T17:57:48Z",
"email": "username@domain.com",
"data": null,
"storage_state": "cached",
"test": false,
"metadata": {
"key": "H2jhkn328903n",
"another_key": 123,
"final_key": true
},
"callback_url": null,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "firstName",
"last_name": "lastName",
"month": 3,
"year": 2026,
"address1": "2323 Rua E",
"address2": "2332",
"city": "Curitiba",
"state": "PR",
"zip": "82590100",
"country": "br",
"phone_number": null,
"company": null,
"full_name": "firstName lastName",
"eligible_for_card_updater": true,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [],
"fingerprint": "32f7843658f578df1f702c14d524def4f594",
"verification_value": "XXX",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}Capture or void
Once a payment is pre-authorized, you must take one of the following actions:
- Capture - The payment is processed.
- Void - The payment is cancelled.
Note: If neither action is taken, the pending authorization will automatically cancel after 4 days.
Capture a payment
When you pre-authorize a payment, Spreedly returns a transaction_token. This token uniquely identifies the pre-authorization and will be used to capture the funds.
Use the transaction token to call the API endpoint for capturing.
- Endpoint: https://core.spreedly.com/v1/transactions/{{transaction_token}}/capture.json
- Authorization: Basic
environment_key
:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Sample request
curl -X POST \
--location 'https://core.spreedly.com/v1/transactions/{{transaction_token}}/capture.json' \
--header 'Authorization: Basic {{environment_key}} : {{access_secret_key}}' \
--header 'Content-Type: application/json' \
--data '{
"transaction": {
"amount": 1000,
"currency_code": "BRL"
}
}'Sample response
{
"transaction": {
"on_test_gateway": false,
"created_at": "2019-12-23T17:58:07Z",
"updated_at": "2019-12-23T17:58:08Z",
"succeeded": true,
"state": "succeeded",
"token": "ZOCdZppB4KVomu1U2pohjqFXe2R", // transaction token
"transaction_type": "Capture",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": null,
"gateway_specific_response_fields": {},
"gateway_transaction_id": "5e0100243571c1ad2a80862c809c6008b1abc2d01fa5e129",
"gateway_latency_ms": 1019,
"warning": null,
"amount": 100,
"currency_code": "BRL",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6UBEDxgdq5rMN6ojUvOGYhmV5pL",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Accepted",
"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": "2019-12-23T17:58:08Z",
"updated_at": "2019-12-23T17:58:08Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": []
}
],
"reference_token": "JK7QJjyAOITvjHnhwAg9at5JD28"
}
}Void a payment
Use the transaction token to call the API endpoint for voiding.
- Endpoint: https://core.spreedly.com/v1/transactions/{{transaction_token}}/void.json
- Authorization: Basic
environment_key
:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Sample request
curl -X POST \
--location 'https://core.spreedly.com/v1/transactions/{{transaction_token}}/void.json' \
--header 'Authorization: Basic {{environment_key}} : {{access_secret_key}}' \
--header 'Content-Type: application/json' \
--data '{
"transaction": {
"amount": 1000,
"currency_code": "BRL"
}
}'Sample response
{
"transaction": {
"on_test_gateway": false,
"created_at": "2019-12-26T13:58:49Z",
"updated_at": "2019-12-26T13:58:50Z",
"succeeded": true,
"state": "succeeded",
"token": "YZwhbdMuXhm1fjHUmxYBIOhQz44",
"transaction_type": "Void",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {},
"gateway_specific_response_fields": {},
"gateway_transaction_id": "5e04bc5c222315003614d0562497fef31abaf95742eaeb60",
"gateway_latency_ms": 939,
"warning": null,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6UBEDxgdq5rMN6ojUvOGYhmV5pL",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Accepted",
"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": "2019-12-26T13:58:50Z",
"updated_at": "2019-12-26T13:58:50Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"reference_token": "4D3vekKe4rzPC7MFpDAayVRKMUn"
}
}Congratulations!
You have captured or voided a payment.
Refunds
Refunding a payment
Use the transaction_token to call the API endpoint for refunds.
- Endpoint: https://core.spreedly.com/v1/transactions/{{transaction_token}}/credit.json
- Authorization: Basic
environment_key
:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Sample request
curl -X POST \
--location 'https://core.spreedly.com/v1/transactions/{{transaction_token}}/credit.json' \
--header 'Authorization: Basic {{environment_key }} : {{access_secret_key}}' \
--header 'Content-Type: application/json' \
--data '{
"gateway_specific_fields": {
"ebanx": {
"description": "refund test",
"amount": 800 // If missing or null, a full refund is issued.
}
}
}'Sample response
{
"transaction": {
"on_test_gateway": false,
"created_at": "2019-12-26T13:35:04Z",
"updated_at": "2019-12-26T13:35:04Z",
"succeeded": true,
"state": "succeeded",
"token": "FlNg020qlFkVy6Ztj5q1YZwadEF",
"transaction_type": "Credit",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
"ebanx": {
"description": "refund test"
}
},
"gateway_specific_response_fields": {},
"gateway_transaction_id": "5e04b6a4f58cbf718fbe34edf01011c12d5c666b8bf1e131",
"gateway_latency_ms": 248,
"warning": null,
"amount": 50,
"currency_code": "BRL",
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "6UBEDxgdq5rMN6ojUvOGYhmV5pL",
"gateway_type": "ebanx",
"response": {
"success": true,
"message": "Accepted",
"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": "2019-12-26T13:35:04Z",
"updated_at": "2019-12-26T13:35:04Z"
},
"shipping_address": {
"name": null,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [],
"reference_token": "S4nGYs7R1Eg1ecvSa54LS7QpnOv"
}
}Congratulations!
You have refunded a payment.
Resources
Use the following resources when testing in your sandbox environment.
Sample Cards
Click here to view mock card data to validate your payment integration.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.