Intenções de pagamento

Uma intenção de pagamento é a sua solicitação para cobrar de um cliente um valor denominado em moeda fiduciária. Ela é dona da sessão de checkout hospedado, da fatura do processador que recebe o pagamento (para pagamentos live, uma fatura na conta Bitcart da plataforma) e de todo o histórico de estados. Faturas e links de pagamento criam intenções de pagamento por baixo dos panos. Intenções de pagamento só podem ser criadas depois que a sua conta é ativada.

POST/v1/payment-intentslive · após ativação da conta

Criação

Campo	Obrigatório	Observações
store_id	sim	Uma loja da sua organização
amount	sim	String decimal com no máximo as casas decimais da moeda: "59.90"
currency	sim	EUR, USD, BRL ou GBP (a referência de liquidação)
allowed_networks	não	Não envie em pagamentos live: eles oferecem todos os ativos que a plataforma aceita, e o campo é recusado com allowed_networks_unsupported. (Apenas processamento somente de observação: um subconjunto das redes habilitadas com uma carteira ativa para a loja)
allowed_methods	não	["crypto"] (padrão; métodos fiduciários não estão disponíveis)
merchant_order_id	não	A sua referência (≤ 200 caracteres); pesquisável
description	não	Exibida ao cliente (≤ 500 caracteres)
customer.email / customer.reference	não	Dados minimizados: apenas o que você precisa para a conciliação
metadata	não	Até 20 pares chave/valor em string para uso próprio
return_url / cancel_url	não	Para onde o checkout envia o cliente depois
expires_in_seconds	não	300–86 400, padrão 3 600

A resposta inclui id, status (created), livemode, expires_at, checkout_session_id, checkout_url e processor. Para pagamentos live, processor descreve a fatura na conta Bitcart da plataforma (name: "bitcart", custodial: true, o status dela, os meios de pagamento depois que o checkout a abre e se o valor recebido foi creditado (credited) ao seu saldo); quote, payment_instructions e totals pertencem ao processamento somente de observação e ficam null.

Os valores são validados com rigor: sem sinais, sem expoentes, sem casas decimais a mais — nada é arredondado em silêncio.

Leitura

GET /v1/payment-intents/{id} retorna a intenção com:

• processor — para pagamentos live, a fatura Bitcart: status, status de exceção, meios de pagamento, o ativo e o valor pagos, os hashes das transações e se o valor foi creditado ao seu saldo.
• quote, payment_instructions e totals — apenas para processamento somente de observação: a cotação travada (veja Cotações), o endereço e o valor exato a pagar, e os valores esperado, recebido e confirmado.
• required_confirmations, detected_at, confirmed_at, resolution.
• fulfillable — true somente quando o valor esperado é final na cadeia (confirmed, overpaid ou resolvida como aceita).

Entregue somente quando fulfillable

Não entregue mercadorias porque uma transferência foi vista. detected e confirming ainda podem ser substituídas, reorganizadas ou sofrer gasto duplo. Aguarde fulfillable: true e confirme de novo com GET /v1/payment-intents/{id} antes de qualquer ação irreversível disparada por um webhook.

GET /v1/payment-intents/{id}/timeline retorna a lista append-only de transições de estado com o motivo, o autor e a evidência (ids das transferências, contagens de confirmações, id da cotação, aprovações). As transferências em si estão disponíveis em GET /v1/transactions?payment_intent_id=….

Cancelamento

POST /v1/payment-intents/{id}/cancel cancela uma intenção antes de qualquer transferência ter sido observada. Depois que uma transferência é vista, a API retorna conflict_error: o dinheiro pode já estar a caminho e a intenção precisa seguir a máquina de estados.

Resolução de estados de revisão

Alguns desfechos precisam de uma decisão humana: underpaid, overpaid, late_payment, manual_review. Registre a sua com POST /v1/payment-intents/{id}/resolve:

{ "resolution": "accepted_partial", "note": "Cliente confirmou por e-mail; enviando o pedido parcial." }

resolution	Use quando
accepted	Você aceita o pagamento como está
accepted_partial	Você aceita um pagamento a menor
accepted_overpayment	Você aceita um pagamento a maior (e trata o excedente com o cliente)
refunded_offchain	Você devolveu os fundos a partir da sua própria carteira
rejected	Você não vai honrar o pagamento

A note (≥ 10 caracteres) fica registrada na trilha de auditoria. A resolução nunca edita nem apaga evidências da cadeia — as observações e transições originais continuam intactas.

Webhooks de intenções

payment_intent.created, invoice.awaiting_payment, payment.detected, payment.confirming, payment.confirmed, payment.expired, payment.review_required, payment.reorged, payment.resolved, payment.canceled. Veja Webhooks.