Record or collect a payment

Records a payment the customer made outside RevKeen (mode: "record"), or asks RevKeen to collect the invoice by Direct Debit (mode: "collect").

Record

Records a payment the customer made outside RevKeen, such as a bank transfer, cash or a cheque, and applies it to the invoice. RevKeen collects no money in this mode.

mode, payment_method, reference and amount_minor are all required and nothing is defaulted. A payment that covers the whole outstanding amount moves the invoice to paid; a smaller one moves it to partially_paid. An amount larger than the invoice total less what is already paid is refused.

A payment record is written for every call, and an invoice is never marked paid without one. To mark an invoice paid, use this operation: setting status to paid or partially_paid through PATCH /v2/invoices/{id} is refused.

Refused with 409, and nothing is changed, when the invoice is already paid, void, a draft, or not recordable here, or when a Direct Debit collection for it is still pending (cancel the collection first; recording a payment would let the customer be charged twice).

The recorded payment fires the same events as a payment recorded in the dashboard, including invoice.paid and payment.succeeded. Recording requires the invoice:mark_paid permission.

Collect by Direct Debit

Schedules a Direct Debit collection of the invoice's outstanding amount (the amount due) against the customer's active mandate, and returns 202. Only payment_method: "direct_debit" is accepted; card collection is not available through this operation. The amount is never taken from the request: a body with any other field, such as amount_minor, is refused with 400.

The collection is scheduled, not completed. The invoice stays unpaid and becomes paid only when the collection settles. The customer is sent the Direct Debit advance notice first; when that notice is still being delivered, collection.status is awaiting_advance_notice and the collection is submitted once delivery is confirmed.

Refused with 409, and nothing is scheduled, when the invoice is already paid, void, a draft or not collectable, when a Direct Debit collection for it is already pending (invoice_has_pending_dd_collection), when the customer has no usable Direct Debit mandate (mandate_not_usable, including more than one active mandate), or when Direct Debit is not enabled for your account (direct_debit_not_configured).

Collecting requires the direct_debit:submit_collection permission and, for an API key, the mandates:write scope as well as invoices:write. An API key is decided as the team member who issued it. Your account owners and admins are emailed whenever an API key starts a collection.

Both modes

Requires the invoices:write scope. Send an Idempotency-Key header: a replay with the same key records or schedules nothing a second time and returns the stored response. A response, including an error, is stored for the key, so use a new key to retry after a failure.

---

Related endpoints

• GET /invoices/{id}/usage-explain — Explain invoice usage charges
• GET /invoices — List invoices
• POST /invoices — Create invoice
• GET /invoices/{id} — Get invoice
• PATCH /invoices/{id} — Update invoice
• GET /invoices/{id}/pdf — Get invoice PDF link
• POST /invoices/{id}/finalize — Finalize an invoice
• POST /invoices/{id}/void — Void an invoice

Common errors

• 400 invalid_request — malformed payload or failed validation.
• 401 authentication_error — missing, invalid, expired, or revoked credential. Codes: authentication_failed, invalid_api_key, expired_api_key, api_key_revoked, session_invalid, merchant_required. Carries a WWW-Authenticate: Bearer challenge.
• 403 authorization_error — the caller is identified but the action is denied. Codes include insufficient_permissions, ip_not_allowed, merchant_mismatch, and origin_not_allowed.
• 404 resource_missing — the referenced resource does not exist or is not visible to your key.
• 409 conflict — Idempotency-Key collision with a different body, or a concurrent state-transition conflict.
• 429 rate_limit_error — code rate_limit_exceeded. Back off using the Retry-After header (whole seconds); X-RateLimit-Reset is a UNIX timestamp in seconds.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

Path Parameters

Payment details

Response Body

curl -X POST "https://api.revkeen.com/v2/invoices/11111111-1111-4111-8111-111111111111/pay" \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "record",
    "payment_method": "bank_transfer",
    "reference": "CHK-12345",
    "amount_minor": 10000
  }'

{  "data": {    "id": "f1a2b3c4-d5e6-4270-8a9b-0c1d2e3f4a21",    "customer_uuid": "c2a1e7d4-5b3f-4a8e-9d21-6f0b3e4c7a11",    "invoice_number": "INV-0042",    "total_minor": 5880,    "currency": "GBP",    "allowed_methods": [      "card"    ],    "status": "paid",    "due_date": "2026-04-16T10:00:00.000Z",    "external_source": null,    "external_type": null,    "external_id": null,    "hosted_invoice_url": "https://pay.revkeen.com/inv_example_0042",    "created_at": "2026-04-16T10:00:00.000Z",    "updated_at": "2026-04-16T10:02:00.000Z"  },  "requestId": "req_7f3a9c2e5b1d"}