Version: current

Spreedly Integration

About this guide

This guide explains how you can use EBANX as a payment gateway of choice on Spreedly to process credit cards in Argentina, Brazil, Colombia, Chile, Mexico and Peru.

How it works

Spreedly 1

Setting up the integration

Add EBANX as a payment gateway
The first step is to call Spreedly’s gateway endpoint to create a token for the EBANX gateway to be called afterwards.
- Endpoint: https://core.spreedly.com/v1/gateways.json
- Authorization: Basic environment_key:access_secret_key
- Header: Content-Type: application/json
- Method: POST
Basic parameters:
Parameter Description
gateway_type This should be set as ebanx.
integration_key Your unique and secret integration key.
Examples of request and response:
{
"gateway": {
"gateway_type": "ebanx",
"integration_key": "your_ebanx_integration_key>"
}
}
{
"gateway": {
"token": "52THAMCzd27iwRl9N1Onlp7xkYk",
"gateway_type": "test",
"description": null,
"payment_methods": [
"credit_card",
"sprel",
"third_party_token",
"bank_account",
"apple_pay",
"android_pay",
"google_pay",
"sepa_direct_debit"
],
"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
}
}

Parameter	Description
`gateway_type`	This should be set as ebanx.
`integration_key`	Your unique and secret integration key.

Create a payment method

Next, collect the customer information and send it to Spreedly in order to create a payment method. This operation will generate a token that will be utilized in the future to charge the customer.

Endpoint: https://core.spreedly.com/v1/payment_methods.json
Authorization: Basic environment_key:access_secret_key
Header: Content-Type: application/json
Method: POST

This endpoint accepts the following parameters:

Basic parameters:

Parameter	Description
`payment_method.credit_card.first_name`	Customer’s First Name
`payment_method.credit_card.last_name`	Customer’s 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.address1`	Customer address, first the street number and then street name. e.g.: 2323 Rua E
`payment_method.credit_card.address2`	Address complement, e.g. Apartment 302
`payment_method.credit_card.city`	Customer City
`payment_method.credit_card.state`	Customer State. For Brazil it must be the 2-letter code of the corresponding state
`payment_method.credit_card.zip`	Customer Zipcode
`payment_method.credit_card.country`	2 letter country code. Accepted values are: br: Brazil , mx: Mexico ,pe: Peru , co: Colombia ,cl: Chile ,ar: Argentina
`payment_method.credit_card.retain_on_success`	Boolean - Flag if the payment method must be retained.
`payment_method.email`	Customer email.
`payment_method.metadata`	Optional metadata

Using the integration

Now that you have the payment method created and the token in hands, you are able to send calls to EBANX API via Spreedly to charge the customer’s credit card (with or without pre-authorization) or refund a previous charge.

Charging a payment

In order to charge a credit card, replace the gateway_token you generated on step 1 in the endpoint URL, and send the payment_method_token generated on step 2 inside the request token alongside the amount and currency_code.

info

If you plan to reutilize a payment method for future charges, always set the retain_on_success flag as true.

In order to charge installments, you need to send the parameter instalments inside the transaction.gateway_specific_fields.ebanx node. In case the parameter is not sent, EBANX API will default the value to 1.

On some countries you might need to send the parameter document inside the transaction.gateway_specific.fields.ebanx node. Refer to the table below for field requirements across EBANX supported countries:

Spreedly 2

EBANX Mandatory Fields

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

This endpoint accepts the following parameters:

Basic parameters:

Parameter	Description
`transaction.payment_method_token`	Spreedly payment method token
`transaction.amount`	Amount to be charged. No decimals utilized, i.e. to charge 0.5 send the amount as 50
`transaction.currency_code`	3 letter currency code. Accepted values are: USD: US Dollars, BRL: Brazilian Reais, MXN: Mexican Pesos, PEN: Peruvian Soles, COP: Colombian Pesos, CLP: Chilean Pesos, ARS: Argentinian Pesos
`transaction.retain_on_success`	Flag if the payment method must be retained.
`transaction.gateway_specific_fields.ebanx.document`	Customer document, required in Argentina, Brazil, Colombia and Chile
`transaction.gateway_specific_fields.ebanx.instalments`	Number of installments, accepted values are: Brazil: 1 – 12, Mexico: 1,3,6,9,12 ,Peru: 1 – 48, Colombia: 1 – 36, Chile: 1 – 48, Argentina: 1,2,3,6,9,12

Examples of request and response:

{
  "transaction": {
    "payment_method_token": "FqqnAg5zkZ28L16Ip5hgW0UPMvL",
    "amount": 50,
    "currency_code": "BRL",
    "retain_on_success": "true",
    "gateway_specific_fields": {
        "ebanx":{
            "document":"05912050023",
            "instalments": 6
        }
    }
}

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

Pre-authorizing a payment
The request structure is the same as if you were charging a payment token, however it is sent to a different endpoint. After pre-authorizing the payment you need to either capture or void the payment. If you don’t, the pending authorization will be automatically cancelled after 4 days. Find the details below:
- 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
info
Pre-authorization is not supported in Colombia.
Examples of request and response:
{
"transaction": {
"payment_method_token": "KvDbD9YT6KadLFXroDTKCz7PNuL",
"amount": 200,
"currency_code": "BRL",
"retain_on_success": "true",
"gateway_specific_fields": {
"ebanx":{
"document":"05912050023",
"instalments": 6
}
}
}
}
{
"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"
}
}
}
i) Capture a pre-authorized payment To capture a payment that has been previously pre-authorized, send the transaction_token from the payment on the endpoint URL below:
- 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
Example of 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_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"
}
}
Cancel a pre-authorized payment
To cancel a payment that has been previously pre-authorized, send the transaction_token from the payment on the endpoint URL below:
- 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
Example of 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"
}
}
Refunding a payment
In order to refund a previous charge, send the transaction_token on the URL below and the description inside the node gateway_specific_fields.ebanx
- 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
info
You can do partial refunds by sending the amount parameter. If you don't send it, a full refund will be issued.
{
"gateway_specific_fields": {
"ebanx": {
"description": "refund test"
}
}
}
{
"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"
}
}

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
In case you’re already our partner please get in touch with our support team at integration@ebanx.com.

Spreedly Integration#

About this guide#

How it works#

Setting up the integration#

Add EBANX as a payment gateway

Basic parameters:#

Create a payment method

Basic parameters:#

Using the integration#

Charging a payment

info

Basic parameters:#

Pre-authorizing a payment

info

Cancel a pre-authorized payment

Refunding a payment

info

Getting help#

Spreedly Integration

About this guide

How it works

Setting up the integration

Basic parameters:

Basic parameters:

Using the integration

Basic parameters:

Getting help