Version: current

Meal Voucher with Direct API

About this guide

This page explains how to add Meal 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. Meal Voucher enabled in your EBANX Dashboard.

How it works

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

  1. Enable Meal Voucher

    The first step is to check if Meal 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, as well as the meal voucher schema below.

    The Meal Voucher schema:

    The below fields are mandatory in your request.

    card_numberMeal voucher number.
    card_nameMeal voucher cardholder name.
    card_due_dateMeal Voucher due date (“valid thru”) in the format mm/yyyy.
    card_cvvMeal 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:


    In the request, the identification of the affiliation with VR must be sent in the metadata node, like this:

    "metadata": {
    "vr": {
    "affiliation_id": "1491172"

    We need this ID to send it to VR, and they can send the amount to the restaurant.

    "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",
    "instalments": "1",
    "metadata": {
    "vr": {
    "affiliation_id": "1491172"
    "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",
    "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 Fernando Pankiewicz Gomes