POST/api/partner/payments

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.

201 Created
{
  "success": true,
  "message": "Payment sent",
  "result": {
    "invoice": {
      "id": "3b9d…",
      "amount": 250
    }
  }
}

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.