Skip to main content
GET
/
api
/
reserves
/
:id
curl https://api.swiftpay.cx/api/reserves/res_abc123 \
  -H "Authorization: Bearer mp_live_your_api_key"
const reserveId = "res_abc123";

const response = await fetch(
   `https://api.swiftpay.cx/api/reserves/${reserveId}`,
   {
      headers: {
         Authorization: "Bearer mp_live_your_api_key",
      },
   }
);

const reserve = await response.json();

// Check if partially released
if (reserve.data.releasedAmountInCents > 0) {
   console.log(
      `$${(reserve.data.releasedAmountInCents / 100).toFixed(
         2
      )} already released`
   );
}
import requests

reserve_id = 'res_abc123'

response = requests.get(
    f'https://api.swiftpay.cx/api/reserves/{reserve_id}',
    headers={'Authorization': 'Bearer mp_live_your_api_key'}
)

reserve = response.json()
data = reserve['data']

if data['reserveAmountInCents'] < data['originalAmountInCents']:
    consumed = data['originalAmountInCents'] - data['reserveAmountInCents']
    print(f"${consumed / 100:.2f} consumed for refunds")
{
  "success": true,
  "data": {
    "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"
  }
}
{
   "success": true,
   "data": {
      "id": "res_def456",
      "paymentId": "sess_uvw123",
      "originalAmountInCents": 10000,
      "reserveAmountInCents": 3000,
      "reservePercentage": 10,
      "status": "partially_released",
      "releasedAmountInCents": 7000,
      "releaseAt": "2024-02-10T00:00:00Z",
      "releasedAt": null,
      "reservedAt": "2024-01-10T14:20:00Z"
   }
}
{
   "success": false,
   "error": {
      "type": "not_found",
      "message": "Reserve not found",
      "requestId": "req_abc123"
   }
}

Get Reserve

Retrieves the details of a specific reserve record.

Request

Authorization
string
required
Bearer token with your API key
id
string
required
The unique identifier of the reserve (e.g., res_abc123)

Response

success
boolean
Whether the request was successful
data
object
curl https://api.swiftpay.cx/api/reserves/res_abc123 \
  -H "Authorization: Bearer mp_live_your_api_key"
const reserveId = "res_abc123";

const response = await fetch(
   `https://api.swiftpay.cx/api/reserves/${reserveId}`,
   {
      headers: {
         Authorization: "Bearer mp_live_your_api_key",
      },
   }
);

const reserve = await response.json();

// Check if partially released
if (reserve.data.releasedAmountInCents > 0) {
   console.log(
      `$${(reserve.data.releasedAmountInCents / 100).toFixed(
         2
      )} already released`
   );
}
import requests

reserve_id = 'res_abc123'

response = requests.get(
    f'https://api.swiftpay.cx/api/reserves/{reserve_id}',
    headers={'Authorization': 'Bearer mp_live_your_api_key'}
)

reserve = response.json()
data = reserve['data']

if data['reserveAmountInCents'] < data['originalAmountInCents']:
    consumed = data['originalAmountInCents'] - data['reserveAmountInCents']
    print(f"${consumed / 100:.2f} consumed for refunds")
{
  "success": true,
  "data": {
    "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"
  }
}
{
   "success": true,
   "data": {
      "id": "res_def456",
      "paymentId": "sess_uvw123",
      "originalAmountInCents": 10000,
      "reserveAmountInCents": 3000,
      "reservePercentage": 10,
      "status": "partially_released",
      "releasedAmountInCents": 7000,
      "releaseAt": "2024-02-10T00:00:00Z",
      "releasedAt": null,
      "reservedAt": "2024-01-10T14:20:00Z"
   }
}
{
   "success": false,
   "error": {
      "type": "not_found",
      "message": "Reserve not found",
      "requestId": "req_abc123"
   }
}

Amount Tracking

Reserves track both original and current amounts:
FieldDescription
originalAmountInCentsAmount when reserve was created
reserveAmountInCentsRemaining amount currently held
releasedAmountInCentsAmount already released or consumed
When a refund consumes reserve funds:
  • reserveAmountInCents decreases
  • releasedAmountInCents increases
  • Status changes to partially_released or released
If reserveAmountInCents equals 0, the entire reserve was released or consumed.