Skip to main content
GET
/
api
/
reserves
# List all reserves
curl "https://api.swiftpay.cx/api/reserves?limit=20" \
  -H "Authorization: Bearer mp_live_your_api_key"

# Filter by status

curl "https://api.swiftpay.cx/api/reserves?status=active&limit=50" \
 -H "Authorization: Bearer mp_live_your_api_key"

# Paginate

curl "https://api.swiftpay.cx/api/reserves?cursor=cursor_abc123" \
 -H "Authorization: Bearer mp_live_your_api_key"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "res_abc123",
        "paymentId": "sess_xyz789",
        "originalAmountInCents": 10000,
        "reserveAmountInCents": 10000,
        "reservePercentage": 10,
        "status": "active",
        "releasedAmountInCents": 0,
        "releaseAt": "2024-02-15T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "res_def456",
        "paymentId": "sess_uvw123",
        "originalAmountInCents": 5000,
        "reserveAmountInCents": 3000,
        "reservePercentage": 10,
        "status": "partially_released",
        "releasedAmountInCents": 2000,
        "releaseAt": "2024-02-10T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-10T14:20:00Z"
      }
    ],
    "nextCursor": "cursor_xyz789"
  }
}

List Reserves

Returns a paginated list of individual reserve records for your business.

Request

Authorization
string
required
Bearer token with your API key
status
string
Filter by status: active, partially_released, released, consumed
limit
integer
default:"20"
Number of results per page (1-100)
cursor
string
Pagination cursor for next page

Response

success
boolean
Whether the request was successful
data
object
# List all reserves
curl "https://api.swiftpay.cx/api/reserves?limit=20" \
  -H "Authorization: Bearer mp_live_your_api_key"

# Filter by status

curl "https://api.swiftpay.cx/api/reserves?status=active&limit=50" \
 -H "Authorization: Bearer mp_live_your_api_key"

# Paginate

curl "https://api.swiftpay.cx/api/reserves?cursor=cursor_abc123" \
 -H "Authorization: Bearer mp_live_your_api_key"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "res_abc123",
        "paymentId": "sess_xyz789",
        "originalAmountInCents": 10000,
        "reserveAmountInCents": 10000,
        "reservePercentage": 10,
        "status": "active",
        "releasedAmountInCents": 0,
        "releaseAt": "2024-02-15T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "res_def456",
        "paymentId": "sess_uvw123",
        "originalAmountInCents": 5000,
        "reserveAmountInCents": 3000,
        "reservePercentage": 10,
        "status": "partially_released",
        "releasedAmountInCents": 2000,
        "releaseAt": "2024-02-10T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-10T14:20:00Z"
      }
    ],
    "nextCursor": "cursor_xyz789"
  }
}

Reserve Statuses

StatusDescription
activeReserve is locked, awaiting release date
partially_releasedSome funds consumed by refund, remainder still locked
releasedFull amount released to available balance
consumedEntire reserve used for refund/chargeback
For a detailed explanation of the reserve lifecycle and how they affect your balance, see the Understanding Reserves guide.