Pix on File Hosted Flow

Tokenized Alternatives Bundle

Pix on File is a Pix payment flow in Brazil that allows customers to authorize payments with a device linked to their bank account, without scanning a QR code for each purchase. The hosted flow keeps Risk Signals collection and the FIDO2/WebAuthn ceremony out of the merchant application: EBANX returns a redirect URL, runs device linking and customer authentication on its own page, and notifies the merchant by webhook once the enrollment and the payment are fully authenticated. Pix on File is available on both the Cross-border and Local tenants.

This guide outlines the key concepts and implementation details required to integrate the Pix on File hosted flow via API. It covers essential steps such as creating a hosted enrollment, redirecting the customer for authentication, requesting payments against an active enrollment, and handling the webhook notifications that confirm each step.

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

The hosted flow significantly reduces integration complexity:

• You redirect customers to an EBANX-hosted URL.
• EBANX securely collects risk signals and processes WebAuthn.
• Once completed, the merchant is notified via Webhooks.

Enrollment Flow

The enrollment process establishes the authorization between merchant and customer. In this hosted flow, device linking confirmation is handled entirely by EBANX during the redirect.

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/userenrollment

2. Provide the bank list (optional)

   The merchant can optionally show a bank list and let the user select their bank. This step is optional because if no bank is selected, the same bank list dropdown will be shown during the EBANX redirect anyway.

   Like the bank, the merchant can also send enrollment.identification. When this field is provided by the merchant, it is prefilled on the Hosted page and cannot be modified by the customer.

3. Create an enrollment

   Create an enrollment for the customer using the ws/userenrollment endpoint.

   Shell

   curl -X POST \
     --location 'https://sandbox-local-latam.ebanxpay.com/ws/userenrollment' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "payment_type_code": "pix-jsr",
       "operation": "hosted_enrollment",
       "enrollment": {
           "country": "br",
           "merchant_enrollment_code": "{{unique_enrollment_code}}",
           "notification_url": "https://merchant.example.com/callback",
           "intent_url": "{{intent_url}}",
           "email": "john.doe@example.com",
           "identification_type": "{{identification_type}}",
           "identification": "{{tax_id}}",
           "account_details": {
               "bank_id": "{{bank_id}}"
           }
       }
   }'

   The response will contain the redirect_url — the page where your customer completes their WebAuthn registration and authorizes the bank.

   JSON

   {
     "status": "SUCCESS",
     "redirect_url": "https://merchant.example.com/callback",
     "enrollment": {
       "enrollment_code": "{{unique_enrollment_code}}",
       "status": "pending"
     }
   }

   Field naming across surfaces

   You send enrollment.merchant_enrollment_code, but the API response returns the same value as enrollment.enrollment_code. The webhook sent to your notification_url uses enrollment.merchant_enrollment_code again. Map each surface explicitly rather than reusing one key.

   redirect_url is an EBANX-hosted page

   The sample above uses this documentation's standard placeholder domain, but the value you receive is an EBANX-hosted page — it is not on your domain, and it is not the notification_url you supplied. That one is your own backend endpoint, which EBANX calls with status updates.

   
   
   

   Treat redirect_url as opaque: send the customer to whatever value you receive, unchanged, and never rebuild it.

   Instead of performing device linking in your app, all the complex authentication is handled in this redirect. You should receive a webhook from EBANX once the enrollment is fully confirmed and authenticated.

4. Monitor enrollment status

   Listen for webhook notifications on your notification_url. Once the enrollment is activated, you can proceed to request payments using the active merchant_enrollment_code.

Payment Flow

Once an active enrollment is established, you can start requesting payments. The same idea applies: all customer presence authentication (WebAuthn) is handled by the EBANX app redirect, and the merchant only needs to receive a webhook when the payment reaches a confirmed status.

1. Create a payment

   Initiate the payment with the ws/direct endpoint, citing the established merchant_enrollment_code in the metadata object.

   Shell

   curl -X POST \
     --location 'https://sandbox-local-latam.ebanxpay.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "type": "request",
       "mode": "full",
       "payment": {
           "country": "br",
           "currency_code": "BRL",
           "amount_total": 99.85,
           "merchant_payment_code": "{{unique_merchant_code}}",
           "order_number": null,
           "payment_type_code": "pix-jsr",
           "name": "John Doe",
           "email": "john.doe@example.com",
           "document": "{{tax_id}}",
           "metadata": {
               "merchant_enrollment_code": "{{unique_enrollment_code}}"
           }
       }
   }'

   You will receive a pending payment response containing payment["pix-jsr"].hosted_url_payment. Redirect the customer to that URL to provide their biometric approval.

   JSON

   {
     "payment": {
       "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
       "country": "br",
       "merchant_payment_code": "{{unique_merchant_code}}",
       "order_number": null,
       "status": "PE",
       "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "99.85",
       "amount_ext": "99.85",
       "amount_iof": "1",
       "currency_rate": "1",
       "currency_ext": "BRL",
       "due_date": "{{YYYY-MM-DD}}",
       "payment_type_code": "pix-jsr",
       "pix-jsr": {
         "hosted_url_payment": "https://payment.ebanx.com/pix-jsr-payment?hash=59acc5f00945fa382ab051651440826da7701533249b3a475&tenant=LOCAL_LATAM"
       }
     },
     "status": "SUCCESS"
   }

   The hosted payment URL is not a top-level redirect_url

   The enrollment step returns its URL as a top-level redirect_url, but the payment step does not. The hosted payment URL is nested at payment["pix-jsr"].hosted_url_payment, and there is no redirect_url anywhere in the payment response. Read the nested field.

   PE is not a confirmed payment

   The payment stays in PE until the customer completes the biometric approval on the hosted page and the provider reports the payment completed, after which EBANX marks it CO. That transition arrives through the payment status-change notification. Release goods or services on CO — never on the SUCCESS above.

2. Wait for confirmation

   You will receive a webhook notification when the payment is fully confirmed by the customer.

   • Learn more about Payment Notificationschevron_right
   • Learn more about Retrieving Payment Statuschevron_right

3. Congratulations!

   You have successfully integrated the Pix on File hosted flow.

   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.