Visão geral
O payment intent é o objecto principal da Rivox: modelo, estados, endpoints e níveis de integração.
Nesta página
O payment_intent é o objecto principal de integração da Rivox. Representa a intenção de receber um valor e acompanha todo o ciclo de vida do pagamento. O charge é a consequência: cada tentativa de execução sobre essa intenção.
Modelo
POST /v1/payment_intents
↓
Payment Intent criado
↓
POST /v1/payment_intents/:id/confirm
↓
Payment Core
↓
Provider Registry
↓
M-Pesa · e-Mola · mKesh · Cartão (Stripe Sandbox)
↓
Charge → Ledger → Eventos → Webhookspayment_intent— o objecto financeiro que cria e confirma.charge— a tentativa de execução gerada pela confirmação. Consulta-se, não se cria.- O routing entre provedores é decidido pela Rivox e nunca é exposto na API.
Níveis de integração
| Nível | Estado | Descrição |
|---|---|---|
| Payment Intents (custom) | Disponível | Controlo total do fluxo: criar, confirmar e consultar via API. |
| Checkout Session (low-code) | Ainda não disponível na API | Página de pagamento alojada pela Rivox. Ver Roadmap. |
Um único core
Quando a Checkout Session for exposta, corre exactamente sobre este Payment Core: os mesmos objectos, os mesmos estados e os mesmos eventos.Estados
| Payment Intent | Significado |
|---|---|
requires_payment_method | Criado; aguarda confirmação com um método. |
processing | A autorização está em curso no provedor. |
succeeded | Pagamento concluído. Estado final. |
failed | Falha técnica, recusa ou expiração. Estado final. |
canceled | Cancelado antes de existir decisão. Estado final. |
| Charge | Significado |
|---|---|
pending | Pedido aceite; push enviado para o telemóvel do cliente. |
processing | O provedor está a processar a autorização. |
succeeded | Cobrança concluída. Estado final. |
declined | O cliente recusou ou não autorizou. Estado final. |
failed | Falha técnica ou do provedor. Estado final. |
expired | Sem resposta dentro da janela permitida. Estado final. |
canceled | Cancelado antes de existir decisão. Estado final. |
Estados finais
Estados finais nunca mudam. Tratesucceeded como única confirmação de recebimento — nunca um 200 OK do pedido de criação.Endpoints
| Método | Endpoint | Scope |
|---|---|---|
| POST | /v1/payment_intents | payments:write |
| GET | /v1/payment_intents/:id | payments:read |
| POST | /v1/payment_intents/:id/confirm | payments:write |
| GET | /v1/payment_methods | payments:read |
| GET | /v1/charges/:id | payments:read |