PIX com pagamento de conta

Referência: referência da API.

Quando o PIX é confirmado, o Pagaki paga um boleto ou uma guia com o saldo da mesma conta do gateway (no MVP, o Asaas). Serve, por exemplo, para o contribuinte pagar a guia do IPTU por PIX. Você não calcula tarifa de gateway: manda a conta e a sua taxa, e o Pagaki calcula quanto cobrar.

Como funciona

1. Você informa a conta (pay_bill) e, se quiser, a sua taxa (service_fee). Para mostrar o valor antes, chame POST /v1/payments/quote.
2. O Pagaki confere a linha digitável, escolhe o gateway, simula a conta nele e calcula o valor. O pagamento de conta nasce em waiting_payment.
3. O pagador paga o PIX (payment.paid).
4. O Pagaki confere o saldo, simula de novo, confere o valor e só então paga (bill_payment.processing). Sem saldo disponível, espera em waiting_funds.
5. Sai bill_payment.paid, ou bill_payment.failed com o motivo. Falha fica esperando a sua decisão.

A composição do valor

O Pagaki calcula o valor e devolve a composição em amount_breakdown, que você só lê.

Exemplo: guia de R$ 120,00, tarifa fixa de R$ 1,99 para receber o PIX, sem tarifa para pagar a conta, e taxa de R$ 2,00. O PIX sai por R$ 123,99.

Tarifa percentual incide sobre o total, então o Pagaki calcula "por dentro": o total é o menor valor que, tirada a tarifa, deixa a conta e a sua taxa inteiras. Item zerado não aparece.

Criar

curl -s https://api.sandbox.pagaki.com.br/v1/payments \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b7e5c1a-3d2f-4a6b-9c8d-7e6f5a4b3c2d" \
  -d '{
    "method": "pix",
    "description": "IPTU 2026, parcela 1",
    "external_id": "guia-778899",
    "payer": { "name": "Fulano de Tal", "document": "12345678909" },
    "service_fee": 200,
    "pay_bill": {
      "identification_field": "818000000012200001232021611280000000000007789009",
      "due_date": "2026-11-28",
      "description": "IPTU 2026, parcela 1"
    }
  }'

$response = $http->post('/v1/payments', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'json' => [
        'method' => 'pix',
        'external_id' => 'guia-778899',
        'payer' => ['name' => 'Fulano de Tal', 'document' => '12345678909'],
        'service_fee' => 200,
        'pay_bill' => [
            'identification_field' => '818000000012200001232021611280000000000007789009',
            'due_date' => '2026-11-28',
        ],
    ],
    'http_errors' => false,
]);

const response = await fetch(`${BASE}/v1/payments`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({
    method: 'pix',
    external_id: 'guia-778899',
    payer: { name: 'Fulano de Tal', document: '12345678909' },
    service_fee: 200,
    pay_bill: { identification_field: '818000000012200001232021611280000000000007789009', due_date: '2026-11-28' },
  }),
});

Quer mostrar o valor antes? Mande o mesmo corpo para POST /v1/payments/quote: nada é criado, e a resposta traz amount, gateway e amount_breakdown. Para criar com o mesmo valor, envie gateway e amount da cotação.

Prefere fixar o valor? Envie amount: o Pagaki confere que cobre tudo, e o que sobrar entra como service_fee. pay_bill.amount é opcional, só para conferir o valor da conta.

O objeto payment volta com amount_breakdown e bill_payment (em waiting_payment).

Situações do pagamento de conta

O bill_payment.processing traz o objeto completo; cada mudança sai como evento bill_payment.<situação>.

Decidir em failed

Nada é tentado de novo nem devolvido sozinho. O PIX continua paid, e o dinheiro fica na sua conta no gateway até você decidir.

Tentar de novo (pode trocar o boleto):

curl -s https://api.sandbox.pagaki.com.br/v1/bill_payments/bpay_01jbz4a1b2c3d4e5f6g7h8j9k0/retry \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4c3b2a19-0f8e-4d7c-b6a5-948372615f0e" \
  -d '{ "identification_field": "818300000018200001232021611280000000000007788991", "amount": 12000, "due_date": "2026-12-05" }'

$http->post('/v1/bill_payments/bpay_01jbz4a1b2c3d4e5f6g7h8j9k0/retry', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $retryKey],
    'json' => ['identification_field' => '818300000018200001232021611280000000000007788991', 'amount' => 12000, 'due_date' => '2026-12-05'],
]);

await fetch(`${BASE}/v1/bill_payments/bpay_01jbz4a1b2c3d4e5f6g7h8j9k0/retry`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': retryKey },
  body: JSON.stringify({ identification_field: '818300000018200001232021611280000000000007788991', amount: 12000, due_date: '2026-12-05' }),
});

Sem corpo, tenta o mesmo boleto. O novo amount não pode passar do valor da conta que o PIX cobriu. Cada tentativa é um pagamento novo no gateway e aparece em attempts[].

Cancelar (o dinheiro fica na sua conta no gateway; o PIX não é devolvido):

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/bill_payments/bpay_01jbz4a1b2c3d4e5f6g7h8j9k0/cancel \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"

retry só em failed; cancel em waiting_payment ou failed. Fora disso: 409 invalid_state. Os dois exigem Idempotency-Key, uma por decisão.

Regras que não mudam

• Mesma conta, sem fallback. O boleto sai da mesma instalação que recebeu o PIX.
• Nunca paga duas vezes. Resposta inconclusiva nunca é reenviada sozinha.
• O que sobra fica com você. Depois de pagar a conta, as tarifas e a sua taxa ficam na sua conta no gateway.
• No sandbox do Asaas nada compensa: todo pagamento de conta termina em failed. Ver ambientes.
• Em aberto com o Asaas: se a mesma linha digitável pode ser paga de novo depois de uma falha (asaas.md §10). O retry tenta; se o Asaas recusar, vira failed com bill_rejected.