Version: current

Multi Benefits Voucher with Direct API

About this guide

This page explains how to add Multi Benefits Voucher to your existing Direct API integration. Direct API integration is basically the same for all payment methods, only varying the payment_type_code and some additional required fields.

If you are not integrated with EBANX Direct API yet, please take a look in this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

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

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. Multi Benefits Voucher enabled in your EBANX Dashboard.


Multi Benefits Voucher integration through Direct API is available to the following countries:

  • Brazil

How it works

To complete Multi Benefits Voucher integration through EBANX Direct API, please follow the steps below.

  1. Enable Multi Benefits Voucher

    The first step is to check if Multi Benefits Voucher is active in your EBANX Dashboard.

    All set? We can go ahead to next step, otherwise, please get in touch with our integration specialists.

  2. Make sure you have all the mandatory fields in your request

    As a starting point, your request must have the payment_type_code set as vr-multibeneficios, as well as the Multi Benefits Voucher schema below.

    The Multi Benefits Voucher schema:

    The below fields are mandatory in your request.

    card_numberMulti Benefits Voucher number.
    card_nameMulti Benefits Voucher cardholder name.
    card_due_dateMulti Benefits Voucher due date (“valid thru”) in the format mm/yyyy.
    card_cvvMulti Benefits Voucher security code.
  3. Send your payment request to EBANX

    Now, you just need to send your payment request to EBANX, below you can check a example:

    "integration_key": "xxxxxxxxxxx",
    "operation": "request",
    "mode": "full",
    "payment": {
    "merchant_payment_code": null,
    "amount_total": 6.08,
    "currency_code": "BRL",
    "name": "José Silva",
    "email": "",
    "birth_date": "12/04/1979",
    "document": "85351346893",
    "address": "Rua E",
    "street_number": "1040",
    "street_complement": "CJ 5",
    "city": "CURITIBA",
    "state": "PR",
    "zipcode": "81500000",
    "country": "br",
    "phone_number": "4111111111",
    "payment_type_code": "vr-multibeneficios",
    "instalments": "1",
    "card": {
    "card_number": "****************",
    "card_name": "test customer",
    "card_due_date": "02/2030",
    "card_cvv": "***",
    "auto_capture": true

    A successful request will return a JSON response similar to the one below. A confirmed payment will have a CO (confirmed) status while a canceled payment will have a CA (canceled) status.

    "payment": {
    "hash": "59ad5f00945fa382ab051651440826da7701533249b3a475",
    "merchant_payment_code": "ecc9be4512a",
    "order_number": null,
    "status": "CO",
    "status_date": "2017-09-04 14:11:12",
    "open_date": "2017-09-04 14:11:11",
    "confirm_date": "2017-09-04 14:11:12",
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2017-09-07",
    "instalments": "1",
    "payment_type_code": "vr-multibeneficios",
    "details": {
    "billing_descriptor": ""
    "transaction_status": {
    "acquirer": "EBANX",
    "code": "OK",
    "description": "Sandbox - Test vr, transaction captured"
    "pre_approved": true,
    "capture_available": false
    "status": "SUCCESS"

    The complete API reference for the end-point ws/direct can be found here. We strongly recommend you to take a look in all the available options.

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
Last updated on by José Cristiano de Sousa