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

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

    Basic parameters:

    ParameterDescription
    gateway_typeThis should be set as ebanx.
    integration_keyYour 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
    }
    }
  2. 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.

    This endpoint accepts the following parameters:

    Basic parameters:

    ParameterDescription
    payment_method.credit_card.first_nameCustomer’s First Name
    payment_method.credit_card.last_nameCustomer’s Last Name
    payment_method.credit_card.numberCredit Card number
    payment_method.credit_card.verification_valueCredit Card security code (CVV)
    payment_method.credit_card.monthCredit Card expiration month
    payment_method.credit_card.yearCredit Card expiration year
    payment_method.credit_card.address1Customer address, first the street number and then street name. e.g.: 2323 Rua E
    payment_method.credit_card.address2Address complement, e.g. Apartment 302
    payment_method.credit_card.cityCustomer City
    payment_method.credit_card.stateCustomer State. For Brazil it must be the 2-letter code of the corresponding state
    payment_method.credit_card.zipCustomer Zipcode
    payment_method.credit_card.country2 letter country code. Accepted values are: br: Brazil , mx: Mexico ,pe: Peru , co: Colombia ,cl: Chile ,ar: Argentina
    payment_method.credit_card.retain_on_successBoolean - Flag if the payment method must be retained.
    payment_method.emailCustomer email.
    payment_method.metadataOptional 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.

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

    This endpoint accepts the following parameters:

    Basic parameters:

    ParameterDescription
    transaction.payment_method_tokenSpreedly payment method token
    transaction.amountAmount to be charged. No decimals utilized, i.e. to charge 0.5 send the amount as 50
    transaction.currency_code3 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_successFlag if the payment method must be retained.
    transaction.gateway_specific_fields.ebanx.documentCustomer document, required in Argentina, Brazil, Colombia and Chile
    transaction.gateway_specific_fields.ebanx.instalmentsNumber 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"
    }
    }
    }
  2. 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:

    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:

    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"
    }
    }
  3. 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:

    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"
    }
    }
  4. 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

    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 ou this form and our comercial 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.
Last updated on by Fernando Pankiewicz Gomes