Cartão com pagamento de conta

Referência: referência da API.

O pagador paga com cartão de crédito, à vista ou parcelado, e o Pagaki paga um boleto ou uma guia com o saldo da conta do seu provedor de cartão (no MVP, o Asaas). Serve, por exemplo, para o contribuinte parcelar o IPTU no cartão. Você não calcula tarifa de gateway e o número do cartão nunca passa por você nem pelo Pagaki: o pagador digita na página do provedor.

Antes de começar

O tenant precisa de um provedor de cartão: uma instalação ativa, escolhida na configuração do tenant, com o máximo de parcelas (max_installments, padrão 12) e a regra wait_for_settlement. Sem isso, a API responde 422 card_provider_not_configured. Por enquanto, quem faz essa configuração é a equipe do Pagaki: ela ainda não está no painel.

Toda cobrança de cartão vai para esse provedor. Não há roteamento nem fallback: se ele estiver fora do ar, você recebe o erro, e nenhum outro gateway é tentado. Trocar de provedor vale só para cobranças novas.

Como funciona

1. Para mostrar as opções ao pagador, chame POST /v1/payments/quote uma vez por número de parcelas.
2. Crie o pagamento com method=card, as parcelas fixadas e a conta em pay_bill. O pagamento de conta nasce em waiting_payment.
3. Mande o pagador para card.payment_url. Ele digita o cartão na página do provedor.
4. Todas as parcelas capturadas: sai payment.paid.
5. O Pagaki paga a conta, no momento que wait_for_settlement define.
6. Sai bill_payment.paid, ou bill_payment.failed com o motivo. Falha fica esperando a sua decisão.

Quando a conta é paga

Este é o ponto mais delicado. Capturado não é dinheiro disponível: o saldo do cartão leva cerca de 32 dias, por parcela. Financiar esse intervalo é uma decisão sua.

Com true, o Pagaki confere o prazo antes de emitir, sempre na hora, sem cache: data de expires_at + prazo × parcelas, indo para a segunda-feira se cair no fim de semana. Se passar do vencimento da conta, responde 422 settlement_after_due_date. Se o provedor não informar o prazo, 502 settlement_unavailable. Nos dois casos nada é criado.

Exemplo: prazo de 32 dias, 3 parcelas, conta vencendo em 30 dias. A última parcela compensaria em 96 dias: a API recusa.

A composição do valor

Não há juros à parte: a tarifa de cada faixa de parcelas entra no valor e é paga pelo pagador. O total depende das parcelas, por isso a cotação é por número de parcelas. A conta é paga inteira de uma vez, mesmo no parcelado.

Exemplo: guia de R$ 120,00, sem tarifa para pagar a conta, taxa de R$ 2,00, 3 parcelas com tarifa de R$ 0,49 + 3,49%. O cartão sai por R$ 126,92.

O provedor não calcula o bruto a partir do líquido. O Pagaki calcula e confere na simulação dele, de centavo em centavo, para a conta nunca ficar descoberta. Depois da captura, card.net_amount traz o líquido real e card.net_difference, a diferença contra o cotado. Negativa, ela sai da sua taxa.

Cotar

curl -s https://api.sandbox.pagaki.com.br/v1/payments/quote \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1e9f2a-4b3d-4e6f-8a1c-2d3e4f5a6b7c" \
  -d '{
    "method": "card",
    "installments": 3,
    "payer": { "name": "Fulano de Tal", "document": "12345678909" },
    "service_fee": 200,
    "pay_bill": { "identification_field": "818000000012200001232021611280000000000007789009", "due_date": "2026-12-28" }
  }'

A resposta traz amount, amount_breakdown e card, com installment_amount, net_amount e max_installments. Nada é criado e nada é reservado.

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": "card",
    "installments": 3,
    "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-12-28",
      "description": "IPTU 2026, parcela 1"
    }
  }'

$response = $http->post('/v1/payments', [
    'headers' => ['Authorization' => "Bearer {$token}", 'Idempotency-Key' => $idempotencyKey],
    'json' => [
        'method' => 'card',
        'installments' => 3,
        'external_id' => 'guia-778899',
        'payer' => ['name' => 'Fulano de Tal', 'document' => '12345678909'],
        'service_fee' => 200,
        'pay_bill' => [
            'identification_field' => '818000000012200001232021611280000000000007789009',
            'due_date' => '2026-12-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: 'card',
    installments: 3,
    external_id: 'guia-778899',
    payer: { name: 'Fulano de Tal', document: '12345678909' },
    service_fee: 200,
    pay_bill: { identification_field: '818000000012200001232021611280000000000007789009', due_date: '2026-12-28' },
  }),
});

O 201 traz o pagamento em pending, com card.payment_url. Mande o pagador para lá. A página fica aberta até expires_at, por padrão 24 h.

Valem também as recusas da conta: amount_mismatch, amount_insufficient, fees_not_configured, invalid_identification_field, bill_overdue e bill_payment_not_supported (PIX com pagamento de conta).

Depois de criar

Cartão recusado: na página do provedor o pagador pode tentar outro cartão, então o pagamento segue pending até pagar ou expirar. Em análise de risco ele também segue pending; a conta nunca sai nesse estado, e a cobrança não expira até a análise terminar.

Parcelas: o pagamento só vira paid com todas capturadas. Os avisos das parcelas podem chegar em qualquer ordem: a cada aviso o Pagaki reconsulta a cobrança inteira, e a conta sai uma vez só.

Estornar

curl -s -X POST https://api.sandbox.pagaki.com.br/v1/payments/pay_01jbz3k8q4m7v2x9c5n6p0r1st/refunds \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: 2f1e0d9c-8b7a-4f6e-9d5c-4b3a29180716"

Só estorno total, e só enquanto a conta não foi paga. A conta que ainda não saiu é cancelada antes de o Pagaki falar com o provedor, e nenhum job consegue pagá-la depois. O 202 diz que o estorno foi pedido; payment.refunded sai quando o provedor concluir.

Se a conta já foi paga, está em curso ou o envio não foi confirmado, a API responde 409 refund_blocked_by_bill_payment e nada é estornado. Devolver ao pagador depois de pagar a conta deixaria a conta paga por você: a decisão é de uma pessoa.

Chargeback

O pagador pode contestar a compra no banco dele. O pagamento continua paid, com card.chargeback, e sai payment.chargeback.

• A conta ainda não saiu: ela vai para failed com failure.code = origin_disputed e espera a sua decisão.
• A conta já saiu: ela não volta. Pelos termos do provedor, o valor é debitado da sua conta nele.
• Você venceu a disputa: card.chargeback.status = reversed e payment.chargeback_reversed. A conta que parou em failed continua lá: chame retry.
• Você perdeu: card.chargeback.status = lost e payment.refunded. A conta que parou em failed vira canceled, porque sem o dinheiro ela não pode mais sair.

A disputa é feita no painel do provedor. O prazo é de 7 a 10 dias corridos, e sem resposta vale como aceite.

Regras que não mudam

• Mesma conta, sem fallback. A conta sai da mesma instalação que recebeu o cartão.
• Nunca paga duas vezes. Webhook repetido, parcela fora de ordem ou job em dobro dão no mesmo resultado.
• Capturou menos que o cobrado? A conta não sai: vai para failed com failure.code = amount_mismatch.
• retry é decisão sua. Em failed, ele envia a conta mesmo com a disputa aberta ou antes da compensação. Depois de um estorno, a conta já é canceled e o retry responde 409 invalid_state.
• Ainda sem confirmação do Asaas: se a página autoriza o parcelamento de uma vez ou parcela a parcela, se o cartão recusado gera evento e o prazo real de compensação das parcelas. O Pagaki segue o lado seguro nos três: só considera capturado com todas as parcelas e calcula o prazo pela última.
• O domínio de retorno e o redirecionamento depois do pagamento ainda não fazem parte da API.