Payments

POST /api/v2/payments/{id}/mark_paid

Mark a payment batch paid.

Mark as Paid on the payment batch (payments.mark_paid), the Paid Date written to each payment it marks. Needs the Payments module.

• Operation ID: markPaymentPaid
• Authentication: A Bearer token from a credential holding the write:post_award scope. Runs as the credential’s Administrator, and needs an Idempotency-Key header.

curl -X POST "https://your-org.backed.giving/api/v2/payments/42/mark_paid" \
  -H "Authorization: Bearer $BACKED_TOKEN" \
  -H "Idempotency-Key: 7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13" \
  -H "Content-Type: application/json" \
  -d '{"paid_date":"2026-11-09","reference":"BNZ-20261109-0042"}'

Parameters

Request body

application/json, the PaymentMarkPaid schema. Mark as Paid on a payment batch: the Paid Date and the bank reference.

{
  "paid_date": "2026-11-09",
  "reference": "BNZ-20261109-0042"
}

200 response

The batch as the mark left it.

Headers: Idempotent-Replayed.

{
  "id": 315,
  "status": "paid",
  "marked_paid_at": "2026-11-09T02:30:00.000Z",
  "paid_date": "2026-11-09",
  "reference": "BNZ-20261109-0042",
  "payment_count": 12,
  "amount_total": "182500.0"
}

400 response

idempotency_key_required: The write has no Idempotency-Key header of 1 to 255 characters. invalid_request: A query parameter is invalid, or a write’s body is not a JSON object.

{
  "error": "idempotency_key_required",
  "error_description": "A write needs an Idempotency-Key header of 1 to 255 characters"
}

{
  "error": "invalid_request",
  "error_description": "limit is invalid"
}

401 response

The token is missing, invalid, expired or revoked, of another Organisation, or API access is not Full. Ask for a new token.

Headers: WWW-Authenticate.

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

403 response

https_required: The request was sent over plain HTTP and was not processed. insufficient_scope: The credential does not hold the scope the route needs. run_as_disabled: The credential has no run-as Administrator, or that person is no longer one. forbidden: The run-as Administrator lacks the permission, or the record is outside their Data Access Rules.

Headers: WWW-Authenticate.

{
  "error": "https_required"
}

{
  "error": "insufficient_scope",
  "error_description": "This credential lacks the write:applications scope"
}

{
  "error": "run_as_disabled",
  "error_description": "This credential has no enabled run-as Administrator"
}

{
  "error": "forbidden",
  "error_description": "The run-as Administrator may not do this to this record"
}

404 response

not_found: An unknown host or path, or an id that is unknown, deleted or of another Organisation. module_disabled: The Organisation has the module this route belongs to turned off.

{
  "error": "not_found"
}

{
  "error": "module_disabled",
  "error_description": "This module is not enabled for the Organisation"
}

409 response

idempotency_in_progress: The first request with this Idempotency-Key has not finished. Nothing was written; retry after the given seconds. invalid_transition: The move is not open from where the record stands; current_status says where that is.

Headers: Retry-After.

{
  "error": "idempotency_in_progress",
  "error_description": "The first request with this Idempotency-Key has not finished. If this persists it stopped part-way: check whether the record exists before writing again with a new key"
}

{
  "error": "invalid_transition",
  "error_description": "The record cannot make this move from approved",
  "current_status": "approved"
}

413 response

The body, or the declared file, is larger than the limit that applies.

{
  "error": "payload_too_large",
  "error_description": "The request body is too large"
}

415 response

The body is not application/json, or the target does not accept the file’s content type.

{
  "error": "unsupported_media_type",
  "error_description": "The request body must be application/json"
}

422 response

idempotency_key_reused: The Idempotency-Key was used in the last 24 hours for a different method, path or body. unknown_field: The body has a property the route does not document; the first is named. validation_failed: Body values the product’s own form would refuse; fields names each.

{
  "error": "idempotency_key_reused",
  "error_description": "This Idempotency-Key was used for a different request"
}

{
  "error": "unknown_field",
  "error_description": "bank_account_number is not a writable field"
}

{
  "error": "validation_failed",
  "error_description": "Invalid fields: due_date",
  "fields": [
    "due_date"
  ]
}

429 response

A rate limit was exceeded: 120 requests a minute per credential, 30 token requests a minute per client_id.

Headers: Retry-After.

{
  "error": "rate_limited",
  "error_description": "Too many requests"
}

500 response

An unexpected server error.

{
  "error": "server_error"
}

503 response

The Organisation’s API access cannot be determined, or a dependency is unavailable. Retry after the given seconds.

Headers: Retry-After.

{
  "error": "temporarily_unavailable"
}