background

Transaction reservations

Tags:transactionsreservationsreservepre-authoriseapirisk rulesmetered billingtransactiereserveringfacturatie

A reservation pre-authorises a payment against a signed mandate before the actual collection is submitted to the bank. When you create a reservation, Twikey evaluates the mandate against your configured risk rules immediately — so you know the collection will be accepted before you commit to it.

Reservations are useful when the final transaction amount is not yet known at the time of authorisation. Common use cases include:

  • Metered billing — reserve upfront, then collect the actual usage amount later.
  • Top-up flows — guarantee a customer's wallet can be topped up before triggering the debit.
  • Multi-step checkout — validate a mandate and lock funds during a checkout process.

Behaviour by collection type

Reservations work for both SEPA Direct Debit (SDD) and Recurring Credit Card (RCC) mandates, but what happens at the payment network level differs:

  • RCC — A hold is placed on the cardholder's card via the PSP. The funds are ring-fenced until you capture or the reservation expires.
  • SDD — A database-only reservation is created (risk-rule check and amount lock only). No hold is placed at the bank.

For the full RCC authorize & capture lifecycle — including Strong Customer Authentication (SCA), capture, cancel, and expiry edge cases — see Authorize and capture.

Reservations are an API-only feature. They cannot be created from the Twikey dashboard.

How reservations work

  1. You create a reservation via the API. Twikey evaluates the mandate against your risk rules and returns a reservation code valid for 24 hours (or until the expiration date you specify).
  2. When you are ready to collect, you create a transaction using the reservation code. The collected amount must be equal to or less than the reserved amount.
  3. If you no longer need the reservation, you delete it explicitly via the API — or replace it in one step when creating a new reservation for the same mandate.

Creating a reservation

Send a standard transaction request to the API with the additional reservation=true parameter.

Two optional parameters control how the reservation interacts with your risk rules:

  • reservationMinimum — Only create the reservation if at least this amount is still available under the mandate's risk rules. If less than the minimum remains, the request fails. If more remains, the maximum available amount is reserved. This prevents you from receiving a partial reservation below a meaningful threshold.
  • reservationExpiration — A date after which the reservation automatically becomes void. If not set, the reservation expires after 24 hours.

For the full API reference, see Twikey API — Transaction Reservations.

Converting a reservation to a transaction

When you are ready to collect, create a transaction as normal and include the X-RESERVATION header with the reservation code. The amount you collect can be equal to or less than the reserved amount.

Once converted, the reservation is consumed. If the collection fails, you will need to create a new reservation before retrying.

Deleting a reservation

You can delete a reservation in two ways:

  • Explicitly — call the delete endpoint on the reservation via the API.
  • Replace in one step — create a new reservation for the same mandate with force=true. This atomically deletes the existing reservation and creates a new one.

Risk rule interaction

Reservations count against the open reservation total tracked by your risk rules. If a risk rule limits the total amount of open reservations on a mandate, the reservationMinimum parameter determines whether a partial reservation (below your configured threshold) is still acceptable.

If the request would exceed the risk rule limit entirely, the API returns an err_billing_overdrawn error.

A reservation does not guarantee collection indefinitely — it expires after 24 hours unless you set a custom `reservationExpiration` date. An expired reservation must be recreated before you can collect.
Last Update: 2026-03-16