Payments and refunds
Methods, attempts, retries, holds and refunds.
POST /v1/payments opens a payment. The router picks the gateway, and on a timeout or an outage fails over before the customer sees an error. GET /v1/payments/{id} shows every attempt, with the gateway, the decline reason and why it was routed there.
Which methods
GET /v1/payment_methods?amount_paise=49900 answers with what is live right now.
A declined payment
Issuer and gateway errors are retried inside the payment's budget. Fraud and anything after an OTP are not. Offer the customer another way with POST /v1/payments/{id}/retry.
Holds
POST /v1/authorisations holds, POST /v1/authorisations/{id}/capture takes all or part, POST /v1/authorisations/{id}/void releases. Real gateways do not offer holds through this API yet, so a live call answers 422 no_route; the sandbox has them.
Refunds
POST /v1/payments/{id}/refunds with amount_paise. Refunds come back on the payment, and refund.processed says when it is done.
Repeats
Send an Idempotency-Key on every POST. A repeat returns the first response. A repeat while the first is still running answers 409 idempotency_in_flight: wait and send it again with the same key.