Version: current

EBANX Billing

About this guide

This page explains how to integrate to our recurring payments solution - EBANX Billing. The integration is the same for all Latin American countries and you're going to be walked through all the additional possibilities here.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. You may sign up for a Sandbox Account here in case you don't have one yet;
  2. Request access to the payment method talking to your Account Manager OR at your EBANX Dashboard by clicking the "Go to Expansion Request" button at the Overview pane. Please, reach out to our integration specialists in case you have any doubts on this step.

Available payment methods and currencies per country

Please check what are the avalible payment methods and currencies for each country before you start your integration. This information is going to be necessary while crearting your subscription plans, which is the foundation of your integration.

πŸ‡¦πŸ‡· Argentina

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Argentina.

  • ARS: Argentine Pesos

πŸ‡§πŸ‡· Brazil

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Brazil.

  • BRL: Brazillian Reais

πŸ‡¨πŸ‡± Chile

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Chile.

  • CLP: Chilean Pesos;

πŸ‡¨πŸ‡΄ Colombia

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Colombia.

  • COP: Colombian Pesos;

πŸ‡¨πŸ‡· Costa Rica

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Costa Rica.

  • CRC: Costa Rican Colon;

πŸ‡ΈπŸ‡» El Salvador

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for El Salvador.

  • USD: US Dollars.
Processing in USD

Please be aware that by charging your customers in USD they're going to have their purchase value converted to their local currency by the local acquirer, meaning you won't be able to ensure a fixed price for the recurring payment.

πŸ‡¬πŸ‡Ή Guatemala

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Guatemala.

  • GTQ: Quetzal.

πŸ‡²πŸ‡½ Mexico

Available payment methods
  • Credit Cards
  • Debit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Mexico.

  • MXN: Mexican Pesos;

πŸ‡΅πŸ‡¦ Panama

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Panama.

  • PAB: Panamanian Balboa.

πŸ‡΅πŸ‡Ύ Paraguay

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Paraguay.

  • PYG: Guarani.

πŸ‡΅πŸ‡ͺ Peru

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Peru.

  • PEN: Nuevo Sol;
Available currencies

πŸ‡ΊπŸ‡Ύ Uruguay

Available payment methods
  • Credit Cards
Available currencies

Bellow you find the code to be used in the currency parameter for the POST requests of ws/subscriptions/plans, while creating a new plan for Uruguay.

  • UYO: Peso Uruguayo;

How it works

To manage recurring payments through EBANX Billing you are going to need to set up your products and plans at our billing engine. Once your setup is completed you're going to be able to manage your subscriptions. Make sure you understand the concept of each of these entities before starting your integration:

Products

Products are the way to differentiate the offers of services or products of your business.

  • Each of your products can be assigned to multiple plans (1 product to N plans);
  • To every product set up at the billing engine a product_id is going to be created;
  • The product_id of your product is going to be required to assign different plans to it.

Plans

Plans are how you define the characteristics of the subscription model you want assigned to each of your products. This is how you're going to set up the periodicity, value, currency and other behaviours of the charging model you want assigned to your products.

  • Each of your plans can be assigned to multiple subscriptions (1 plan to N subscription);
  • While creating a new plan you're going to be requested to create a plan_code to it;
  • To every plan set up at the billing engine a plan_id is going to be created;
  • Both plan_code and plan_id are going to be required to create a subscription.

Subscriptions

