Payments

A payment (pay-in) is created with POST /payments, which requires an Idempotency-Key. Amounts are integers in minor units, and currency is a separate field.

Flow

hosted (default): send the payer to checkout_url.
s2s: show next_action in your own UI.

GET /payment-methods?country=...&currency=... lists methods with limits and the fields the payer must provide (required_fields). Each method has a family: card, bank_redirect, bank_transfer, wallet, cash or deposit_reference.

next_action

next_action.type says what to show the payer.

`type`	What to do
`redirect`	Redirect the payer to `redirect_url`.
`qr`	Show the QR from `qr_payload`.
`voucher`	Show `voucher_code` and `voucher_barcode`.
`bank_transfer_details`	Show `bank_transfer` details. The payer must include `bank_transfer.reference`.
`phone_otp`	The payer confirms with a one-time code sent to their phone.
`none`	Nothing to show.

expires_at tells when the unpaid payment expires.

Statuses

Status	Meaning
`created`	The request passed checks.
`requires_action`	The payer must act: follow `next_action`.
`processing`	The payer started paying.
`succeeded`	The expected amount (or more, when no amount was expected) was received.
`partially_paid`	Less than expected was received and the deadline has not passed.
`overpaid`	More than expected was received.
`failed`	The provider rejected the payment.
`expired`	The time ran out. Not final: a late payment moves it to `succeeded`.
`canceled`	Canceled by the merchant.
`on_hold`	Paused for review.
`chargeback`	A card payment was disputed.

partially_paid and overpaid apply to transfers. chargeback applies to cards. The list of statuses is open: tolerate new values.

Transitions

From	To	Trigger
`created`	`requires_action`	The provider accepted the payment and there is a `next_action`.
`created`, `requires_action`	`processing`	The payer started to pay.
`created`, `requires_action`, `processing`	`failed`	The provider rejected it.
`requires_action`, `processing`	`expired`	The time ran out.
`created`, `requires_action`	`canceled`	`POST /payments/{id}/cancel`.
any non-final status	`on_hold`	A risk rule asked for a review. Staff then release or reject it.
any except `chargeback`	`succeeded` / `partially_paid`	Money arrived.
`partially_paid`	`succeeded` / `overpaid`	An extra payment completed or exceeded the expected amount.
`succeeded`	`chargeback`	A chargeback notice (cards).

After the deadline a partially_paid payment is closed. The amount already credited stays with the merchant; it is not returned to the payer automatically.

Money in any status

Money is recorded when it arrives, whatever the payment status; the status then follows the fact.

A payment that is expired and then paid becomes succeeded (or partially_paid). You receive payment.succeeded.
A payment that was canceled or failed and then paid goes to on_hold for manual review, because you may have already canceled the order. The decision is either to credit you or to return the money to the payer.
A duplicate receipt of the same incoming payment is ignored.

Cancel

POST /payments/{payment_id}/cancel works only while the payment is created or requires_action, otherwise 422 invalid_state. If the provider does not support cancellation, the cancel is internal and money that still arrives is handled as above.

If the provider call is uncertain

If POST /payments ends in 503 provider_unavailable, repeat it with the same Idempotency-Key to get the stored result or the current state.

Amounts

Always read amount, amount_received, fee, net_amount and refunded_amount as integers in minor units of currency. A payer’s own transfer may be less or more than amount: use amount_received.