PAY-IN — ciclo de vida, montantes e endereços

A verdade financeira da YooBank é o PAY-IN canónico. Hosted Checkout e webhooks são superfícies em torno desse facto.

Status canónicos

Apenas:

created
awaiting_payment
paid

Não existe status canónico expired.

No YooCheckout, expired_for_payment é só apresentação: o prazo para o pagador acabou. O registo PAY-IN não muda para expired.

Transição típica

created — intent e endereço alocados (API create, ou POST /c/{token}/start no YooCheckout).
awaiting_payment — observação activa; o pagador deve enviar o montante exacto.
paid — evidência on-chain elegível confirmada (montante exacto, a tempo, token/rede/endereço correctos).

Pagamento atrasado

Uma transferência depois do prazo não passa o PAY-IN a paid.

Não instrua o pagador a reutilizar endereço/montante expirados. Crie um checkout novo (Modelo A) ou um novo PAY-IN (Modelo C).

Montantes

Sempre string decimal ("10.50", "1.123456").
Sem vírgula, sem sinal, sem notação científica (e / E).
Sem zero à esquerda excepto o próprio 0 antes do ponto (0.5 é válido; 00.5 não).
Zero exacto é inválido.
Até 18 dígitos inteiros e 18 fraccionários no parser; o asset ainda tem de ser representável nos decimais do token (USDT 18, USDC 6).
Matching on-chain é exacto. Subpagamento e sobrepagamento não pagam o intent.

Não use float / double / number binário para lógica financeira. Em PHP use string; em JSON nunca envie 10.5 como número se o contrato pede string.

Endereço e prazo

Um endereço de depósito por PAY-IN. Não reutilize entre pagamentos.
Pague só na rede e no contrato documentados em ASSETS.md.
expires_at na criação tem de ser futuro.

Campo `reference`

No JSON público o campo chama-se reference (pedido de create, GET, LIST e payload de webhook). Internamente o domínio pode usar outro nome; o contrato HTTP é reference.