Transactions
Every movement on a card is a transaction: a purchase, a refund, a transfer between your balance and the card, and each fee. You read them with the list call, and NAS also sends a webhook event as they happen.
List transactions
List card transactions takes the accountId and any filters: cardId, type, status, clientTransactionId, batchNo and a time range with startTime and endTime. Times are timestamps in milliseconds since the epoch.
curl "https://sandbox-api.nas.cards/open-api/v3/cards/transaction-list?accountId=$ACCOUNT_ID&cardId=<card-id>&status=PENDING&limit=20" \
-H "x-access-token: $ACCESS_TOKEN"
{
"code": "000000",
"message": "success",
"data": {
"total": 1,
"list": [
{
"id": "6931c160-998d-4fb5-9638-c2ec6f47094d",
"accountId": "459c8d9b-de8f-4849-9a73-c9db109568b2",
"cardId": "051a843f-4925-499c-ab07-a7650d69ce1c",
"cardTransactionId": "4bca6f28-f618-453c-b7b5-d40b3c5c56ea",
"currency": "USD",
"amount": "5",
"fee": "0",
"feeDetails": [],
"clientTransactionId": "",
"transactionDisplayId": "4645345456",
"type": 1,
"status": "PENDING",
"merchantName": "Example Store",
"mcc": "5999",
"direction": 2,
"createTime": "1756191211000",
"transactionTime": "1756191211000"
}
]
}
}
Paging works as described in Idempotency, pagination and limits.
For card funding transfers and budgets, List budget transactions lists the movements of a budget. It needs a time range of at most three months.
Types
type | Name | What it is |
|---|---|---|
0 | Credit | A refund or other credit to the card. |
1 | Consumption | A purchase. |
2 | Transfer in | Money moved from your balance onto the card. |
3 | Transfer out | Money moved from the card back to your balance. |
9 | Fee consumption | A fee charged when a purchase was authorised. |
10 | Declined fee | A fee charged for a declined purchase. |
14 | Reversal | A purchase cancelled before it cleared. |
15 | System fee | A fee charged by the programme. |
16 | Verification fee | A fee for a verification. |
direction is 1 for money coming in and 2 for money going out. fee is separate from amount: it is not included in it. feeDetails lists each fee.
Statuses
status | Meaning |
|---|---|
PENDING | In progress. |
CLOSED | Complete. |
FAIL | Failed. remark gives the reason. |
The life of a purchase
A card purchase passes three stages: authorisation, clearing and settlement.
- Authorisation. The merchant asks the card for permission. If the card approves, a consumption transaction (
type1) is created asPENDINGand you receiveCARD_TRANSACTION.CREATED. Fees for the authorisation are charged and show as their own transactions. - Clearing. The merchant asks for the money. The consumption transaction becomes
CLOSEDand you receiveCARD_TRANSACTION.UPDATED. Clearing can be for the full amount, for less than was authorised (partial clearing) or for more (over-clearing). - Settlement. The card network settles with NAS. Nothing changes for you.
An authorisation can also fail before any transaction exists, for example for an insufficient balance, a frozen card or a blocked merchant category. In that case you receive CARD_TRANSACTION.UPDATED with FAIL status, and no money is taken. A declined fee can apply.
Some merchants, such as fuel stations and restaurants, hold more than the final amount. The extra hold is released after the purchase settles.
Reversals and refunds
- A reversal cancels a purchase before it clears. The amount returns to the balance. A reversal is
type14, andrelatedCardTransactionIdlinks it to the original purchase. - A refund comes after clearing. It is a new credit (
type0) and leaves the original purchase as it was.
The authorisation fee on the original purchase is not refunded.
Reconcile
- Use your own ids. Send a unique
clientTransactionIdon every transfer and match on it. Transfers carry the id you sent. - Match on
cardTransactionId. It ties a fee or a reversal to the purchase it belongs to. A reversal also carriesrelatedCardTransactionId. - Let events drive, let the list confirm. Update your records from events as they arrive. Run the list on a schedule, for example each day over the last day, to catch any event you missed.
- Write once per
id. The same event can arrive twice. Save a transaction once by itsidand update it afterwards. - Do not trust arrival order. Use the status in the payload, and compare
createTimeortransactionTime.
Negative balances
A card or budget can go below zero, for example when a merchant takes more than was authorised or a fee lands after the money is spent. You receive CARD.BALANCE.NEGATIVE when that happens. Move money onto the card with Card transfer in to clear it.
Events
| Event | When |
|---|---|
CARD_TRANSACTION.CREATED | A card transaction was created. |
CARD_TRANSACTION.UPDATED | A transaction changed, for example it cleared or failed. |
BUDGET_TRANSACTION.CREATED | A budget transfer or budget-card fee was recorded. |
See Webhooks for the format.
Errors
| Code | HTTP status | What happened |
|---|---|---|
NB40001 | 400 | The accountId is missing. |
NB40301 | 403 | The account is not yours. |
| other | 400 | A validation message, for example a time range that is too long. |
See Errors.