Skip to main content

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"
Response GET /open-api/v3/cards/transaction-list
{
"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​

typeNameWhat it is
0CreditA refund or other credit to the card.
1ConsumptionA purchase.
2Transfer inMoney moved from your balance onto the card.
3Transfer outMoney moved from the card back to your balance.
9Fee consumptionA fee charged when a purchase was authorised.
10Declined feeA fee charged for a declined purchase.
14ReversalA purchase cancelled before it cleared.
15System feeA fee charged by the programme.
16Verification feeA 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​

statusMeaning
PENDINGIn progress.
CLOSEDComplete.
FAILFailed. remark gives the reason.

The life of a purchase​

A card purchase passes three stages: authorisation, clearing and settlement.

  1. Authorisation. The merchant asks the card for permission. If the card approves, a consumption transaction (type 1) is created as PENDING and you receive CARD_TRANSACTION.CREATED. Fees for the authorisation are charged and show as their own transactions.
  2. Clearing. The merchant asks for the money. The consumption transaction becomes CLOSED and you receive CARD_TRANSACTION.UPDATED. Clearing can be for the full amount, for less than was authorised (partial clearing) or for more (over-clearing).
  3. 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 type 14, and relatedCardTransactionId links it to the original purchase.
  • A refund comes after clearing. It is a new credit (type 0) 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 clientTransactionId on 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 carries relatedCardTransactionId.
  • 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 its id and update it afterwards.
  • Do not trust arrival order. Use the status in the payload, and compare createTime or transactionTime.

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​

EventWhen
CARD_TRANSACTION.CREATEDA card transaction was created.
CARD_TRANSACTION.UPDATEDA transaction changed, for example it cleared or failed.
BUDGET_TRANSACTION.CREATEDA budget transfer or budget-card fee was recorded.

See Webhooks for the format.

Errors​

CodeHTTP statusWhat happened
NB40001400The accountId is missing.
NB40301403The account is not yours.
other400A validation message, for example a time range that is too long.

See Errors.