Skip to main content
Spreedly

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

Spreedly 1

  1. 1Add EBANX as a payment gateway within your Speedly account.
  2. 2Create a tokenized payment method on Spreedly.
  3. 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.

  1. Add EBANX as a payment gateway

    To add EBANX as a payment gateway within Spreedly, use the following endpoint to obtain a gateway token.

  2. Sample request

    Gather required parameters for your request.

    ParameterDescription
    environment_keyObtain from your Speedly account.
    access_secret_keyObtain from your Speedly account.
    gateway_typeThis should be set to ebanx .
    integration_keyYour 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"
    }
    }'
  3. 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

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


    Parameters:

    ParameterDescription
    payment_method.credit_card.first_nameCustomer first name
    payment_method.credit_card.last_nameCustomer 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.phone_numberCustomer phone number
    payment_method.credit_card.emailCustomer email address
    payment_method.credit_card.address1Customer address
    Street number, then street name.
    payment_method.credit_card.address2Additional address info.
    (e.g. Apartment 302)
    Optional
    payment_method.credit_card.cityCustomer city
    payment_method.credit_card.stateCustomer state.
    For Brazil, it must be the 2-letter code.
    payment_method.credit_card.zipCustomer zip code
    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_successFlag to retain payment method.
    Boolean
    payment_method.emailCustomer email.
    payment_method.metadataMetadata
    Optional
  2. Sample 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
    }
    }'
  3. 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.

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

  1. Charging a customer

    To charge the customer’s credit card, follow the steps below.

    Create a request.


    Basic parameters:

    ParameterDescription
    transaction.payment_method_tokenSpreedly payment_method_token
    (from previous step)
    transaction.amountAmount to be charged. No decimals.
    i.e. to charge 0.5, send the amount as 50
    transaction.currency_code3 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 Dollars
    transaction.retain_on_successStore a payment method for future charges.
    Boolean
    EBANX
    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 = 1

    Aditional parameters (by country).

    CountryName*Email*Document**Address*Country*Amt***Currency***
    Argentinacheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outline
    Brazilcheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outline
    Chilecheck_circle_outlinecheck_circle_outlinehighlight_offcheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outline
    Colombiacheck_circle_outlinecheck_circle_outlinehighlight_offcheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outline
    Mexicocheck_circle_outlinecheck_circle_outlinehighlight_offcheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outline
    Perucheck_circle_outlinecheck_circle_outlinehighlight_offcheck_circle_outlinecheck_circle_outlinecheck_circle_outlinecheck_circle_outline
    *** Sent inside the transaction node.
    ** 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


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

  1. Pre-authorize a payment

    Pre-authorization uses a different endpoint.


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

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


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

    Use the transaction token to call the API endpoint for voiding.


    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"
    }
    }
  5. Congratulations!

    You have captured or voided a payment.


Refunds

  1. Refunding a payment

    Use the transaction_token to call the API endpoint for refunds.


    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"
    }
    }
  2. Congratulations!

    You have refunded a payment.


Resources

Use the following resources when testing in your sandbox environment.


Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: