Ciclo de vida del pago

Hay dos preguntas que importan, y tienen respuestas distintas.

¿Ha pagado el cliente? Eso decide si completa el pedido. Lea outcome.

¿Ha llegado el dinero a mi wallet? Esa es su liquidación, y ocurre después de completar el pedido. Lea settlement.

Complete el pedido según `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 tiene tres valores.

`outcome`	Significado	Completar pedido
`pending`	todavía no está pagado y no ha terminado	no
`paid`	el dinero del cliente ha llegado	sí
`failed`	caducado, cancelado o fallido	no

Esa es toda la regla. Complete el pedido con paid, y nunca antes.

outcome es el mismo sin importar cómo haya pagado el cliente. Un pago hecho directamente desde una wallet y uno hecho a una dirección de depósito generada llegan ambos a paid, así que su código necesita una sola rama, no dos.

isFinal indica si la respuesta todavía puede cambiar. outcome: pending con isFinal: false significa que debe seguir esperando.

Después, siga `settlement` para su liquidación

Un pago pasa a paid en cuanto llega el dinero del cliente. Hacerlo llegar a su wallet es un paso aparte y, en raras ocasiones, tarda más que el propio pago. settlement es donde se refleja:

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`	esperando al cliente
`settling`	pago recibido, liquidación en camino
`delayed`	liquidación todavía en curso, se reintenta por sí sola
`settled`	en su wallet
`failed`	la liquidación no se pudo completar, nos pondremos en contacto con usted

delayed no es un problema sobre el que tenga que actuar. Se reintenta automáticamente y el dinero está contabilizado. failed es el único estado que requiere intervención, y somos nosotros quienes nos ponemos en contacto con usted, en lugar de esperar a que usted lo note.

Cada estado incluye un message redactado para una persona, así que puede mostrarlo en su propio panel sin tener que escribir el texto usted mismo.

Cuánto ha llegado: `paymentState`

paymentState responde a una tercera pregunta: qué ha pasado con el dinero, a diferencia de si el pago ha tenido éxito.

`paymentState`	Significado
`awaiting`	todavía no ha llegado nada
`underpaid`	ha llegado una parte, menos de lo facturado
`completed`	ha llegado el importe completo
`overpaid_refunding`	ha llegado más de lo facturado, el excedente se está gestionando
`expired_refunding`	caducó con pago insuficiente, lo que llegó se está devolviendo

underpaid no es un fallo. El pago sigue abierto y se completa si el cliente envía la diferencia, y usted recibe un webhook payment.underpaid cuando esto ocurre, que es el momento de avisarle.

Confirmar

Webhooks, si puede recibirlos. Se le avisa, en lugar de tener que preguntar. Consulte Webhooks.

Polling, en caso contrario, contra el endpoint de estado anterior.

Haga el polling desde su servidor, no desde el navegador. Una lectura de estado en el navegador del cliente puede ser falsificada por el propio cliente.

El callback onSuccess del SDK se dispara cuando la wallet del cliente acepta la transacción. En ese momento la transacción se ha difundido, no confirmado. Todavía puede fallar, ser reemplazada por una transacción con una comisión más alta o descartarse. Trate onSuccess como «el cliente ha enviado el pago» y confirme por separado.

Pagos con dirección de depósito

Algunos pagos se hacen a una dirección generada para ese único pago, en lugar de enviarse directamente a su wallet. Después, el dinero se le reenvía a usted.

Esto no cambia nada en su integración. outcome sigue pasando a paid, y settlement sigue indicándole cuándo llega la liquidación. El paso adicional solo es visible en los eventos de webhook de depósito, que se enumeran en Webhooks.

El importe que llega no siempre es el importe solicitado. Consulte Sobrepagos y reembolsos.

Valores de estado sin procesar

status es un campo de diagnóstico que describe nuestro progreso interno en un pago. No lo necesita para integrarse: outcome y settlement contienen todo lo anterior. Se enumera aquí para que pueda consultar un valor que vea en una respuesta de la API sin procesar, en una exportación del panel o en una conversación con soporte.

`status`	Se informa 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`

No base su lógica en estos valores. Describen nuestra mecánica de liquidación, pueden cambiar, y todo lo que necesite de ellos ya está en outcome y settlement.