Multi Benefits Voucher

The Multi Benefits Voucher allows Brazilian merchants to accept a variety of employer-sponsored vouchers (like meal and food vouchers) through a single integration. These vouchers are widely used in Brazil and give employees the flexibility to pay for meals and groceries at affiliated establishments.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See Direct API Guide for more info.

Considerations

• VR Affiliation ID - Partner with providers to obtain unique affiliation IDs for your company.
  • An affiliation ID is a unique identifier assigned by a voucher provider (like VR, Sodexo, or Ticket) to a merchant or business that is authorized to accept that provider’s payment vouchers.
• Similar to other payment types - Works similar to a regular payment with the EBANX Direct API, with a few differences to accommodate the voucher-specific requirements.
• Transaction Parameters: Gather key information such as payment type and affiliation ID for each transaction.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Define your parameters

   Gather information for the HTTP request.

   Parameter	Description
   operation	Set to request
   integration_key	Your EBANX integration key
   payment.payment_type_code	Set to vr-multibeneficios
   payment.country	Set to br for Brazil.
   metadata.vr.affiliation_id	Your merchant VR affiliation ID

   Meal voucher parameters.

   Parameter	Description
   card_number	Multi benefits voucher number.
   card_name	Multi benefits voucher cardholder name.
   card_due_date	Multi benefits Voucher due date (“valid thru”) in the format mm/yyyy.
   card_cvv	Multi benefits Voucher security code.

   Customer data.

   Parameter	Description
   name	Customer name
   email	Customer e-mail
   document	Customer document
   address	Customer address
   street_number	Customer street number
   city	Customer city
   state	Customer state
   zipcode	Customer zip code
   phone_number	Customer phone number

3. Sample request

   Use the following example to initiate a request.

   {
     "integration_key": "xxxxxxxxxxx",
     "operation": "request",
     "mode": "full",
     "payment": {
       "merchant_payment_code": null,
       "amount_total": 6.08,
       "currency_code": "BRL",
       "name": "José Silva",
       "email": "jose@example.com",
       "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
       }
     }
   }

4. Sample response

   A successful request will return a response similar to the example below.

   • A confirmed payment will display a status of confirmed (CO)
   • A canceled payment will display a status of canceled (CA)
   
   

   {
     "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"
   }
   
   
   At this stage, the payment will appear as pending (PE) in your

   EBANX Dashboardchevron_right

5. Congratulations!

   You have succesfully integrated Multi Benefits Voucher.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

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

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.