Pix with Direct API

Overview

This guide will walk you through a basic API integration that accepts payments via Pix in EBANX.

note

PIX is offered by EBANX Instituição de Pagamento Ltda (Juno), which is a direct participant of the instant payment arrangement as specified in the Resolution nº1 of the Brazilian Central Bank.

About this guide

By following this basic integration guide, you will understand how you can accept Pix payments in your ckeck-out, by using EBANX Direct API. To complete a payment with Pix you will need a single API call that will create the payment and provide the necessary information for the customer to complete the transaction.

Availability

Pix integration through Direct API is available in Brazil only.

What you will need

A Sandbox Account

As with any secure payment integration, you will first need to set up authorization. The EBANX sandbox allows you to set up a test environment to run transactions using test credit card numbers and explore our payment solutions.

Sign up for an Sandbox Account at our EBANX Business Page, select your business model and answer a few questions. We'll get in touch with you shortly after!

Sign up for an EBANX Sandbox Account here

How it works

To complete a Pix payment, please follow the steps below.

1. Enable Pix in your dashboard

   The first step is to check if Pix are active in your EBANX Dashboard.

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

2. Call the /ws/direct API to get the Pix link and QR Code

   Pix provides the option of redirecting the customer to a voucher created by EBANX or to get the raw QR Code. To get this link, you just need to call the end-point ws/direct (server-side) with the following required fields:

   • Operation: Must be request;
   • Payment type code: Must be pix;

   Customer data:

   • Customer name;
   • Customer e-mail;
   • Customer document;
   • Customer address;
   • Customer street number;
   • Customer city;
   • Customer state;
   • Customer zip-code;
   • Customer phone number

   Charge info:

   • Unique merchant payment code;
   • Currency code (BRL or USD);
   • Total amount to be charged;
   • Expiration time in seconds

   Check the example:

   curl -X POST 'https://sandbox.ebanxpay.com/ws/direct' \

   -d 'request_body={

   "integration_key": "your_test_integration_key_here",

   "operation": "request",

   "payment": {

   "name": "José Silva",

   "email": "jose@example.com",

   "document": "853.513.468-93",

   "address": "Rua E",

   "street_number": "1040",

   "city": "Maracanaú",

   "state": "CE",

   "zipcode": "61919-230",

   "country": "br",

   "phone_number": "8522847035",

   "payment_type_code": "pix",

   "merchant_payment_code": "a92253f29db",

   "currency_code": "BRL",

   "amount_total": 100

   "expiration_time_in_seconds": 3600

   }

   }'

   A successful request will return a JSON response like the one below. The Pix redirect link will be in the parameter payment.redirect_url, and the QR Code will be the value of payment.pix.qr_code_value.

   {

   "payment": {

   "hash": "59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",

   "pin": "655158605",

   "merchant_payment_code": "af461f512c1",

   "order_number": null,

   "status": "PE",

   "status_date": null,

   "open_date": "2017-09-04 14:06:09",

   "due_date": "2017-09-04",

   "confirm_date": null,

   "transfer_date": null,

   "amount_br": "100.38",

   "amount_ext": "100.00",

   "amount_iof": "0.38",

   "currency_rate": "1.0000",

   "currency_ext": "BRL",

   "payment_type_code": "pix",

   "redirect_url": "https://sandbox.ebanxpay.com/print/?hash=59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",

   "pix": {

   "qr_code_value": "00020101021226590014br.gov.bcb.pix2537pix-h.juno.com.br/qr/D762CC0E270360DF52040000530398654042.015802BR5910EBANX Ltda6008CURITIBA62240520JNPX2020110400000004630474D0"

   },

   "pre_approved": false,

   "capture_available": null

   },

   "status": "SUCCESS"

   }

   note

   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.

3. Presenting the Pix QR Code

   You can present the QR code in two different ways, by either redirecting your customer to our payment voucher (redirect_url), or by rendering the code at your page.

   Redirect customer to our payment voucher (Recommended)

   Redirect your customer to the URL returned in the parameter redirect_url. The experience will look like this:

   

   You can also present this voucher in a modal, an iframe or in a webview, so the customer can pay without leaving your site or app.

   Rendering the Pix QR code

   You can also render the payment information at your own page. The suggested experience can be seen below.

   For Desktop

   

   1. When presenting the payment info, reinforce that this is Pix payment

   2. Present the value and the expiration clearly. Keep in mind that although Pix is an instant payment, the customer can take some time to pay it, and the payment is valid for 4 hours.

   3. Present the QR clearly and with a good contrast. To display the QR Code, render it using the value provided by the API request and a QR Code library of your choice.

   4. In desktop payments, the button is a secondary interaction, but you can show it so the customer can copy it and send it to herself/himself if needed.

   5. Finally, you can also present some instructions so the customer can feel more comfortable paying.

   For Mobile Devices

   

   1. You can offer a short explanation when the payment method is selected. Also, it's important to pay attention to the branding: Pix must be always written with the first capital letter.

   2. Use a clear call to action to reinforce the method selection.

   3. When presenting the payment info, reinforce that this is Pix payment

   4. Present the value and the expiration clearly. Keep in mind that although Pix is an instant payment, the customer can take some time to pay it, and the payment is valid for 4 hours.

   5. Present the QR clearly and with a good contrast. Note: although is good for recognition of the payment, the QR code is optional for mobile users.

   6. In mobile payments, provide a button so the customer can copy the code and pay in her/his app.

   7. Finally, you can also present some instructions so the customer can feel more comfortable paying.

   Copying QR Code to Clipboard

   Alternatively, you can simply deliver the QR Code number from payment.pix.qr_code_value to your customer's clipboard so they can paste it into their banking/wallet app.

   At this point you have a pending (PE) payment in your EBANX Dashboard.

4. Wait for the payment

   As soon as we get the confirmation, payment status is modified from pending (PE) to confirmed (CO).

   Important!

   Pix payments expire after 4 hours. If your customers don't complete the payment via pix in time, the payment will be automatically canceled.

Getting help

If you have any doubts or need help, you can send and email to: EBANX Integration