Payouts to Pix

This guide details a step-by-step implementation of payouts to Pix.

Introduction

This guide explains how to use Integrated Payouts to send BRL to Pix accounts with the non-Pockyt wallet configuration.

Prerequisites

  • Merchant Account Setup: Ensure the merchant has an active Pockyt account and has been approved for BRL Pix Payouts.
  • API Credentials: Obtain the merchantNo and storeNo values from Pockyt.
  • Webhook Configuration: Set up ipnUrl to receive transaction status updates.
  • Banking Requirements: Ensure the payee has a valid Pix Key (CPF, CNPJ, Email, Phone, or Random Code).
  • Regulatory Compliance: Merchants must adhere to KYC and AML regulations. Brazilian payees typically require a valid CPF/CNPJ.

API Workflow (Sequence Diagram)


Step-by-Step Breakdown of the Payout Workflow

📘 API References for Workflow Steps

  • Step 1: Register Payee (/v3/payee/register)
  • Step 2: Submit Compliance Documents
  • Step 3: Verify Payee Status (/v3/payee/retrieve)
  • Step 4: Retrieve Bank Account Configuration (/v3/payee/account/configurations)
  • Step 5: Add Pix Account as Payout Method (/v3/payee/account/create/bank-account)
  • Step 6: Execute Payout (/v3/payouts/pay)
  • Step 7: Handle Webhook Notifications

Step 1: Register Payee

Action: The merchant registers a payee in Pockyt's system to generate a customerNo. This identifier is required for all subsequent payout steps.

Key Considerations:

  • The profileType (INDIVIDUAL or BUSINESS) determines the required fields.
  • The payee's email and governmentId must be unique.
  • The customerNo returned here is needed in Steps 5 and 6.

Step 2: Submit Compliance Documents

Action: The merchant submits identity verification documents (e.g., CPF/CNPJ proof, passport) for compliance review.

Key Considerations:

  • Payee accounts are initially set to ACTIVE upon creation. However, certain trigger events in compliance reviews may change their status to PENDING or DECLINED.
  • The merchant must verify the payee's status before initiating a payout to ensure funds are not sent to an ineligible payee.

Step 3: Verify Payee Status

Action: Query the /v3/payee/retrieve endpoint to confirm whether the payee is ACTIVE for payouts.

Key Considerations:

  • If the status is PENDING, the payee may be under additional compliance review.
  • If the status is DECLINED, additional documents may be required.
  • Payee status can change dynamically based on compliance requirements, so always check the status before payouts.

Step 4: Retrieve Bank Account Configuration

Action: Call /v3/payee/account/configurations to retrieve the required parameters for linking a payee's Pix account.

Example API Response:

[
  {
    "profileType": "INDIVIDUAL",
    "accountType": "BANK_ACCOUNT",
    "accountCurrency": "BRL",
    "accountCountry": "BR",
    "fields": [
      {
        "isRequired": true,
        "name": "pixKey",
        "label": "PIX Key",
        "maxLength": 64
      },
      {
        "isRequired": true,
        "name": "ownerDocument",
        "label": "Owner Document",
        "maxLength": 64
      },
      {
        "isRequired": true,
        "name": "pixKeyType",
        "label": "PIX Type",
        "maxLength": 20
      }
    ]
  }
]

Step 5: Add Pix Account as Payout Method

Action: Register the payee's Pix account using /v3/payee/account/create/bank-account.

Key Considerations:

  • The customerNo from Step 1 is required in this request.
  • The ownerDocument (CPF/CNPJ) and pixKey must belong to the same registered payee to avoid rejection.
  • The response returns an accountToken, which serves as the payment token for this payout method.
  • This accountToken must be included in Step 6 to execute the payout.

Example accountToken: 2010378298556879970563


Step 6: Initiate Payout Transfer

Action: Execute a payout to the payee's Pix account via /v3/payouts/pay.

Key Considerations:

  • The customerNo from Step 1 and the accountToken from Step 5 are required.
  • Ensure the amount does not exceed the merchant's available balance.
  • The invoiceId should be unique to avoid duplicate payouts.
  • The ipnUrl is critical for receiving transaction updates.
  • This API request only confirms that Pockyt received the payout request. It does not confirm that the funds have been deposited.

Step 7: Handle Webhook Notifications

Action: The webhook is triggered to notify the merchant of the final transaction status.

Purpose: The initial API response in Step 6 does not confirm that the payout has been completed. Webhook notifications indicate whether the payout is PENDING, SUCCESSFUL, or FAILED. The webhook contains the transactionNo and status.



Did this page help you?