BRL Pay-in Business Integration Guide

This guide outlines the core business logic and technical workflow for integrating Brazilian Real (BRL) payment services via BPN.

We recommend sharing the user's KYC/KYB information via this interface to streamline the payment process. However, if the merchant does not have KYC information to share, this step can be skipped, and you may proceed directly to Step 2 (Request Payment Session).

API Endpoint: Share KYB/KYC Info For Sub User

Business Logic:

Individual Users: You must provide the legal Name and CPF (Brazilian Individual Tax ID).

Corporate Users: You must provide the Company Name and CNPJ (Brazilian Business Tax ID).

Result: The system returns subUserId and externalUserId. Store these IDs, as they are required to link the user to their future transactions.

2. Request Payment Session (Checkout)

After identity verification, you can request a payment session to generate the checkout interface for the user.

API Endpoint: Request Pay Session

Core Requirements:

Identity Reference: Provide the subUserId or externalUserId obtained in the previous step.

Redirect URL: You must provide a merchant callback URL. Once the user completes the payment or exits the payment page, BPN will automatically redirect them back to your specified link.

Result: The API returns a redirectUrl. You should redirect the user to this URL to display the PIX QR code or bank transfer instructions.

3. Transaction Status Notification (Webhook)

Since BRL payments (specifically PIX) are processed asynchronously, your system must listen for status updates.

API Endpoint: Transaction Status Notification

Usage:

BPN will push a notification to your configured Webhook URL when the Pay-in status changes.

Use this to capture the final status (e.g., SUCCESS) and the Platform Order Number.

Security: It is highly recommended to verify the notification signature to ensure the data is authentically from BPN.

4. Order Query & Reconciliation

For manual reconciliation or as a fail-safe if a Webhook is missed, use the query interface to check specific transaction details.

API Endpoint: Get Reconciliation Order List By Page

Usage:

Query the full details of a BRL transaction using the Merchant Order No or Platform Order No.

Retrieve granular data including the exact BRL amount received, fees, and timestamps.

Notes:

Ensure all BRL amounts are handled with correct decimal precision as specified in the technical docs.

The redirectUrl in Step 2 typically expires after a short period; it should be generated at the time of the user's intent to pay.

BRL Pay-in Business Integration Guide

BRL Pay-in Business Integration Guide#

1. Identity Verification (KYC/KYB Sharing)#

2. Request Payment Session (Checkout)#

3. Transaction Status Notification (Webhook)#

4. Order Query & Reconciliation#

BRL Pay-in Business Integration Guide

1. Identity Verification (KYC/KYB Sharing)

2. Request Payment Session (Checkout)

3. Transaction Status Notification (Webhook)

4. Order Query & Reconciliation