Create card account reservation

Here, you will learn how to create account reservations in Tuum when card-related accounts are located within Card API.

If you are working with Tuum setup where card-related accounts are located within Tuum core, you should use the appropriate Account API endpoints instead.

Use case

In this example, we will review how to add an account reservation for a card account.

Use case data	API parameters with values
The card account ID to which the reservation is added.	...accounts/C001664282649/reservation
Reservation amount. The value is determined by the underlying business transaction. Note: The final reservation amount may differ from the amount requested if fees apply to the given transaction type. Fees are applied only if the transactionTypeCode is provided and the directionCode is OUT.	"money": { "amount": 100, "currencyCode": "EUR" },
The card ID of the card used to initiate the transaction reservation. Note: It is recommended to always provide the card ID. This is necessary to identify the correct card-level price list in cases where multiple cards are associated with the same account.	"cardId": "C001664282657"
The reservation is created by transaction RES_2 in the external system named ONLINE.	"source": { "sourceName": "ONLINE", "sourceRef": "RES_2" }
Reservation details	"details": "123 Main Street, Bratislava, SVK"
Merchant information	"merchantInfo": "Kaufland Bratislava, SVK"
Additional information related to the transaction.	"additionalInfo": "Additional info"
The code that identifies the transaction type. Note: Must be provided if fees are calculated in CMS.	"transactionTypeCode": "CARD_PUR"
Amount will be deducted from the account. Note: Fees are only charged for outgoing account reservations.	"directionCode": "OUT"
Account balance must be checked before making the reservation.	"checkBalance": true

Sample API call

To create a new account reservation, use the following endpoint:

https://card-api.sandbox.tuumplatform.com/api/v1/accounts/{accountId}/reservation

Learn more about the create card account reservation endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

JSON

{
  "money": {
    "amount": 100,
    "currencyCode": "EUR"
  },
  "cardId": "C001664282657",
  "source": {
    "sourceName": "ONLINE",
    "sourceRef": "RES_2"
  },
  "details": "123 Main Street, Bratislava, SVK",
  "merchantInfo": "Kaufland Bratislava, SVK",
  "additionalInfo": "Additional info",
  "transactionTypeCode": "CARD_PUR",
  "directionCode": "OUT",
  "checkBalance": true
}

cURL

Sample response

Below you will find the response to the API request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "reservationId": "C001664282461",
        "accountId": "C001664282649",
        "amount": 100.50,
        "currencyCode": "EUR",
        "directionCode": "OUT",
        "source": {
            "sourceName": "ONLINE",
            "sourceRef": "RES_2"
        },
        "details": "123 Main Street, Bratislava, SVK",
        "merchantInfo": "Kaufland Bratislava, SVK",
        "additionalInfo": "Additional info",
        "reservationDTime": "2025-11-03T15:00:00.438234Z"
    }
}

Result

The outcome of the API call is the complete set of reservation data, including system-generated parameters and the fee calculation result.

Parameter and value	Explanation
"reservationId": "C001664282461"	A unique identifier assigned to the newly created account reservation.
"amount": 100.50	The amount of funds reserved on the account for this transaction includes the transaction amount (100 EUR) plus the calculated fee (0.50).