Create PIX charge

POST/api/v1/bank/wallet/charge/pix/Bearer Token

---

Request headers

Header	Value	Required
Authorization	Bearer {A55_ACCESS_TOKEN}	Yes
Content-Type	application/json	Yes
Idempotency-Key	UUID v4	Recommended

Request body

Field	Type	Required	Description
wallet_uuid	string (UUID)	Yes	Wallet that receives the funds
merchant_id	string (UUID)	Yes	Merchant identifier
payer_name	string	Yes	Payer full name
payer_email	string	Yes	Payer email address
payer_tax_id	string	Yes	CPF or CNPJ (e.g., 123.456.789-09)
payer_cell_phone	string	Yes	Mobile phone with country code
amount	number	Yes	Charge amount in BRL (e.g., 100.00)
currency	string	Yes	Must be BRL
due_date	string	Yes	Expiration date YYYY-MM-DD
description	string	Yes	Charge description shown to the payer
webhook_url	string	No	Override default webhook URL
payer_address	object	Yes	Billing address (street, city, state, postal_code)

---

Response fields

Field	Type	Description
charge_uuid	string	Unique charge identifier
status	string	issued — waiting for payer to scan QR
pix_payload	object	PIX payment data
pix_payload.qr_code_base64	string	Base64-encoded PNG of the QR code
pix_payload.copy_paste	string	EMV copy-paste string (pix copia e cola)
pix_payload.expiration	string	QR code expiration ISO 8601 timestamp
local_currency	number	Amount in BRL
charge_payment_url	string	Hosted payment page URL

Rendering the QR code

Decode qr_code_base64 and display it as an <img> tag:

<img src="data:image/png;base64,{qr_code_base64}" alt="PIX QR Code" width="250" />

Alternatively, show the copy_paste string so the payer can paste it in their banking app.

---

HTTP status codes

Status	Description
200	PIX charge created — QR code returned
400	Invalid request body or missing required fields
401	Invalid or expired Bearer token
403	Insufficient permissions for this wallet
404	Wallet not found
422	Validation error (invalid CPF, currency not BRL)
429	Rate limit exceeded
500	Internal server error — retry with exponential backoff

---

Code examples

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/charge/pix/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "Ana Costa",
    "payer_email": "ana@example.com",
    "payer_tax_id": "111.222.333-44",
    "payer_cell_phone": "+5521977777777",
    "amount": 149.90,
    "currency": "BRL",
    "due_date": "2026-12-31",
    "description": "Order #100 — PIX",
    "webhook_url": "https://your-app.com/webhooks/a55",
    "payer_address": {
      "street": "Av. Rio Branco",
      "address_number": "200",
      "complement": "Sala 301",
      "neighborhood": "Centro",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "postal_code": "20040-002",
      "country": "BR"
    }
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/charge/pix/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
            "payer_name": "Ana Costa",
            "payer_email": "ana@example.com",
            "payer_tax_id": "111.222.333-44",
            "payer_cell_phone": "+5521977777777",
            "amount": 149.90,
            "currency": "BRL",
            "due_date": "2026-12-31",
            "description": "Order #100 — PIX",
            "webhook_url": "https://your-app.com/webhooks/a55",
            "payer_address": {
                "street": "Av. Rio Branco",
                "address_number": "200",
                "complement": "Sala 301",
                "neighborhood": "Centro",
                "city": "Rio de Janeiro",
                "state": "RJ",
                "postal_code": "20040-002",
                "country": "BR",
            },
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "660e8400-e29b-41d4-a716-446655440001",
        },
    )
    response.raise_for_status()
    charge = response.json()
    print(f"PIX Charge: {charge['charge_uuid']}")
    print(f"Copy-paste: {charge['pix_payload']['copy_paste']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/charge/pix/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "660e8400-e29b-41d4-a716-446655440001",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_id: "11111111-1111-1111-1111-111111111111",
      payer_name: "Ana Costa",
      payer_email: "ana@example.com",
      payer_tax_id: "111.222.333-44",
      payer_cell_phone: "+5521977777777",
      amount: 149.90,
      currency: "BRL",
      due_date: "2026-12-31",
      description: "Order #100 — PIX",
      webhook_url: "https://your-app.com/webhooks/a55",
      payer_address: {
        street: "Av. Rio Branco",
        address_number: "200",
        complement: "Sala 301",
        neighborhood: "Centro",
        city: "Rio de Janeiro",
        state: "RJ",
        postal_code: "20040-002",
        country: "BR",
      },
    }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const charge = await response.json();
  console.log(`PIX Charge: ${charge.charge_uuid}`);
  console.log(`Copy-paste: ${charge.pix_payload.copy_paste}`);
} catch (error) {
  console.error("PIX charge failed:", error.message);
}

---

Error response example

{
  "charge_uuid": null,
  "status": "error",
  "message": [
    {
      "code": "INVALID_TAX_ID",
      "source": "validation",
      "description": "payer_tax_id is not a valid CPF or CNPJ"
    }
  ]
}

---

Get charge →Poll PIX charge status — confirms within seconds.PIX transfer →Send a PIX payout to a key or bank account.Webhooks →Receive instant notification when PIX is paid.