Subscriptions are the application of the charging models defined at your plans to your end users, given their personal and payment information.

  • Each of your subscriptions represent a new end user that is going to be periodically charged by the billing engine (1 subscription to 1 end user);
  • All created subscription return a subscription_id, which is going to be used to manage your subscriptions;
  • Subscriptions can be created, read, updated and deleted through the different endpoints of this API.
  1. Create your products

    To set up a product you must send a POST request to /ws/subscriptions/products. This end-point requires the following parameters as input:

    ParameterDescription
    codeString defining the code of the product. This parameter is required.
    nameString defining the name of the product. This parameter is required.
    descriptionString defining the description of the product. This parameter is required.

    Bellow you have an example of request accepted by the end-point, creating a test product:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/products' \
    --data-raw '{
    "code": "TEST_PRDCT",
    "name": "Test Product",
    "description": "This is a test product created to assing a plan to it."
    }'

    A successful request will return a JSON response as output, like the one below:

    {
    "product_id": 2764441752
    }

    To create a plan both product_id and code are going to be necessary.

  2. Create a plan and assign it to a product

    To set up a plan and assign it to a product you must send a POST request to /ws/subscriptions/plans. This end-point requires the following parameters as input:

    ParameterDescription
    codeString defining the code of the plan. This parameter is required.
    nameString defining the name of the plan. This parameter is required.
    product_idInteger assigned to the product you're associating the plan with. This parameter is required.
    product_codeString created by you while creating the product you're associating the plan with. This parameter is required.
    grace_periodInteger defining the amount of days a subscription is going to stay with the ACTIVE status before it changes to CANCELED. This parameter is required
    amountInteger containing the value that is going to be charged for the plan. This parameter is required.
    currencyString defining the currency of the amount defined for the plan. This parameter is required.
    periodicity : lengthInteger containing the multiple of units of the plan's periodicity. This parameter is required.
    periodicity : unitString containing the unit of the plan's periodicity. Unit can be WEEKLY, MONTHLY or ANNUAL. This parameter is required.
    Periodicity

    Periodicity has two child variables to give you versatility while defining your charging periods. You can use "length": 2 and "unit": "WEEKLY" to charge a customer every 14 days, as well as "length": 3 and "unit": "MONTHLY" to charge a customer every 3 months and so on.

    Bellow you have an example of a request accepted by the end-point, creating a test plan that charges BRL 450 every month and assigning it to your test product:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/plans' \
    --data-raw '{
    "name": "Monthly test plan",
    "code": "M_TEST_PLAN",
    "product_id": 2764441752,
    "product_code": "TEST_PRDCT",
    "grace_period": 5,
    "amount": "450",
    "currency": "BRL",
    "periodicity": {
    "length": 1,
    "unit": "MONTHLY"
    }
    }'

    A successful request will return a JSON response as output, like the one below:

    {
    "plan_id": 2964341753
    }

    To create a subscription both plan_id and code are going to be necessary.

  3. Create a subscription

    To be able to create recurring payment subscriptions you must send a POST request to /ws/subscriptions/subscriptions. Use this end-point to create a new subscription after capturing your end user's personal and payment information. This end-point accepts the following parameters as input:

    ParameterDescription
    plan_codeString created by you while creating the plan you're associating the subscription with. This parameter is required.
    account.emailString containing the email of your end user. This parameter is required.
    account.documentString containing the document of your end user. This parameter is required.
    account.nameString containing the name of your end user. This parameter is required.
    acount.birth_dateString containing the birth_date of your end user. This parameter is required.
    account.addressString containing the address of your end user. This parameter is required.
    acount.street_numberString containing the street number of your end user.
    acount.cityString containing the city of your end user. This parameter is required.
    account.stateString containing the state of your end user. This parameter is required.
    account.countryString containing the country of your end user. This parameter is required.
    account.zip codeString containing the zipcode of your end user.
    acount.phone_numberString containing the phone number of your end user.
    payment_method.card_tokenString containing the token of your end user's payment information. EBANX' tokens can be created through our tokenization end-point, further information on this page. The payment_method parameter requires either the card_token OR the group of parameters in the following rows of this table. This parameter is required.
    payment_method.numberString containing your end user's credit card number. This parameter is required.
    payment_method.holder_nameString containing your end user's card holder's number. This parameter is required.
    payment_method.expiration_yearString containing your end user's card expiration year. This parameter is required.
    payment_method.expiration_monthString containing your end user's card expiration month. This parameter is required.
    payment_method.cvvString containing your end user's card verification value. This parameter is required.
    Required parameters

    Each country has different required fields that are configured to your account at EBANX' system. While creating a plan these parameters requiredness are going to be applied.

    Bellow you have an example of a request accepted by the end-point, creating a subscription and assigning its charge model to the one st up at the M_TEST_PLAN created previously, using a card token:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/subscriptions' \
    --data-raw '{
    "plan_code": "M_TEST_PLAN",
    "account": {
    "email": "random_mail@gmail.com",
    "document": "7278234525",
    "name": "Fictitious User",
    "birth_date": "1987-01-10",
    "address": "Fictitious street",
    "street_number": "171",
    "city": "Curitiba",
    "state": "PR",
    "country": "BR",
    "zipcode": "80740320",
    "phone_number": "0405777687"
    },
    "payment_method": {
    "card_token": "e548d4b0b4132b32f0100e15598f51c55a184dd86e08f111*************b91176de00fc44bf08a5c0222ff56c6fce830e0db6f98abb51bdf"
    }
    }'

    You may also create it using the customer's raw payment data, as bellow:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/plans' \
    --data-raw '{
    "plan_code": "M_TEST_PLAN",
    "account": {
    "email": "random_mail@gmail.com",
    "document": "7278234525",
    "name": "Fictitious User",
    "birth_date": "1987-01-10",
    "address": "Fictitious street",
    "street_number": "171",
    "city": "Curitiba",
    "state": "PR",
    "country": "BR",
    "zipcode": "80740320",
    "phone_number": "0405777687"
    },
    "payment_method": {
    "number": "4111000011110000",
    "holder_name": "Fictitious Name",
    "expiration_year": "2025",
    "expiration_month": "12",
    "cvv": "123"
    }
    }'

    A successful request will return a JSON response as output, like the one below:

    {
    "subscription_id": "0c002konr4308nfsa08ih340knibutyre3546e57r67",
    "status": "PENDING_ACTIVATION"
    }
    Subscription status

    All newly created subscriptions are going to have the PENDING_ACTIVATION status at its creation moment. Once subscriptions have been successfully added to our billing engine their statuses are going to be changed to ACTIVE. That process usually happens nearly instantaneously.

  4. Consult the subscription's status to give users access to your service or product

    To check a subscription's status you must send a GET request to /ws/subscriptions/get. This end-point requires a subscription_id as a query parameter at the request's URL:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request GET 'https://sandbox.ebanxpay.com/ws/subscriptions/get?subscription_id=0c002konr4308nfsa08ih340knibutyre3546e57r67

    A successful request will return a JSON response as output, like the one below:

    {
    "status": "ACTIVE"
    }

    Subscription's status are in regards to the payment status of such recurring deals. Based on a subscription's status you are able to give end users access to your service or product. Statuses are defined as bellow:

    StatusDescription
    PENDIND_ACTIVATIONThe subscription request has been received and it's being set up at the billing engine.
    ACTIVEThe subscription has been set up at the billing engine and its payments are up to date.
    CANCELLEDThe subscription has been cancelled and no further payments are coming from it.
  5. Enable your customers to cancel their subscriptions

    To enable customers to cancel their subscriptions you must send a POST request to /ws/subscriptions/cancel. This end-point requires a subscription_id as a query parameter at the request's URL:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/cancel?subscription_id=0c002konr4308nfsa08ih340knibutyre3546e57r67

    A successful request will return a JSON response as output, like the one below:

    {
    "operation_status": "success",
    "subscription": {
    "status": "CANCELLED",
    "creation_date": "2021-08-02 19:03:03",
    "cancellation_date": "2021-08-09 22:09:11"
    },
    "account": {
    "email": "random_mail@gmail.com",
    "document": "7278234525"
    },
    "plane": {
    "name": "Monthly test plan",
    "code": "M_TEST_PLAN",
    "type": "fixed_price"
    }
    }

    Once a subscription is cancelled it can't be re-activated. Should a customer desire to have its subscription restored a new subscription has to be created.

  6. Enable your customers to update their subscriptions' payment information

    To enable customers to update their subscriptions' payment information you must send a POST request to /ws/subscriptions/update. This end-point requires a subscription_id as a query parameter at the request's URL as well as the following parameters as input:

    ParameterDescription
    payment_method.card_tokenString containing the token of your end user's payment information. EBANX' tokens can be created through our tokenization end-point, further information on this page. The payment_method parameter requires either the card_token OR the group of parameters in the following rows of this table.
    payment_method.numberString containing your end user's credit card number.
    payment_method.holder_nameString containing your end user's card holder's number.
    payment_method.expiration_yearString containing your end user's card expiration year.
    payment_method.expiration_monthString containing your end user's card expiration month.
    payment_method.cvvString containing your end user's card verification value.

    Bellow you have an example of a request accepted by the end-point, updating the payment information of an existing subscription, using a card token:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/update?subscription_id=0c002konr4308nfsa08ih340knibutyre3546e57r67' \
    --data-raw '{
    "payment_method": {
    "card_token": "e548d4b0b4132b32f0100e15598f51c55a184dd86e08f111*************b91176de00fc44bf08a5c0222ff56c6fce830e0db6f98abb51bdf"
    }
    }'

    You may also update it using the customer's raw payment data, as bellow:

    curl --header "X-EBANX-Integration-Key: test__ldIjHGr**************l86vCL" \
    --request POST 'https://sandbox.ebanxpay.com/ws/subscriptions/update?subscription_id=0c002konr4308nfsa08ih340knibutyre3546e57r67' \
    --data-raw '{
    "payment_method": {
    "number": "4111000011110000",
    "holder_name": "Fictitious Name",
    "expiration_year": "2025",
    "expiration_month": "12",
    "cvv": "123"
    }
    }'

    A successful request will return a JSON response as output, like the one below:

    {
    "subscription_id": "0c002konr4308nfsa08ih340knibutyre3546e57r67",
    "status": "ACTIVE"
    }

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 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.
Last updated on by Vanderson Lopes