Ciclo de vida do pagamento

Há duas perguntas que importam, e as respostas são diferentes.

O cliente já pagou? É isso que decide se processa a encomenda. Leia outcome.

O dinheiro já chegou à minha wallet? Essa é a transferência para si, e acontece depois de a encomenda ser processada. Leia settlement.

Processe a encomenda com base em outcome

curl https://hub.stablezact.com/api/v1/payments/PAYMENT_UUID/status \
  -H "X-Public-Key: pk_your_public_key"

{
  "success": true,
  "payment": {
    "paymentId": "e6c1…",
    "outcome": "paid",
    "isFinal": true,
    "amount": "50.00",
    "amountReceived": "50.00",
    "currency": "USDC",
    "network": "Base",
    "transactionHash": "0x…"
  }
}

outcome tem três valores.

outcome	Significado	Processar a encomenda
pending	ainda não pago e ainda não terminado	não
paid	o dinheiro do cliente entrou	sim
failed	expirado, cancelado ou falhado	não

A regra é só esta. Processe a encomenda com paid, e nunca antes.

outcome é o mesmo seja qual for a forma como o cliente pagou. Um pagamento feito diretamente a partir de uma wallet e um pagamento feito para um endereço de depósito gerado chegam ambos a paid, por isso o seu código precisa de um ramo, não de dois.

isFinal indica se a resposta ainda pode mudar. outcome: pending com isFinal: false significa que deve continuar a aguardar.

Depois, acompanhe settlement para a sua transferência

Um pagamento passa a paid no momento em que o dinheiro do cliente entra. Fazê-lo chegar à sua wallet é um passo separado e, em raras ocasiões, é mais lento do que o próprio pagamento. É em settlement que isso se vê:

curl https://hub.stablezact.com/api/v1/payments/PAYMENT_UUID \
  -H "X-Public-Key: pk_your_public_key"

{
  "success": true,
  "payment": {
    "settlement": {
      "state": "settled",
      "message": "Paid out to your wallet."
    }
  }
}

state	Significado
pending	à espera do cliente
settling	pagamento recebido, transferência a caminho
delayed	transferência ainda em curso, com novas tentativas automáticas
settled	na sua wallet
failed	não foi possível concluir a transferência, entramos em contacto consigo

delayed não é um problema sobre o qual tenha de agir. As novas tentativas são automáticas e o dinheiro está contabilizado. failed é o único estado que exige intervenção de alguém, e somos nós que o contactamos, em vez de esperarmos que repare.

Cada estado inclui uma message escrita para pessoas, por isso pode mostrá-la no seu próprio painel sem ter de escrever o texto.

Quanto chegou: paymentState

paymentState responde a uma terceira pergunta: o que aconteceu ao dinheiro, independentemente de o pagamento ter sido bem-sucedido.

paymentState	Significado
awaiting	ainda não chegou nada
underpaid	chegou uma parte, menos do que o valor faturado
completed	chegou o montante total
overpaid_refunding	chegou mais do que o valor faturado, o excesso está a ser tratado
expired_refunding	expirou com pagamento insuficiente, o que chegou está a ser devolvido

underpaid não é uma falha. O pagamento fica aberto e é concluído se o cliente enviar a diferença, e recebe um webhook payment.underpaid quando isso acontece, que é o momento certo para avisar o cliente.

Confirmar

Webhooks, se os puder receber. É avisado, em vez de ter de perguntar. Consulte Webhooks.

Polling, caso contrário, no endpoint de estado acima.

Faça o polling a partir do seu servidor, não do navegador. Uma leitura de estado feita no navegador do cliente pode ser falsificada pelo cliente.

O callback onSuccess do SDK é disparado quando a wallet do cliente aceita a transação. Nesse momento, a transação foi difundida, não confirmada. Ainda pode falhar, ser substituída por uma transação com uma taxa mais alta ou ser descartada. Trate onSuccess como “o cliente enviou” e confirme separadamente.

Pagamentos por endereço de depósito

Alguns pagamentos são feitos para um endereço gerado para esse pagamento específico, em vez de serem enviados diretamente para a sua wallet. O dinheiro é depois reencaminhado para si.

Isto não muda nada na forma como faz a integração. outcome continua a passar a paid, e settlement continua a indicar quando a transferência chega. O passo adicional só é visível nos eventos de webhook de depósito, listados em Webhooks.

O montante que chega nem sempre é o montante pedido. Consulte Pagamentos em excesso e reembolsos.

Valores brutos de estado

status é um campo de diagnóstico que descreve o nosso progresso interno ao longo de um pagamento. Não precisa dele para a integração: outcome e settlement contêm tudo o que foi descrito acima. Está listado aqui para que possa consultar um valor visto numa resposta bruta da API, numa exportação do painel ou numa conversa com o suporte.

status	Reportado como
pending	outcome: pending
completed	outcome: paid
sweeping	outcome: paid, settlement: settling
swept	outcome: paid, settlement: settled
sweep_failed	outcome: paid, settlement: failed
expired	outcome: failed
cancelled	outcome: failed
failed	outcome: failed

Não baseie a lógica do seu código nestes valores. Descrevem a nossa mecânica de liquidação, estão sujeitos a alterações, e tudo o que precisa deles já está em outcome e settlement.