🇧🇷 PIX

Overview

PIX is Brazil’s instant A2A (account-to-account) payment system, developed and operated by the Central Bank of Brazil. It allows individuals and businesses to send and receive funds instantly, 24/7 — including weekends and holidays — using only a simple identifier such as CPF, phone number, email, or random key.

With Orkestra, you can easily initiate PIX payouts via a unified API by providing a few mandatory fields. Funds are settled in seconds and status updates are delivered asynchronously via webhook.

📝 Minimum Required Fields for PIX Payouts

Field	Type	Description
`amount`	Decimal	Amount to be sent in BRL.
`currency`	String	Must be `"BRL"`.
`paymentMethod`	String	Must be `"PIX"`.
`receivingBankAccount.key`	String	PIX key (CPF/CNPJ, email, phone, or EVP/random).
`receivingBankAccount.document`	String	CPF or CNPJ associated with the PIX key.
`receivingBankAccount.documentType`	String	`"CPF"` or `"CNPJ"`.
`beneficiary.firstName`	String	Beneficiary's first name or legal name.
`beneficiary.lastName`	String	Beneficiary's last name or business suffix.
`beneficiary.type`	String	`"INDIVIDUAL"` or `"BUSINESS"`.
`beneficiary.document`	String	Same CPF or CNPJ provided in the receiving bank account.
`beneficiary.documentType`	String	`"CPF"` or `"CNPJ"`.

Optional Fields

Field	Type	Description
`referenceId`	String	Custom reference for idempotency.
`beneficiary.emailAddress`	String	Optional contact email.
`beneficiary.phoneNumber`	String	Optional phone in E.164 format.
`beneficiary.gender`	String	`"M"` or `"F"` (if available).
`beneficiary.birthdate`	String	Format: `YYYY-MM-DD`.
`beneficiary.livingAddress`	Object	Optional address fields.

📦 Example: PIX Payout Request

{
  "amount": 1.0,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "receivingBankAccount": {
    "key": "00000000000",
    "document": "00000000000",
    "documentType": "CPF"
  },
  "beneficiary": {
    "firstName": "Chopin",
    "lastName": "Pagamentos LTDA",
    "type": "BUSINESS",
    "document": "00000000000",
    "documentType": "CPF"
  }
}

🔁 Payout Flow Overview

You send the PIX payout request to Orkestra.
Orkestra validates the PIX key and beneficiary data.
The transfer is sent in real-time via Brazil’s PIX infrastructure.
You receive status updates via webhooks or polling the GET /payouts/{id} endpoint.

📦 Example: PIX Payout Response

{
  "id": 29189,
  "paymentMethod": "PIX",
  "amount": 1.0,
  "currency": "BRL",
  "status": "PENDING",
  "beneficiary": {
    "firstName": "Chopin",
    "lastName": "Pagamentos LTDA",
    "document": "00000000000",
    "documentType": "CPF",
    "gender": null,
    "birthdate": null,
    "emailAddress": null,
    "phoneNumber": null,
  },
  "processedAt": null,
  "createdAt": "2025-10-17T15:28:07.205Z",
  "updatedAt": "2025-10-17T15:28:07.205Z"
}

🚨 Notes

Make sure the document field matches the PIX key’s owner, or the payout may be rejected.
CPF/CNPJ must be valid and active in the PIX directory of the Central Bank.
PIX payouts operate 24/7 with instant confirmation.
A PENDING status typically clears in seconds unless delayed by banking validations.

✅ Summary

To initiate a PIX payout:

Set paymentMethod to "PIX".
Provide a valid PIX key and its associated document.
Define a beneficiary with consistent data.
Receive real-time feedback via API or webhook.

Orkestra’s PIX integration gives your business instant access to one of the fastest-growing payment rails in the world — fast, secure, and always available.