🇧🇷 PIX

Overview

PIX is Brazil’s instant payment system operated by the Central Bank (Banco Central do Brasil). It allows real-time transfers 24/7 between bank accounts and is a widely adopted A2A payment method in Brazil.

Through Orkestra, you can create a PIX payment by specifying PIX as the payment method in the order transaction.

📝 Minimum Required Fields for PIX

When creating an Order for PIX, the following fields are mandatory:

Field	Type	Description
charges[].customer.firstName	String	Customer’s first name.
charges[].customer.lastName	String	Customer’s last name.
charges[].customer.documentType	Enum	Document type: must be CPF (individual) or CNPJ (company).
charges[].customer.document	String	Valid CPF or CNPJ number.
charges[].transactions[].paymentMethod	Enum	Must be set to PIX.

⚡ Optional PIX-specific Fields

You can customize the PIX experience using the following optional fields:

Field	Type	Description
charges[].transactions[].pix.allowsAmountChange	Boolean	Whether the customer is allowed to change the payment amount. Default is false.
charges[].transactions[].pix.expiresAt	ISO8601 Timestamp	Expiration date and time for the PIX payment. If not set, defaults to your account configuration (usually 1 hour).

📦 Example: PIX Order Request

json

{  
  "merchantOrderId": "b95e8d4c-8920-4cdd-805e-d4b9c21b619a",  
  "softDescriptor": "Piano Strings",  
  "amount": 19000,  
  "currency": "BRL",
  "allowsThirdPartyPayments": false,  
  "charges": [  
    {  
      "customer": {  
        "firstName": "Frédéric",  
        "lastName": "Chopin",  
        "documentType": "CPF",  
        "document": "53513406070"  
      },  
      "transactions": [  
        {  
          "paymentMethod": "PIX",  
          "pix": {  
            "allowsAmountChange": false,  
            "expiresAt": "2023-10-18T10:00:00.000Z"  
          }  
        }  
      ]  
    }  
  ]  
}

🔁 Payment Flow Overview

• You create an order with the payment method set to PIX.
• Orkestra will generate a PIX QR Code and a Copy-Paste Code (PIX "Copia e Cola").
• You receive these details in the transaction response.
• The customer scans the QR Code or pastes the code into their banking app.
• Payment confirmation will be notified via webhook (if configured).

🚨 Important Notes

• PIX transactions are processed in real time.
• PIX QR codes have an expiration — either defined by you via expiresAt or based on a platform default (e.g., 1 hour).
• It is recommended to validate CPF/CNPJ before submission to ensure a smooth payment experience.
• In case you wish to allow third-party payments, you will receive the actual payer's information via webhooks. Otherwise, third-party payments will be blocked, automatically refunding the payer with our third-party policy disclaimer.

📦 Example: PIX Order response

json

{
  "id": 10081,
  "merchantOrderId": "b95e8d4c-8920-4cdd-805e-d4b9c21b619a",
  "softDescriptor": "Music Sheets",
  "amount": 340,
  "allowsThirdPartyPayments": false,
  "currency": "BRL",
  "status": "PENDING",
  "metadata": {
    "value": 3
  },
  "charges": [
    {
      "id": 10081,
      "amount": 340,
      "status": "PENDING",
      "customer": {
        "firstName": "Frédéric",
        "lastName": "Chopin",
        "document": "53513406070",
        "documentType": "CPF"
      },
      "transactions": [
        {
          "id": 10081,
          "amount": 340,
          "paymentMethod": "PIX",
          "pix": {
            "qrCode": "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQAQAAAACoxAthAAAEI0lEQVR4Xu2aMZLbMAxF6XHh0kfQUXQ06Wg6io6wpYsdI3gfpNZ2ksmSzqTIAA2XEh4LAfwA6S3WbeX1wZ8tkV5LpNcS6bVEeu3fIR8Fu9g",
            "typeableLine": "00020101021226790014br.gov.bcb.pix2557brcode.bank.com/v2/6796d0badcea445484113357166d6c3a5204000053039865802BR5925Okestra Tecnologia em Pagamentos Sao Paulo62070503***6304694E",
            "url": "https://api.bank.com/v2/dynamic-brcode/6796d0badcea445484113357166d6c3a.png",
            "allowsAmountChange": false,
            "expiresAt": "2024-03-01T23:59:59.999Z"
          },
          "status": "PENDING",
          "transactionPageUrl": "https://paywall.orkestrapay.io/payment/b908e235-b1d8-467a-b112-0df550a266d1"
        }
      ]
    }
  ]
}

🛡️ Relevant Fields in the Response

Field	Type	Description
charges[].transactions[].pix.qrCode	Base64 String	PIX QR Code (Base64-encoded image).
charges[].transactions[].pix.typeableLine	String	PIX Copia e Cola (Typeable line for manual entry).
charges[].transactions[].pix.url	String (URL)	Direct link to the QR Code image.
charges[].transactions[].transactionPageUrl	String (URL)	Hosted payment page URL (optional use — iframe or redirect).
status	Enum	Order status: PENDING, FAILED.

✅ Summary

To create a PIX payment, ensure:

• You have customer name and document information.
• You set the paymentMethod field to PIX.
• Optionally, configure if you allow receiving a different amount and the QR code expiration.

Orkestra handles the rest — providing you with a ready-to-use PIX QR code for your customer.