AdvancedMI (H2H)

Dynamic Invoice Amount Reservation (H2H)

This endpoint allows merchants and partners to reserve a guaranteed available invoice amount, even when the initially requested amount is already occupied.

The system automatically returns the exact amount (if available) or the closest alternative that is free

In some payment flows, invoice amounts must be temporarily reserved and unique. This method ensures a smooth customer experience by:

• Returning the requested amount if available

• Returning a nearby amount if the original is already booked

• Preventing duplicate invoice amounts in parallel sessions

Step-by-step usage guide

Scenario: Booking an invoice amount

1. Send a POST request to /book_cabinet with the desired amount and relevant parameters (currency, method, site ID, etc.)

2. Receive a response with:

   • The reserved amount (may be exact or adjusted)

   • The expiration time (typically 30 seconds)

3. Use this amount immediately to create an invoice via your standard invoice creation endpoint.

4. If the invoice is not created within the reservation window, the amount becomes available to others again.

Main logic

• System attempts to reserve the exact requested amount.

• If it is already taken, it tries to reserve one of 6 nearby alternatives (based on internal rules).

• The chosen amount is locked for 30 seconds (via book_cabinet).

• Only one client can reserve any specific amount at a time.

• If no options are available → 404 response.

Authentication

All requests must be signed according to Cactus H2H signature rules.

See Authentication Guide for implementation instructions.

Method

POST /book_cabinet

Request parameters

request_id	Yes	string	Unique idempotency key
merchant_id	Yes	string	Merchant ID
site_id	Yes	integer	Site ID under the merchant
site_login	Yes	string	Associated login
method	Yes	string	Payment method (card, sbp, etc.)
currency	Yes	string	Currency code (e.g. RUB)
amount	Yes	integer	Requested invoice amount
bank_name	No	string	(Optional) Target only cards of a specific bank
signature	Yes	string	H2H-compliant signature Signature

Request example

Endpoint

POST https://<your-cactus-domain>/api/book_cabinet/
Content-Type: application/json

Body

{
  "request_id": "b5d10f30-8c12-4ea3-b301-773de4a2f1c9",
  "merchant_id": "merchant_abc123",
  "site_id": 1004,
  "site_login": "myshop",
  "method": "sbp",
  "currency": "RUB",
  "amount": 9000,
  "bank_name": "Tinkoff",
  "signature": "a4f1f2e7d31a5b6a4e61dcbd9cf3aa1c"
}

✅ signature should be calculated using your secret key according to H2H signing rules

Response parameters

amount	integer	Reserved amount (either exact or adjusted)
expires_at	datetime	UTC datetime when the reservation expires

Response example

Example Response — success (exact match)

Status code: 200 OK Meaning: The requested amount was available and successfully reserved.

{
  "amount": 9000,
  "expires_at": "2025-05-20T06:54:16Z"
}

Example Response — success (alternative match)

Status code: 200 OK Meaning: The requested amount was already reserved, but an alternative amount was found and successfully booked

{
  "amount": 9020,
  "expires_at": "2025-05-20T06:54:16Z"
}

Example Response — failure (no free amounts)

Status code: 404 Not Found Meaning: The cabinet was found, but the requested and all auto-generated alternative amounts are already reserved by other sessions.

{
  "error": "All generated amounts were already booked"
}

Example Response — No eligible cards (cabinets)

Status code: 404 Not Found Meaning: No cards matched the provided method, currency, or bank filters. Cannot proceed with booking.

{
  "error": "Card not found"
}

Best practice

• Always create the invoice immediately after receiving the reserved amount

• If reservation expires → retry booking

• Avoid using hardcoded fallback values — rely on the booked amount returned by the API