Payments, rules and approvals

A payment sends an asset out of one of your vaults to an address. Your software asks for it with POST /v1/payments; your organisation’s payment rules decide whether it may go, whether people must agree first, or neither; and Sotirea signs it, sends it and follows it until the network has made it final.

A payment’s life

The request is answered at once, 202, with the payment as it stands. It then moves through these statuses, and GET /v1/payments/{id} or a webhook tells you where it is:

Status	Meaning
`requested`	Accepted. The amount is reserved in the vault, so it cannot be promised twice.
`awaiting_approval`	Your rules need people to agree first. `held_by` names the rule.
`awaiting_gas`	The vault’s first payment on this network, waiting while the vault’s account is created there.
`signed`	Signed and written down, about to be sent.
`sent`	On the network, with its `tx_hash`. Not final yet.
`confirmed`	Final. The vault’s balance is reduced and the reservation released.
`failed`	It did not happen, and `error` says why in words you can show a person. Any reservation is released.
`stuck`	Sent, but the network has not taken it for 15 minutes.

Five of them are also sent as webhooks: payment.awaiting_approval, payment.sent, payment.confirmed, payment.failed and payment.stuck.

New statuses may be added. Treat one you do not recognise as still in progress.

A payment that the network runs and then rejects is failed, and still pays its network fee from your gas pool, as on any network.

Ask before you send

POST /v1/payments/quote takes the same body as sending and answers what sending now would come to, with nothing sent or reserved:

outcome: allowed; needs_approval, with the rule and approvals_required; refused, by a rule, sanctions or the vault’s balance, with the rule and a reason you can show a person; or unavailable, when the network is paused or will not price it now.
fee_ceiling: the most the network fee can cost, paid from your gas pool, and gas_pool_covers: whether the pool holds that much now.

Payment rules

Payment rules are set in the console, under Payment rules, by people who can change them. Your software can read them with GET /v1/rules. A rule is one of four templates:

Template	What it does
`open`	Allows any payment the vault can afford.
`limited`	Caps a single payment (`max_per_transfer`), the total over a period (`max_per_window` within `window_seconds`), or both.
`allowlist`	Allows payments only to your approved addresses.
`dual_control`	Holds payments for approval: every payment, or those of `approval_threshold` or more, until `approvals_required` people agree.

A rule applies to the whole organisation, or to one asset on one network, and the more specific one wins. Every template can also make new addresses wait: an address your organisation has never paid must first be added to your approved addresses, and can be paid only once new_address_wait_seconds has passed, from none to 30 days.

What a refusal looks like

A payment the rules refuse is answered 403, code forbidden, with a message written for a person and fields.rule naming what refused it, so your code can handle each case without reading the words. The checks run in this order:

`fields.rule`	Why
`sanctioned_address`	The address is on a sanctions list. See sanctions screening.
`blocked_destination`	The address is on Sotirea’s blocked list.
`lookalike_destination`	The address looks like one you have paid or approved, but is not it: the same first and last characters, different in between. A common trick.
`allowlist`	Your rules allow only approved addresses, and this is not one.
`new_destination`	You have never paid this address, and your rules make new addresses wait. Approve it first.
`destination_waiting`	Approved recently, and its wait is not over. The message says when it can be paid.
`max_per_transfer`	More than one payment may move.
`max_per_window`	Would take the period’s total past its limit.

A payment that needs approval is not refused: it is accepted as awaiting_approval, with held_by set to approval_threshold.

Approvals

People approve or reject held payments in the console. An API key can never approve, and neither can the person who asked for the payment or anyone who created or gave a new secret to the key that asked for it. So software alone can never both ask for a payment and agree to it.

How many approvals a payment needs is fixed when it is requested. One rejection fails it, with the reason the person gave. A payment not approved within 24 hours fails on its own.

Approved addresses

Your organisation keeps a list of addresses it has approved, for every network or for one. GET /v1/approved-addresses lists them, and a key with the permission to manage them can add or remove one. People who manage your payment rules are emailed when one is added. An address on a sanctions list cannot be approved.

A stuck payment

A payment the network has not taken 15 minutes after it was sent, or that the network keeps refusing to accept for 15 minutes, is stuck, usually because network fees rose after it was priced. Its money stays reserved and Sotirea keeps watching it. You can:

Speed it up: send it again in its place with a higher fee, at least a quarter more or the network’s current price, whichever is higher.
Cancel it: send a payment of nothing in its place, which takes its slot so the original can never go through.

Either way the payment is sent again with the new tx_hash, and payment.sent fires again. The network decides which one goes through: if the original or the faster one is mined, the payment is confirmed; if the cancel is, it is failed, “cancelled before the network took it”. Both pay their fee from the gas pool, and both are refused 409 with fields.rule replace for a payment that is not stuck or already has a cancel on its way.