Pix on File Bank List

Tokenized Alternatives Bundle

Pix on File is a Pix payment flow in Brazil that links the customer's device to their bank account, so customers can authorize payments without being redirected to their bank app. Pix on File is available on both the Cross-border and Local tenants.

Pix on File is the EBANX layer on top of Pix Jornada Sem Redirecionamento, the Brazilian Central Bank (Bacen) product. Financial and payment institutions with over 500,000 active accounts, which are obligated to offer Pix, are either required to implement it or are in the process of doing so. Since availability varies by institution, query the EBANX Bank List to know which banks currently accept account linking.

This guide outlines how to retrieve the list of banks enabled for Pix on File. It covers building the request, reading the response, and using the returned bank codes when initiating Device Linking.

Requirements

• API authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, 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 EBANX Direct for more info.

How it works

• Request the bank list - Send a GET request to the ws/getBankList endpoint with payment_type=pix-jsr.
• Display the banks - Show the returned banks so the customer can select the one that holds their account.
• Start Device Linking - Send the selected bank code as enrollment.account_details.bank_id in the Device Linking request.

Instructions

Follow the steps below.

Sample requests use the Local host

The sample requests on this page are sent to the Local sandbox host. If you operate Cross-border, send the same request to the Cross-border host — paths and payloads are identical.

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.

   Check the method's availability for your country and tenant in Payment Methods by Country. Questions about tenant and environment? Check our API Operability and API Endpoints.

   Cross-border sandbox

   https://sandbox.ebanxpay.com/ws/getBankList

2. Define your parameters

   This is a GET request and all parameters are sent as query string parameters. Do not send a request body.

   Parameter	Requirement	Description
   integration_key	Required	Your integration key
   country	Required	Must be br
   payment_type	Required	Must be pix-jsr

   Use payment_type, not payment_type_code

   This endpoint reads the payment method from payment_type. Any other name — including payment_type_code, used by the payment and enrollment endpoints — is ignored, and the request still returns HTTP 200 with a generic Brazilian bank list that is not the Pix on File list. Always confirm the returned codes come from this endpoint with payment_type=pix-jsr.

3. Bank list request

   Send the request to the ws/getBankList endpoint.

   Sample request

   Shell

   curl -X GET 'https://sandbox-local-latam.ebanxpay.com/ws/getBankList?integration_key={{integration_key}}&country=br&payment_type=pix-jsr'

4. Bank list response

   A successful request returns a JSON response like the one below, containing an array of banks. The values listed as {bank_code} are the acceptable enrollment.account_details.bank_id values when initiating Device Linking.

   JSON

   [
     {
       "code": "{bank_code}",
       "name": "{bank_name}",
       "logo_url": "{bank_logo_svg}"
     }
   ]

   logo_url is only present when the institution has a logo registered, so treat it as optional when rendering a bank selector.

5. Congratulations!

   You have successfully retrieved the Pix on File bank list.

   Next, link the customer's device in

   Pix on File Device Linkingchevron_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.