PIX por biometria

With a regular Payment Request, the payer is redirected to their bank on every payment to approve it. With PIX por biometria, the payer goes to the bank only once, to link an account to their device. From then on, they confirm each payment on the Pluggy payment page with Face ID, their fingerprint or the device's screen lock, without leaving the page.

PIX por biometria is the Open Finance Jornada Sem Redirecionamento (JSR). The payment is still a Pix initiated through Open Finance: it settles instantly, and you track it with the same Payment Requests, Payment Intents and webhooks you already use.

How it works#

The first payment on a device#

1. The payer opens the paymentUrl and chooses their bank. Only institutions that support linking are listed.
2. The page explains what linking means, and the payer is redirected to the bank. There they approve the link and set their limits. They have up to 15 minutes to do it.
3. Back on the payment page, the payer creates a passkey with the device's biometrics or screen lock. This completes the link.
4. The payer confirms the payment with biometrics, and the Pix is sent.

Every later payment#

On the same device and browser, the payment page finds the payer's linked account and shows it next to the payment details. The payer confirms with biometrics and the payment is sent. There is no bank redirect.

The payer can also choose to pay with another bank, which starts the first-payment path for that institution.

Concepts#

• Payment Request: one per purchase, created with POST /payments/requests/pix-biometric. You send its paymentUrl to the payer, as with any payment request.
• Payment Intent: each attempt to pay a request. PIX por biometria intents have paymentMethod: "PIX_BIOMETRIC" and an enrollmentId. Only the payment page creates them.
• Enrollment: the linked account. It ties the payer's account at one institution to one device and browser. Only the payer can create it, on the payment page. You can list, read and revoke enrollments through the API. See Managing linked accounts.

Compared with a regular payment request#

Requirements and limits#

• Payment Initiation must be enabled for your client.
• Institutions: the institution must support linking. Check supportsPixBiometric on the connector (see Coverage).
• Device: the payer needs biometrics or a screen lock and a browser that supports passkeys. Some apps' built-in browsers cannot use passkeys; when the page detects one, it asks the payer to open the link in the device's browser.
• One link per device: a link belongs to the device and browser where the passkey was created, to the payer's CPF or CNPJ, and to your client. On another device or browser, the payer links again, which creates a new enrollment.
• Limits: when linking, the payer sets a per-payment and a daily limit at the bank. The institution rejects a payment above them. The enrollment's limits field shows them.
• Expiration: each link has an expiration date set by the institution (expiresAt). After it, the payer links again.
• Recipients: payments go to bank account recipients. Smart account recipients are not supported.

Sharing balance (optional)#

Create the payment request with linkedJourney: true to let the payer also share their account balance and overdraft limit with you when they link, in the same approval at the bank. Sharing is optional for the payer and unchecked by default. It lasts as long as the link, and you read the balance through the API before charging, to avoid payments rejected for insufficient funds. See Managing linked accounts.

Unlinking#

The payer can undo a link at any time in their bank's app. You can revoke a link through the API. Either way, the next payment on that device goes through the bank again to create a new link.

See Getting Started with PIX por biometria to create your first payment request.