Checkout hospedado

Toda intenção de pagamento vem com um checkout hospedado na checkout_url, servido a partir de https://checkout.feitpay.com. O checkout é rápido, não tem efeitos 3D e funciona sem animações; ele mostra o nome e o logo do lojista apenas a partir da identidade visual sanitizada da sua loja, junto com sinais de verificação de domínio, e informa ao cliente com clareza quem recebe o pagamento.

As sessões de checkout existem apenas para intenções de pagamento live, por isso ficam disponíveis depois que a sua conta é ativada.

Sessões de checkout

Uma sessão de checkout é uma URL de capacidade opaca e de curta duração para uma intenção de pagamento — cs_ seguido de 32 caracteres aleatórios. O próprio id dá acesso a uma visão pública sanitizada, portanto:

• nunca coloque chaves de API no navegador — o checkout nunca precisa delas;
• trate a URL como uma senha para aquele pagamento (não a registre em logs públicos);
• crie uma nova sessão para uma intenção em aberto se a anterior tiver expirado.

POST/v1/checkout-sessionslive · após ativação da conta

{ "payment_intent_id": "pi_01J…" }

As sessões ficam open, complete ou expired.

O que o cliente vê

1. O valor na sua moeda e a identidade da loja.
2. Uma declaração clara de que o cliente paga para a carteira do FeitPay, com processamento pela Bitcart, e de que você é creditado quando o pagamento é confirmado (pagamentos live são em custódia).
3. Meios de pagamento — o checkout abre uma fatura na conta Bitcart da plataforma e lista, para cada ativo aceito, o valor exato calculado com a taxa de câmbio da Bitcart, o endereço e um QR code. Os botões de copiar dão retorno imediato.
4. Status em tempo real com uma linha do tempo. Server-sent events enviam as mudanças; se não estiverem disponíveis, a página faz polling a cada 3 segundos.
5. Páginas de sucesso, pendente, falha e expirado. Após a confirmação, o cliente pode voltar para a sua return_url.

O checkout nunca troca o ativo em silêncio e nunca liquida automaticamente pagamentos parciais ou atrasados — eles passam pela máquina de estados, por uma verificação de operador para qualquer crédito em custódia e pela sua decisão.

Nota

Pagamentos em cripto não são pagamentos com cartão: não há chargebacks. Reembolsos nunca são automáticos; o lojista devolve os fundos, por exemplo com um saque para um endereço informado pelo cliente.

Endpoints públicos usados pelo checkout

Eles ficam em /v1/public/ e exigem apenas o id da sessão:

Endpoint	Finalidade
GET /v1/public/checkout-sessions/{id}	Sessão sanitizada: status do pagamento, processor (status da fatura e meios de pagamento) e linha do tempo
POST /v1/public/checkout-sessions/{id}/processor-invoice	Abre a fatura na conta Bitcart da plataforma e retorna os meios de pagamento. Idempotente: chamadas posteriores retornam a mesma fatura
GET /v1/public/checkout-sessions/{id}/events	Server-sent events de status
POST /v1/public/checkout-sessions/{id}/select-option	Apenas processamento somente de observação (não usado para pagamentos nesta plataforma): escolhe network_id + asset_id, trava uma cotação e atribui um endereço
POST /v1/public/checkout-sessions/{id}/refresh-quote	Apenas processamento somente de observação: nova cotação após a expiração (mesma rede e mesmo endereço)

Você pode usar os mesmos endpoints (ou useCheckoutSession de @feitpay/react) para mostrar o status na sua própria página de pedido.

URLs de retorno e de cancelamento

return_url e cancel_url precisam ser URLs absolutas que você controla. Um redirecionamento para a return_url é uma conveniência, não uma prova de pagamento — confie sempre no webhook assinado e em fulfillable.

Links de pagamento

Um link de pagamento é uma URL reutilizável para um valor fixo — útil para faturas enviadas por e-mail, doações ou produtos simples. Cada visita cria uma nova intenção de pagamento e uma nova sessão de checkout, por isso um link só pode ser pago depois que a sua conta é ativada. Um link pertence ao ambiente em que foi criado: crie os links que você vai compartilhar depois que a sua conta for ativada.

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

{
  "store_id": "store_01J…",
  "title": "Workshop ticket",
  "amount": "120.00",
  "currency": "EUR"
}

A resposta contém a url pública, sessions_count e confirmed_count. Desative um link com PATCH /v1/payment-links/{id} e { "active": false }. Não defina allowed_networks em links para pagamentos live: as intenções criadas por eles seriam recusadas com allowed_networks_unsupported.