Send a payment
Sends a payment from one of your users to anyone, named by email or phone. Prio finds or invites the recipient and sends the payment from the bank account or card you name.
Headers
| Header | Type | Required |
|---|---|---|
| Idempotency-Key | string | yes |
Send a new Idempotency-Key with each payment, 1 to 255 printable characters; a UUID works well. Send the same key again only when you retry that same payment.
Request body
| Field | Type | Required |
|---|---|---|
| senderId | string | yes |
| recipientEmail | string or null | no |
| recipientPhone | string or null | no |
| amount | number | yes |
| description | string | yes |
| bankAccountId | string or null | no |
| creditCardId | string or null | no |
Send recipientEmail or recipientPhone; one of the two is required.
Send bankAccountId or creditCardId; one of the two is required.
The example is abridged; the invoice carries more fields.
The amount is at most 2000; 2000 is accepted. A payment Prio could not send returns 422 with the reason in its message.
The reply's invoice can be authorized: the payment is held, not paid. See Invoices and payment states.
If you did not get a reply, read the sender's invoices (GET /api/partner/users/:userId/invoices with a startDate just before your attempt) and look for one the sender pays with the same amount and description, created since you sent it, before sending again.
Prio moves money only for a user who has accepted Prio's current Terms of Use. Until the sender 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 sender 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.
Run this example on development
Run this example on development: it sends as Clearpath, Prio’s test partner, and cannot use your key or customers.