Criar cobrança PIX
POST
/api/v1/bank/wallet/charge/pix/Bearer TokenCabeçalhos da requisição
| Cabeçalho | Valor | Obrigatório |
|---|---|---|
Authorization | Bearer {A55_ACCESS_TOKEN} | Sim |
Content-Type | application/json | Sim |
Idempotency-Key | UUID v4 | Recomendado |
Corpo da requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
wallet_uuid | string (UUID) | Sim | Carteira que recebe os fundos |
merchant_id | string (UUID) | Sim | Identificador do estabelecimento |
payer_name | string | Sim | Nome completo do pagador |
payer_email | string | Sim | Endereço de e-mail do pagador |
payer_tax_id | string | Sim | CPF ou CNPJ (ex.: 123.456.789-09) |
payer_cell_phone | string | Sim | Celular com código do país |
amount | number | Sim | Valor da cobrança em BRL (ex.: 100.00) |
currency | string | Sim | Deve ser BRL |
due_date | string | Sim | Data de expiração YYYY-MM-DD |
description | string | Sim | Descrição da cobrança exibida ao pagador |
webhook_url | string | Não | Substituir a URL de webhook padrão |
payer_address | object | Sim | Endereço de cobrança (street, city, state, postal_code) |
Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
charge_uuid | string | Identificador único da cobrança |
status | string | issued — aguardando o pagador escanear o QR |
pix_payload | object | Dados de pagamento PIX |
pix_payload.qr_code_base64 | string | PNG do QR code codificado em Base64 |
pix_payload.copy_paste | string | String EMV copia e cola (pix copia e cola) |
pix_payload.expiration | string | Timestamp ISO 8601 de expiração do QR code |
local_currency | number | Valor em BRL |
charge_payment_url | string | URL da página de pagamento hospedada |
Renderizando o QR code
Decodifique qr_code_base64 e exiba como uma tag <img>:
<img src="data:image/png;base64,{qr_code_base64}" alt="PIX QR Code" width="250" />
Alternativamente, exiba a string copy_paste para que o pagador possa colá-la no aplicativo do banco.
Códigos de status HTTP
| Status | Descrição |
|---|---|
| 200 | Cobrança PIX criada — QR code retornado |
| 400 | Corpo da requisição inválido ou campos obrigatórios ausentes |
| 401 | Token Bearer inválido ou expirado |
| 403 | Permissões insuficientes para esta carteira |
| 404 | Carteira não encontrada |
| 422 | Erro de validação (CPF inválido, moeda diferente de BRL) |
| 429 | Limite de requisições excedido |
| 500 | Erro interno do servidor — tente novamente com backoff exponencial |
Exemplos de código
- cURL
- Python
- Node.js
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"
}
}'
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}")
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);
}
Exemplo de resposta de erro
{
"charge_uuid": null,
"status": "error",
"message": [
{
"code": "INVALID_TAX_ID",
"source": "validation",
"description": "payer_tax_id is not a valid CPF or CNPJ"
}
]
}