Pix

PIX is a real-time payment solution developed by the Brazilian Central Bank, enabling instant transfers 24/7 through QR codes and other identifiers. By integrating PIX with the EBANX Direct API, merchants can offer Brazilian customers a fast and secure payment option that supports immediate fund transfers across accounts. This guide provides step-by-step instructions on how to implement PIX within your EBANX integration, including creating QR codes, managing transactions, and ensuring a smooth user experience. Integrating PIX through EBANX helps businesses streamline transactions while expanding accessibility for Brazil’s large base of digital and mobile payment users.

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.

How it works

• Set up a payment request through the EBANX API and choose PIX as the payment method.
• Generate a QR code for the customer, or redirect them to an EBANX-hosted QR code.
• Display the QR code, amount, and expiration date clearly for the customer.
• Monitor payment status until confirmed.

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. Create a Pix link

   Pix is an instant payment system which allows customers to make payments directly from their bank account using QR codes. To create a Pix link and QR Code, gather the required information for your request then call the ws/direct endpoint with the required parameters.

   
   

   Defining API parameters

   You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.
   
   

   Essential parameters

   • payment.payment_type_code - Specifies the payment method to be used for the transaction.
   • payment.currency_code - Three-letter code of the payment currency.
   • payment.amount_total - Total amount to be charged.

   
   

   Additional parameters

   • EBANX Integration Key - Used to authenticate and authorize API requests.
   • Customer Information
     • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
     • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
   • Additional Context - Extra data for specific methods or countries.

   
   

   To learn more about API parameters, please refer to the

   API Reference Guide chevron_right

   At the API Reference Guide, select Brazil and Pix from the dropdown menues.

3. Sample request

   Here’s an example using cURL to initiate a PIX payment:

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_test_integration_key_here",
       "operation": "request",
       "payment": {
         "name": "José Silva",
         "email": "jose@example.com",
         "document": "853.513.468-93",
         "country": "br",
         "payment_type_code": "pix",
         "merchant_payment_code": "a92253fwe29djbs2",
         "currency_code": "BRL",
         "amount_total": 100,
       }
     }'

4. Sample response

   A successful request returns a response similar to the example below.

   • The PIX redirect link is located in the payment.redirect_url parameter.
   • The raw QR Code value is provided in payment.pix.qr_code_value.
   
   

   {
   "payment": {
     "hash": "6753669df5c6e02853a53f75d84e8f30572b205d5233a2ab",
     "country": "br",
     "merchant_payment_code": "a92253fwe29djbs2",
     "order_number": null,
     "status": "PE",
     "status_date": null,
     "open_date": "2024-12-06 21:03:25",
     "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",
     "due_date": "2024-12-06",
     "instalments": "1",
     "payment_type_code": "pix",
     "redirect_url": "https:\/\/sandbox.ebanx.com\/pix\/checkout?hash=6753669df5c6e02853a53f75d84e8f30572b205d5233a2ab",
     "pre_approved": false,
     "capture_available": null,
     "pix": {
       "qr_code_value": "00020101021226780014br.gov.bcb.pix2556fake-pix.com.br\/qr\/v2\/ACA4311F88661BC0D48200487EF1BCD95204000053039865802BR5910FAKEPIX Ltda6008CURITIBA62070503***58550"
     }
   },
   "status": "SUCCESS",
   "redirect_url": "https:\/\/sandbox.ebanx.com\/pix\/checkout?hash=6753669df5c6e02853a53f75d84e8f30572b205d5233a2ab"
   }
   At this stage, the payment will appear as pending (PE) in your

   EBANX Dashboardchevron_right

5. Show voucher using redirect URL (Option 1)

   Use the redirect_url to redirect your customer to an external page to display the Pix voucher and QR code.

   Sample redirect URL:

   

6. Show voucher within your site (Option 2)

   Instructions

   • Use a modal, iframe or webview to display the voucher within your site (or app).
   
   

   Guidelines for Desktop

   • Clearly indicate that this is a PIX payment.
   • Display the payment amount prominently.
   • Display the expiration time. PIX is instant but customer may take time to complete payment.
   • Render the QR code with high contrast, using a QR code library and the raw value provided by the API.
   • Include a button for easy copying, allowing customers to send the link to themselves if needed.
   • Provide clear instructions to make the customer comfortable with the payment process.

   Example on desktop:

   
   
   

   Guidelines for Mobile

   • Provide a brief overview of PIX. Ensure branding by capitalizing “Pix”
   • Use a clear call-to-action to reinforce payment-method selection.
   • Confirm that the payment-type is Pix when displaying payment info.
   • Display the payment amount and 4-hour expiration clearly.
   • Show the QR code with high contrast (optional for mobile users).
   • Provide a copy button to allow user to copy the code and pay in their app.
   • Provide clear instructions to make the customer comfortable with the payment process.

   Example on mobile device:

   
   
   
   
   Copying QR Code to Clipboard

   Copy the payment.pix.qr_code_value directly to the customer's clipboard, allowing them to paste it into their banking or wallet app.

7. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO).

   • Pix payments expire based on one of the following:

     • The default set by Pix (30 minutes).
     • The request parameter expiration_time_in_seconds (overrides default).

   • If the customer does not complete the payment within this timeframe, the status will automatically update to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

8. Congratulations!

   You have succesfully integrated Pix.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

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.