Handle Reservations

This section describes the Funds Reservation APIs used by ImPAI during instant payment processing.
Reservations ensure that sufficient funds are blocked before continuing the payment workflow, preventing overdrafts and race-conditions in high-speed processing scenarios.

The reservation module exposes two API endpoints:

Funds Reservation Request
Creates or updates a liquidity block on the debtor account. The request is forwarded to the configured reservation engine (e.g., Core Banking System).
Reservation Release
Releases a previously blocked reservation once the payment is completed, cancelled, or otherwise no longer requires reserved funds.

Both APIs follow a consistent structure and provide traceability through standardized header metadata.

1️⃣ Funds Reservation Request

This endpoint is used to create a new reservation or update an existing one during the payment lifecycle.
It is typically invoked:

before initiating an SCT Inst payment
during internal pre-check flows
when re-validating liquidity for repeated attempts
during pre-authorization procedures

The service forwards the request to the external reservation engine and returns the resulting status, including the assigned reservation identifier.

Request Structure

❶ reservationRequest

The group reservationRequest defines the reservation parameters.

Field	Type	Required	Description	Constraints
`identifiers.reservationId`	String	No	Used when updating an existing reservation	max. 36 chars
`identifiers.transactionId`	String	Yes	Id of the underlying transaction	1-36 chars
`account.accountId`	String	Yes	Debtor account to reserve funds on	1-34 chars
`account.accountType`	String	Yes	Type of the account identifier	Enum: `IBAN` `ACCOUNT_NUMBER`
`amount.value`	Number	Yes	Amount to be blocked
`amount.currency`	String	Yes	ISO-4217 currency code	3 chars
`agent.bic`	String	No	Bank identification	11 chars, BIC format
`reservationType`	String	Yes	Type of reservation	Enum: `CREDIT` `DEBIT`

Example Request:

{
  "reservationRequest": {
    "identifiers": {
      "transactionId": "PAI0500000123456"
    },
    "account": {
      "accountId": "DE22123412341234",
      "accountType": "IBAN"
    },
    "amount": {
      "value": 250.00,
      "currency": "EUR"
    },
    "reservationType": "DEBIT"
  }
}

Response Structure

🟢 Success — HTTP 200

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-05-30T10:45:31.002Z"
  },
  "reservationResponse": {
    "status": "Reserved",
    "reservationId": "RSV12345678",
    "reservationType": "DEBIT",
    "balanceDetails": {
      "coreBalance": 1234.56,
      "holdBalance": 250.00,
      "availableBalance": 984.56,
      "lastUpdatedAt": "2025-05-30T10:45:31.001Z"
    }
  }
}

🔴 Error — HTTP 400

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-05-30T10:45:31.002Z"
  },
  "reservationResponse": {
    "status": "Failed",
    "message": "The reservation request cannot be fulfilled.",
    "errors": [
      {
        "code": "amount",
        "message": "Requested amount exceeds available balance."
      }
    ]
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
`errorCode`	Application-level error identifier (e.g. `500_INTERNAL_ERROR`)
`message`	Brief description such as "Time-out" or "Something went wrong"

Example:

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

POST/api/sbl/v1/reservation/createCreate a new Funds Reservation

2️⃣ Reservation Release

This endpoint releases a previously created reservation. A release is triggered when:

the payment is successfully executed (final settlement),
the payment is cancelled or rejected,
the reservation expires,
the orchestration layer determines that the reservation is no longer required.

The service notifies the reservation engine and returns the release status.

Request Structure

The request payload for releasing a reservation is structured into the following components:

❶ header (common metadata)

Field	Type	Required	Description	Constraints
`requestId`	String	Yes	Unique client-side request identifier	1-36 chars
`entityId`	String	No	Processing entity (bank, branch, or tenant)	max.36 chars
`userId`	String	No	User or service initiating the request	max. 36 chars
`sourceSys`	String	Yes	Origin of the request (channel, orchestration component, etc.)	1-35 chars
`clientId`	String	Yes	Application/client identifier	1-36 chars
`clientIP`	String	No	Source IP address
`creationTime`	String	Yes	Request creation timestamp

❷ identifiers

The identifiers section provides references to previously created funds reservations and links the release request to the original reservation:

Field	Type	Required	Description	Constraints
`reservationId`	String	Yes	Reservation identifier to release	1-35 chars

Example Request:

{
  "header": {
    "requestId": "ReqId-419578",
    "entityId": "Im-Par",
    "userId": "user123",
    "sourceSys": "OnlineBanking",
    "clientId": "1234",
    "clientIP": "192.168.0.1",
    "creationTime": "2025-06-02T14:15:22Z",
  },
  "identifiers": {
    "reservationId": "RSV12345678"
  }
}

Response Structure

🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

Group	Description
`header`	A group containing `responseId`, `originalRequestId`, `responseTime`
`body`	An object with detailed information like the new `status` and the `reservationId` of the underlying reservation.

Example:

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-05-30T10:45:31.002Z"
  },
  "body": {
    "status": "Success",
    "reservationId": "RSV12345678",
    "message": "Funds released"
  }
}

🔴 Error — HTTP 400

{
  "header": {
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "originalRequestId": "ReqId-419578",
    "responseTime": "2025-05-30T10:45:31.002Z"
  },
  "body": {
    "status": "Failed",
    "reservationId": "RSV12345678",
    "message": "Reservation not found or already released.",
    "errors": [
      {
        "code": "reservationId",
        "message": "Not found or invalid."
      }
    ]
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
`errorCode`	Application-level error identifier (e.g. `500_INTERNAL_ERROR`)
`message`	Brief description such as "Time-out" or "Something went wrong"

Example:

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

POST/api/sbl/v1/reservation/releaseRelease a previous Funds Reservation

Summary — Handling Reservations

This page explains how to create and release fund reservations in ImPAI. Reservations ensure that sufficient liquidity is blocked before processing a payment or workflow step.

The system exposes two reservation operations:

Create / Update Reservation — blocks a specific amount on an account and returns a reservationId maintained by the external reservation engine.
Release Reservation — frees a previously created reservation when the payment is completed, cancelled, or no longer requires blocked funds.

Each Reservation operation:

uses standard ImPAI metadata headers,
communicates asynchronously with the external reservation engine,
returns technical identifiers and status information,
and provides consistent success and error response structures.

1️⃣ Funds Reservation Request​

2️⃣ Reservation Release​

Summary — Handling Reservations​

1️⃣ Funds Reservation Request

2️⃣ Reservation Release

Summary — Handling Reservations