TABLE OF CONTENTS
5.1. Card Authorisation Lifecycle and Webhook Relationship
- “cardId”
- “authorisationId”
- “transactionId”
5.2. Showing Reservations in the Transaction List
- Recommended flow
5.3. Capture Scenarios
- Multiple captures
- Capture without a previously observed reservation
- Reservation reversal before capture
- Refund after capture
- Late capture after expiration
5.6. Retrieve Statement for Card Captures
5.7. Card Fee process
BaaS Card Transactions — Authorisations, Reservations, Reversals, Refunds and Expiration (Beta)
This section explains how BaaS integrators should handle the card transaction lifecycle from the initial authorisation through reservation, capture, reversal, refund, or expiration.
The main integration components are:
- Card Payment Status Changed webhook — provides real-time card payment lifecycle events.
- Get Card Authorisation Details API — provides details about a card authorisation or active reservation.
- Get Account Transactions API — provides booked balance-moving transactions, including captured card transactions and refunds.
A card authorisation/reservation and a booked account transaction represent different stages of the card payment lifecycle and should not be treated as the same record.
5.1 Card Authorisation Lifecycle and Webhook Relationship
A typical card transaction follows this lifecycle:
Authorisation → Reservation → Capture → Booked Transaction
However, not every transaction follows the complete flow. A reservation may be reversed or expire without being captured, and in some cases a capture may be processed without a previously observed reservation.
The Card Payment Status Changed webhook should be used as the primary real-time source for card payment lifecycle changes.
| Event | Meaning | Integration handling |
|---|---|---|
| BaaSCard.HoldAdded | New authorisation/reservation created | Create or display Pending reservation |
| BaaSCard.HoldModified | Reserved amount changed | Update Pending reservation |
| BaaSCard.HoldDeleted | Reservation removed/reversed | Remove Pending reservation |
| BaaSCard.HoldCaptured | Card payment captured | Remove Pending reservation and show booked transaction |
| BaaSCard.HoldExpired | Reservation expired without capture | Remove Pending reservation |
| BaaSCard.Refunded | Refund/credit processed | Show as completed credit transaction |
The webhook payload contains the identifiers required to link the lifecycle events to the relevant BaaS APIs:
{
"cardId": "563a53ac-c681-4eaa-924b-680dea6d6e27",
"transactionId": "25559a5b-e5ff-4340-a2f3-5bc510687396",
"authorisationId": "50bc86d2-e5c7-44af-b675-f27153ff9003"
}“cardId”
Identifies the card related to the event. It can be used by the partner backend to associate the event with the correct cardholder and account.
“authorisationId”
Identifies the card authorisation/reservation.
Use this identifier with Get Card Authorisation Details:
GET baas/ob/cards/{cardId}/authorisation/{authorisationId}The endpoint returns the financial and merchant details required to represent the reservation.
Example:
{
"authorisationId": "019bd668-23f6-7968-9e9f-6d8b7f39bca4",
"cardId": "6ee0305e-aeeb-44f6-a831-b2a9a492e6dc",
"authorisationStatus": "Reserved",
"authorisationDate": "2026-01-19T13:18:27.000Z",
"lastEventDate": "2026-01-19T13:18:28.000Z",
"authorisationAmount": {
"amount": 4.55,
"currency": "EUR"
},
"originalCurrency": "EUR",
"merchant": {
"address": {},
"name": "ModifyHold",
"categoryCode": "5411"
},
"creditDebitIndicator": "Debit",
"debtorName": "Johan Snow",
"debtorAccount": {
"iban": "LT643740010000035381"
},
"cardEventType": "Authorization",
"authorisationGroup": "Other",
"authorisationType": "AutomatedFuelDispenser"
}For a Pending transaction view, partners can use fields such as the authorisation date, amount, currency, merchant information, and debit/credit indicator.
“transactionId”
Identifies the related booked card transaction.
The value is returned as a standard UUID.
For captured transactions, use transactionId to locate the corresponding transaction returned by Get Account Transactions:
webhook.transactionId = accountTransaction.entryReferenceThe relationship can therefore be summarized as:
authorisationId
│
▼
Get Card Authorisation Details
│
▼
Reservation / Authorisation
transactionId
│
▼
Get Account Transactions
│
▼
Booked Transaction
5.2 Showing Reservations in the Transaction List
The Get Account Transactions API returns booked balance-moving events, including captured card payments, payments, fees, refunds, and other account transactions.
An active card reservation is different.
When an authorisation reserves funds:
- the amount is deducted from the customer’s Available Balance;
- the funds are reserved for the merchant;
- the final card transaction may not yet be booked.
As a result, the customer’s Available Balance may already be reduced while the corresponding transaction is not yet returned in the regular account transaction list.
To provide a complete customer experience, partners should maintain active card reservations based on the Card Payment Status Changed webhook and combine them with booked transactions in their own transaction view.
Recommended flow
When BaaSCard.HoldAdded is received:
- Store the reservation using authorisationId.
- Use cardId and authorisationId to call Get Card Authorisation Details.
- Display the reservation as Pending.
When BaaSCard.HoldModified is received:
- Find the existing reservation using authorisationId.
- Retrieve or update the latest authorisation details.
- Update the existing Pending item.
A modified hold should remain one reservation. It should not be shown as a second transaction.
Example:
HoldAdded
EUR 50 Pending
│
▼
HoldModified
EUR 65 PendingWhen one of the following events is received:
BaaSCard.HoldDeleted
BaaSCard.HoldCaptured
BaaSCard.HoldExpiredthe reservation is no longer active and should be removed from the Pending view.
The customer-facing transaction list can therefore combine:
Transaction List
│
┌───────────┴───────────┐
│ │
▼ ▼
Active Reservations Booked Transactions
│ │
Webhook + Authorisation Get Account Transactions
Details API API
│ │
▼ ▼
Pending Completed
Example:
Today
Coffee Shop -4.55 EUR Pending
Hotel -150.00 EUR Pending
Salary +2,500.00 EUR Completed
Supermarket -32.40 EUR Completed
Pending is a presentation-layer state maintained by the partner.
When a reservation is captured, the Pending record should be removed and replaced by the corresponding booked transaction:
Pending Reservation
authorisationId = A1
│
│ HoldCaptured
▼
Remove Pending Reservation
│
▼
transactionId = T1
│
▼
Get Account Transactions
│
▼
entryReference = T1
│
▼
Display Completed Transaction
This prevents the same card payment from appearing twice as both Pending and Completed.
5.3 Capture Scenarios
Integrations must not assume a strict one-authorisation-to-one-transaction relationship.
Multiple captures
Multiple captures may be associated with the same authorisation.
In this scenario, the same:
authorisationIdmay be referenced by several captures, while each booked capture has its own:
transactionIdPartners should therefore use transactionId to identify individual booked transactions.
Capture without a previously observed reservation
A capture may also occur without a previously stored HoldAdded event.
For this reason, integrations must not require an active local reservation before processing BaaSCard.HoldCaptured.
If no matching reservation exists, the capture should still be processed and represented using the corresponding booked transaction from Get Account Transactions.
The same applies to a delayed capture that arrives after the original reservation has already expired.
5.4 Reversals and Refunds
A reversal and a refund are different card processes and should be handled differently.
Reservation reversal before capture
If the card payment has not entered the capture process, the merchant may reverse the authorisation.
The reserved amount is reduced to zero and the reservation is terminated.
Webhook event:
BaaSCard.HoldDeletedLifecycle:
Authorisation
│
▼
Reservation
│
│ Merchant reversal
▼
HoldDeleted
│
▼
Reservation terminated
│
▼
Reserved funds released
When HoldDeleted is received, the partner should:
- Find the active reservation using authorisationId.
- Remove it from the Pending transaction view.
- Do not create a completed refund transaction.
A reversal releases previously reserved funds. It does not represent a new balance-moving credit.
Refund after capture
Once the original card transaction has been captured, returning funds requires a refund rather than removal of the original reservation.
A refund is a separate card event in the opposite financial direction.
Example:
Original purchase
Customer → Merchant
-100 EUR
Refund
Merchant → Customer
+100 EUR
Webhook event:
BaaSCard.RefundedA refund should:
- not be added to the Pending reservations store;
- not be treated as a reservation reversal;
- be displayed as a completed credit transaction;
- be handled through the regular booked transaction flow.
According to the current integration behaviour, refunds do not provide a linking identifier to the original captured card transaction.
Partners should therefore not assume that an originalTransactionId or equivalent relationship will be available.
Refunds should be represented as separate balance-moving events based on the information returned for the refund transaction.
This is the example of Such Authorisation details:
TBA ????????????5.5 Authorisation Expiration
If the merchant neither captures the card transaction nor sends an authorisation reversal, the reservation can eventually expire automatically.
Webhook event:
BaaSCard.HoldExpiredLifecycle:
Authorisation
│
▼
Reservation
│
│ No capture
│ No reversal
▼
Expiration
│
▼
HoldExpired
│
▼
Reserved funds released
When HoldExpired is received, the partner should:
- Find the reservation using authorisationId.
- Remove it from the Pending transaction view.
- Do not create a completed transaction from the expiration itself.
The standard expiration period documented for card authorisations is 10 calendar days.
(Special Travel & Entertainment transactions, such as hotels and car rentals, may remain reserved for a longer period. The current documentation describes these cases as allowing reservations for up to 30 calendar days. There fore such reservations can be expired, and within 30 days period generate stand-alone Capture)
Partners should therefore rely on BaaS lifecycle events instead of implementing reservation expiration exclusively with their own local timer.
A reservation should normally be removed when one of the authoritative termination events is received:
BaaSCard.HoldDeleted
BaaSCard.HoldCaptured
BaaSCard.HoldExpiredLate capture after expiration
Expiration of a reservation does not necessarily mean that the merchant can never subsequently submit a capture.
A delayed capture can arrive after the reserved funds have already been released.
Example:
Day 1
Authorisation → EUR 100 reserved
Day 10
Reservation expires → EUR 100 released
Later
Merchant submits delayed capture
→ Card transaction is booked against the account balanceThe integration must therefore process a valid capture even when the corresponding reservation is no longer active locally.
Integration Summary
The main integration rules are:
- Use authorisationId to manage the reservation lifecycle and retrieve authorisation details.
- Use transactionId to identify booked card transactions by matching it to entryReference in Get Account Transactions.
- Show HoldAdded and HoldModified authorisations as Pending.
- Remove Pending reservations on HoldDeleted, HoldCaptured, or HoldExpired.
- Treat HoldCaptured as the transition from Pending reservation to booked transaction.
- Treat a reversal as release of reserved funds, not as a refund.
- Treat a refund as a separate completed credit transaction.
- Support multiple captures for one authorisationId.
- Support captures without a previously stored reservation.
- Use BaaS lifecycle events as the authoritative source for reservation state.
5.6. Retrieve Statement for Card Captures:
All Balance moving events are listed in single BAAS API: Get Account Transactions
This API returns all types of balance moving events, including Payments, Card transaction, Fees, and Other. API description
5.7 Card Fee process
Fees Are managed via Initiate Fee PAyment API