Pix Biometric

Account Linking (First time users)

• Consent & Authentication: Users link their bank account to a payment initiator (e.g., wallet or merchant app) through a secure one-time redirect to their bank’s environment for authentication, to confirm they trust the initiator with payment access.

• Device Binding: Post-authentication, a public-private key pair is generated. The private key is securely stored in the device’s secure element (SE), while the public key is sent to the bank. For future payments, the bank verifies the transaction by validating a biometric-signed challenge using the stored public key— ensuring that only that specific device can initiate transactions without redirection​.

• Biometric Setup: The user sets up device biometrics (fingerprint, facial recognition) or a PIN for future payment approvals.

• Security Management: In case of device loss or compromise, credentials can be remotely revoked immediately either through the merchant or user's bank app.

Payment Initiation & Authentication  (Repeat users)

• Direct Initiation: User initiates Pix payment directly from the merchant or wallet app by selecting "Pay with Pix" at checkout or tapping their device on a POS terminal—no redirects or QR scans involved.

• Local Biometric Authentication: Payment is authorized instantly within the initiator’s app using the stored biometric credential or device PIN, validated locally by the initiator.

• Real-time Bank Validation: The initiator securely requests the transaction from the bank using Pix APIs. The bank trusts this request due to the previously established secure device linking and verifies it with real-time fraud checks.

• Instant Completion: Upon validation, the bank immediately executes the transfer, settling funds directly to the merchant, with the user receiving real-time confirmation—all seamlessly within the initiator’s interface.

This entire payment flow happens securely and instantly, without the need to leave the merchant’s or initiator’s app environment, significantly enhancing user convenience and transaction speed.

Integration Guide:

Step 1.1

Create Customer Call

This API is responsible for creating a new customer object in Juspay systems. You can invoke this API whenever a new user registers in your App/Website and is triggering the payment process.

Note

This is a mandatory call only while registering new customers with Juspay, If you have already registered the customer you can use the same customer reference in the subsequent calls.

Step 1.2

Create Order API Call

This is a Server-to-Server API that takes order parameters as an input and creates an order in the Juspay system and fetches the corresponding client_auth_token.

Note

For PIX Biometric:

• identity_credentials field is a required field, this takes customer’s cpf/cnpj/pix_key as input

• account_registration_date field is a required field, this is the date when customer registered with the business

Step 2

Initiating the Juspay SDK

To initialise the SDK, client needs to call the initiate SDK function. The initiate function call boots up the SDK and makes it ready for all other operations.

Note

• TENANT_NAME: Set the value tojuspayglobal

• CLIENT_ID: Use the client ID provided by Juspay for the respective tenant.

Step 3

Process Transaction via Juspay SDK

Retrieve Information about all the configured payment method via Get Payment Methods
then once the customer selects the preferred Payment Method Pass the adequate payload in process function of the SDK.

Step 4.1.

Handle Payment Events from SDK

All payment responses are sent by the SDK in the HyperPaymentCallbackHandler under the process_result event.
Implement the highlighted code snippet in your app for proper handling of all events and status

Step 4.2.

Check Payment Status

After receiving process_result from SDK, it is mandatory to do a Server-to-Server Order Status API call to determine the final payment status. Please ensure that you verify the order ID and amount transaction.

Step 4.3.

Display Payment Status

Once the payment status is determined via the API, the final status should be displayed to the user. This screen needs to be handled by the merchant, it is not provided by the SDK

FAQs: