Guideline

For platforms that will use PIX as the payment method the integration will, usually, consist in three steps:

1. Setup
2. Requests to our endpoints
3. Receiving our webhooks

Setup

The initial setup is described in the general setup section, and no specific configuration is required in this case. The general configuration has two steps:

• Obtaining an API Token to communicate with our API
• Setting up a processor that will enable operations with the partner banking service

Requests to our endpoints

Request a pay-in

The deposits endpoint is the one that will be used to request a QR code for the PIX payment. You can use the endpoint /api/pix/charge for Users and /api/pix/merchant/funds for Merchant.

sequenceDiagram
    autonumber
    actor Customer
    participant Platform
    participant Gateway
    participant BankingPartner as "Banking Partner"

    Customer ->> Platform: Requests a deposit
    Platform ->> Gateway: [POST] /api/pix/charge

    alt Compliance/Validation issue
        rect rgba(255, 0, 0, .1)
            Gateway ->> Platform: Returns 422 error
            Platform ->> Customer: Shows error message
        end
    else Success
        Gateway ->> BankingPartner: Requests QR Code
        BankingPartner ->> Gateway: Returns QR Code
        Gateway ->> Platform: Returns QR Code
        Platform ->> Customer: Displays QR Code

        Customer -->> BankingPartner: Makes PIX payment
        BankingPartner ->> Gateway: Confirms payment
        Gateway ->> Platform: [Webhook] Successful deposit
        Platform ->> Customer: Credits account
    end

On Step 2, When making a request to the [POST] /api/pix/charge endpoint you will receive a 422 error if the customer is not compliant or if the PIX key is not valid. In this case you should show an error message to the customer. This transaction will not be processed and will be marked with a failure status on our side.

If everything is ok, the gateway will request the QR code to the payment service provider and return it to the platform. The platform will show the QR code to the customer (Steps 5 to 8).

On step 9, the customer will make the PIX payment and the PSP will return the payment confirmation to the gateway. The gateway will then send a successfull deposit webhook to the platform. Finally, the platform will credit the customer account with the amount of the deposit.

⚠️

The user account should be credited only after receiving the successfull deposit webhook. This is the only way to guarantee that the payment was processed and the customer account should be credited.

Request a pay-out

This endpoint is the one that will be used to request a withdrawal from the merchant account to customer bank account. You can use this endpoint like described on the request details following this link.

sequenceDiagram
    autonumber
    actor Customer
    participant Platform
    participant Gateway
    participant BankingPartner as "Banking Partner"

    Customer ->> Platform: Requests a withdrawal
    Platform ->> Gateway: [POST] /api/pix/pay

    alt Compliance / Validation / Balance issue
        rect rgba(0, 0, 255, .1)
            Gateway ->> Platform: Returns 422 error
            Platform ->> Customer: Shows error message
        end
    else Success
        Gateway ->> BankingPartner: Requests the withdrawal
        BankingPartner ->> Gateway: Confirms withdrawal request
        Gateway ->> Platform: Confirms withdrawal request
        Platform ->> Customer: Blocks withdrawal amount

        alt Banking failure
            rect rgba(0, 0, 255, .1)
                BankingPartner -->> Gateway: Returns withdrawal failure
                Gateway ->> Platform: [Webhook] Refund
                Platform ->> Customer: Refunds the blocked amount
            end
        else Success
            BankingPartner -->> Gateway: Confirms payment
            Gateway ->> Platform: [Webhook] Successful withdrawal
            Platform ->> Customer: Releases the withdrawn amount
        end
    end

On Step 2, When making a request to the [POST] /api/pix/pay endpoint you will receive a 422 error if the customer is not compliant or if your account is out of funds. In this case you should show an error message to the customer. This transaction will not be processed and will be marked with a failure status on our side.

If everything is ok, the gateway will request the withdraw to the banking partner and return the withdraw request confirmation to the platform. At this point, we recommend the platform to block the desired withdraw amount on the customer account (steps 5 to 8).

On steps 9 to 11, we show the situation where a baking failure occurs. In this case, the banking partner will return the withdraw failure to the gateway. The gateway will then send a refund webhook to the platform. The platform will then refund the blocked amount to the customer account. This transaction will not be processed and will be marked with a failure status on our side.

On steps 12 to 14, the banking partner will return the payment confirmation to the gateway. The gateway will then send a successfull withdraw webhook to the platform. The platform will then withdraw the blocked amount from the customer account.

Transaction Events

PIX transactions use the same schema as other transaction types in the system. The key difference is that the PIX-specific fields are populated, and the TransactionEvent types correspond to the following transaction statuses: