POST/api/partner/invoices/:invoiceId/pay

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.

200 OK
{
  "success": true,
  "message": "Invoice paid",
  "result": {
    "invoice": {
      "id": "3b9d…",
      "status": "authorized"
    }
  }
}

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.