Guia YooCheckout (Hosted Checkout)

Base pública: https://pay.yoobank.net

YooCheckout é a experiência hospedada: o merchant cria um link, o pagador paga nessa página. Destinado ao Modelo A (zero-code) e, quando útil, ao Modelo B.

Login e área merchant

Não existe auto-registo público. A conta merchant é criada pela plataforma.

Criar um checkout

Campos típicos:

• Referência — identificador do merchant (encomenda, factura). Opcional.
• Descrição — texto visível ao pagador.
• Montante — valor fixo, em string decimal (sem vírgula, sem notação científica).
• Asset / rede — só pares Ready do catálogo: USDT/BEP20 e/ou USDC/ERC20.

O backend é a autoridade. Se um par não estiver Ready, a criação é recusada (incluindo criação parcial: ou todos os pares escolhidos estão Ready, ou nenhum checkout é criado).

Após criar, copie o URL público:

https://pay.yoobank.net/c/{token}

O token em claro é mostrado uma vez. Ver [limitação conhecida](#token-publico-so-na-criacao).

Readiness (pronto a receber)

Merchant Active não basta.

O merchant não consegue criar checkout para um asset/rail que o backend considere não pronto. Razões visíveis (sem IDs internos):

Webhook não é requisito de readiness. Credencial de máquina não é requisito de YooCheckout.

Avisos no ecrã não substituem a decisão do servidor.

Fluxo do pagador

1. Abre GET /c/{token}.
2. Escolhe o método (se houver mais do que um) e inicia o pagamento.
3. Vê endereço, montante exacto, rede, token e prazo.
4. Transfere exactamente esse montante, nesse token, nessa rede, para esse endereço.
5. A página passa a “a aguardar pagamento” e depois a “pago” quando o PAY-IN canónico fica paid.

Rotas públicas do pagador:

• GET /c/{token} — página (não cria PAY-IN)
• POST /c/{token}/start — único caminho YooCheckout que materializa PAY-IN
• GET /c/{token}/status — JSON estreito para actualização da página
• GET /hosted-checkout/app.css — folha de estilos

Estados de apresentação (não são o status canónico do PAY-IN):

• select_method
• ready_to_start
• awaiting_payment
• paid
• expired_for_payment
• unavailable

expired_for_payment é só apresentação. O PAY-IN não passa a um status expired. Uma transferência atrasada não passa a paid.

paid na apresentação só é verdadeiro quando o PAY-IN canónico está paid.

Histórico e detalhe

A lista e o detalhe mostram o estado de apresentação, o status PAY-IN quando existe, o endereço de depósito e o hash da transacção confirmada quando há evidência.

Desactivar um checkout (POST /merchant/checkouts/{uuid}/disable) só se aplica a sessões open ainda não usadas. Um checkout pago não pode ser revertido.

As páginas merchant nunca alocam endereço. Só o pagador, ao iniciar, materializa o PAY-IN.

Token público só na criação

RAW_PUBLIC_TOKEN_RECOVERY_MODEL=creation_only
KNOWN_PRODUCT_LIMITATION=yes

O token público é gerado com CSPRNG e guardado apenas como hash SHA-256. Não é possível reconstruir um URL antigo a partir da base de dados. Isto é o modelo actual (hash-only), não um defeito de segurança. Recomendação futura: persistir o token de forma recuperável (cifrada) se o produto exigir reenvio do mesmo URL.

Limites de ritmo (Hosted Checkout)

Pedidos públicos (página/status/start) podem receber HTTP 429 (RATE_LIMITED) após 60 pedidos / 60 segundos por acção, IP e token.

Criação autenticada de checkout: 20 pedidos / 60 segundos por identidade.

O que o YooCheckout não faz

• Não liquida saldos nem faz payout.
• Não é PIX nem banca fiat.
• Não substitui a API PAY-IN para merchants que integram o próprio checkout (Modelo C).

API: https://api.yoobank.net · Checkout: https://pay.yoobank.net