> This is the Markdown of https://backed.giving/developers/reference/payments, a page of the Backed developer documentation. Every page is listed at https://backed.giving/developers/llms.txt.
# Payments
Payment batches. 1 operation: parameters, request body and answers, with examples.
- [POST /api/v2/payments/{id}/mark\_paid](#markPaymentPaid) — Mark a payment batch paid.
## 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.
Example request:
```bash
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
Parameters of POST /api/v2/payments/{id}/mark_paid:
| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | `integer` | The record id. Anything but a positive integer is 404. Example: `42`. |
| `Idempotency-Key` | header | Yes | `string` | A key of 1 to 255 characters, unique per write. A retry with the same key, method, path and body within 24 hours answers the first response again (with `Idempotent-Replayed: true`) and writes nothing. Example: `7d1f0c2e-5b8a-4f3e-9c61-2a4b8e9d0f13`. |
### Request body
`application/json`, the `PaymentMarkPaid` schema. `Mark as Paid` on a payment batch: the Paid Date and the bank reference.
Fields of the PaymentMarkPaid body:
| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `paid_date` | `string` | Yes | |
| `reference` | `string` | Yes | |
Example request body:
```json
{
"paid_date": "2026-11-09",
"reference": "BNZ-20261109-0042"
}
```
### 200 response
The batch as the mark left it.
Headers: `Idempotent-Replayed`.
Fields of PaymentMarkedPaid:
| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | |
| `status` | `string` | Yes | Always `paid`. |
| `marked_paid_at` | `string` | Yes | |
| `paid_date` | `string` | Yes | |
| `reference` | `string` | Yes | |
| `payment_count` | `integer` | Yes | |
| `amount_total` | `string` | Yes | |
Example 200 response:
```json
{
"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.
Example 400 response: idempotency_key_required:
```json
{
"error": "idempotency_key_required",
"error_description": "A write needs an Idempotency-Key header of 1 to 255 characters"
}
```
Example 400 response: invalid_request:
```json
{
"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`.
Example 401 response:
```json
{
"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`.
Example 403 response: https_required:
```json
{
"error": "https_required"
}
```
Example 403 response: insufficient_scope:
```json
{
"error": "insufficient_scope",
"error_description": "This credential lacks the write:applications scope"
}
```
Example 403 response: run_as_disabled:
```json
{
"error": "run_as_disabled",
"error_description": "This credential has no enabled run-as Administrator"
}
```
Example 403 response: forbidden:
```json
{
"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.
Example 404 response: not_found:
```json
{
"error": "not_found"
}
```
Example 404 response: module_disabled:
```json
{
"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`.
Example 409 response: idempotency_in_progress:
```json
{
"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"
}
```
Example 409 response: invalid_transition:
```json
{
"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.
Example 413 response:
```json
{
"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.
Example 415 response:
```json
{
"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.
Example 422 response: idempotency_key_reused:
```json
{
"error": "idempotency_key_reused",
"error_description": "This Idempotency-Key was used for a different request"
}
```
Example 422 response: unknown_field:
```json
{
"error": "unknown_field",
"error_description": "bank_account_number is not a writable field"
}
```
Example 422 response: validation_failed:
```json
{
"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`.
Example 429 response:
```json
{
"error": "rate_limited",
"error_description": "Too many requests"
}
```
### 500 response
An unexpected server error.
Example 500 response:
```json
{
"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`.
Example 503 response:
```json
{
"error": "temporarily_unavailable"
}
```