Skip to main content

Upsert payment(s)

POST 
/v1/payments

Create or update one or more payment records, with optional invoice applications. Payments are identified by the (external_source, external_payment_id) natural key — re-posting with the same pair updates the existing row.

Body shape: accepts either a single PaymentCreateRequest object OR an array of them.

  • Single object → 200 with { payment_id } on success, or 400 with { message } on validation failure.
  • Array → 200 with { results: [...] } if every payment succeeded; 207 Multi-Status with { results: [...] } if at least one failed. Each result entry is { index, external_payment_id, ok, payment_id?, error? }.

Required fields: external_payment_id, method, total_amount, currency. external_source is strongly recommended (defaults to 'UNKNOWN') since the natural key collides without it.

Lines (invoice applications):

  • If lines is omitted: existing applications are untouched.
  • If lines is provided with replace_lines = true (default): all existing applications are deleted, then the new set is inserted.
  • If lines is provided with replace_lines = false: new applications are appended; existing ones stay.
  • Every line must include a valid invoice_token (UUID). Unknown tokens fail the whole payment with 400 unknown invoice_token: ....

Auto-fill: if status is PAID / SETTLED and settled_at is omitted, the API stamps settled_at = now(). Same for RETURNED → returned_at. Pass an explicit null to opt out.

Request​

Responses​

Payment(s) created or updated — all succeeded