Pay an invoice
Pays an invoice one of your users owes, from the bank account or card you name. Returns the invoice as it stands after the payment: authorized while the payment is held, or paid.
Path parameters
| Field | Type | Required |
|---|---|---|
| invoiceId | string | yes |
Headers
| Header | Type | Required |
|---|---|---|
| Idempotency-Key | string | yes |
Send a new Idempotency-Key with each invoice payment, 1 to 255 printable characters; a UUID works well. Send the same key again only when you retry that same invoice payment.
Request body
| Field | Type | Required |
|---|---|---|
| clientId | string | yes |
| bankAccountId | string or null | no |
| creditCardId | string or null | no |
Send bankAccountId or creditCardId; one of the two is required.
A user who is not the payer on the invoice returns 422. Payment errors keep their own status; these are the named ones, in the body's error field.
| Error | Status | When |
|---|---|---|
| PAYMENT_CHARGE_FAILED | 400 | the bank account or card could not be charged |
| PAYMENT_PROCESSING_ERROR | 400 | the charge may still have gone through: read the invoice, and do not pay again |
| CURRENCY_MISMATCH | 400 | the payment's currency does not match the payee's payout account |
| PAYMENT_METHOD_NOT_FOUND | 404 | the bank account or card was not found |
| PAYMENT_IN_PROGRESS | 409 | a charge on this invoice may still be going through: read the invoice, and do not pay again |
| INVOICE_CANCELLED | 409 | the invoice was cancelled |
| NO_ELIGIBLE_PROVIDER | 422 | Prio could not take this payment right now |
| INVOICE_NOT_FOUND | 404 | the invoice went away while it was being paid; an unknown invoice id is a 404 whose error is Not Found |
| INVOICE_AMOUNT_CHANGED | 409 | the amount owed changed, and nothing was charged |
| INVOICE_NO_LONGER_OWED | 409 | the invoice is no longer owed, and nothing was charged |
| INVOICE_CHECK_UNAVAILABLE | 409 | Prio could not confirm the amount owed, and nothing was charged |
Prio moves money only for a user who has accepted Prio's current Terms of Use. Until the paying client has, this call returns 403 with the error TERMS_NOT_ACCEPTED and details.userId, nothing moves, and your Idempotency-Key is not used. Open the Prio window for the paying client with a data-prio-onboard button (see Add the embed), where Prio asks them to accept, then send the same call again — the same key works.
Retrying safely
If you lose the reply, send the identical call again with the same key. When the first call has finished, Prio returns its reply exactly, with the header Idempotent-Replayed: true, and does nothing else. A first call that failed is returned as that same failure.
The same key with a different request returns 422 with the error IDEMPOTENCY_KEY_REUSED, and nothing moves.
While the first call is still running, a retry returns 409 with the error IDEMPOTENCY_KEY_IN_PROGRESS and the header Retry-After: 10. Wait that many seconds, then retry.
A server restart in the middle of a call (a deploy, or the daily restart, on production too) can leave it unfinished. A retry is then told the call is still running for up to 10 minutes, and after that returns 409 with the error IDEMPOTENCY_KEY_UNRESOLVED.
Any replayed failure, and an unresolved key, is final for its key: check the user’s invoices, then send a new key if the money did not move. A key is honoured for 24 hours from its first use.