Integrate card transaction notifications, queries, fees and refunds without missing records or charging twice.
Card Transactions, Fees and Refunds
Purchases, settlements, reversals, refunds and fee changes all use card.transaction.updated. There is no separate card.transaction.refunded event. Subscribe by event_type, then distinguish the business activity using data.kind, data.status and data.direction.
Query after receiving a notification
- Verify the signature and deduplicate by
event_id. Persist the notification before acknowledging it. - Query
GET /v1/cards/{id}/transactions?id=ctx_...usingdata.card_id,data.idand the member'sx-on-behalf-ofheader. - Update the existing record by its
ctx_ID. Do not create another purchase or charge again for each notification. The query returns the current snapshot, including when an older event arrives late. - Delivery can be retried. Settlement and fee changes generate further notifications for the same transaction. Periodically query all pages to catch omissions.
from/tofilter transaction occurrence time, so filtering from your last synchronization time misses later updates to older transactions.
Notifications and queries share kind, status, direction, posted, settlement_status, updated_at, fee fields, and original-currency/bill fields. Notifications include card_id; queries also provide the display amount and merchant details. original_transaction_id contains a ctx_ ID only when the original transaction can be linked within the same card and merchant. Its absence does not invalidate a refund. Do not guess the link from equal amounts.
Transaction types: kind
These are the current standard types. The enumeration is open: retain and query unfamiliar values instead of dropping them. Use direction for funds movement; never hardcode it from the type name. A service-fee record can also represent a return.
| Value | Meaning |
|---|---|
auth | Purchase authorization or purchase record |
corrective_auth | Purchase adjustment |
verification | Card verification, possibly for zero amount |
void | Purchase reversal or authorization release |
refund | Merchant refund, possibly partial or without an original-transaction link |
corrective_refund | Refund adjustment |
corrective_refund_void | Refund-adjustment cancellation |
refund_reversal | Refund reversal |
recharge | Funds added to the card |
recharge_return | Card balance returned |
discard_recharge_return | Balance returned on card closure |
service_fee | Separate service-fee record |
fund_in | Funds in |
atm_inquiry | ATM balance inquiry |
atm_withdrawals | ATM withdrawal |
atm_inquiry_failed_return | ATM inquiry fee returned |
atm_withdrawals_failed_return | ATM withdrawal returned |
auth_failed_return | Failed purchase returned |
Some products preserve extension values such as purchase, authorization, reversal, authorization_reversal, or product transaction codes. Use the returned direction and posting facts. Send unknown types for review instead of treating them as purchases or income by default.
Status and direction
status | Meaning and handling |
|---|---|
pending / processing | Processing; query again |
authorized | Authorized but not yet settled; available spending capacity may be held |
succeed | Transaction processing succeeded; still distinguish principal, funding movements and fees |
failed | Transaction failed; fees may still be charged or returned separately |
void | Original transaction reversed; release the authorization hold without refunding principal that was never debited |
Status is also an open enumeration. Do not treat an unknown status as success or failure automatically.
direction is closed: debit is outgoing, credit incoming, none has no principal direction, and unknown has no confirmed direction. amount is a nonnegative integer string; its sign cannot identify funds flow.
posted=true means this transaction's principal has been posted to the zinfra card ledger. false does not mean failure: authorizations, zero-amount verifications, reversals of unposted authorizations, and funding movements posted through separate business orders may all be false. Do not infer fee collection from this field; inspect the fee fields.
settlement_status is the current settlement marker. Common values are Unsettled, Settled, an empty string and N/A. Separate service fees and funding movements may have no settlement marker. Do not label every empty marker as unsettled.
Amounts and fees
amount, bill_amount and fee amounts are integer strings in the smallest unit. For USD with scale=6, "100000" means USD 0.10. original_amount is the original decimal text and does not use that scale.
| Field | Meaning |
|---|---|
amount | Card-currency display amount: stored card movement, otherwise authorization hold; not the increment for this update |
bill_amount | Known card-currency bill amount, preferring settlement; may be omitted when unknown, with no live currency conversion |
bank_fee | Currently known cumulative bank fee, not an additional charge per notification |
bank_fee_return | Cumulative bank-fee return known on this record; may appear on a reversal/refund record |
zinfra_fee | Current zinfra fee; use the returned value instead of assuming it is always zero |
fee_paid | Current net collection in the spending-fee workflow; may decrease after a refund and is not historical gross collection |
fee_due | Current outstanding amount in the spending-fee workflow |
fee_state | none: no fee workflow; reserved: authorization stage; processing: processing; due: awaiting collection; refunding: refunding; settled: settled; review: needs review |
fee_currency / fee_scale | Fee currency and precision |
bank_fee and bank_fee_return are fee evidence; fee_paid and fee_due describe the fee workflow. They are not four charges to add together. Do not add bank_fee or zinfra_fee again to an amount that may already include fees. Query card details for its current available balance instead of reconstructing that balance by adding display amounts.
Refunds, reversals and fee returns
- Merchant refund: usually a separate
refundtransaction withdirection=credit. Deduplicate by the refund's ownctx_ID, retain the original purchase, and preserve each partial refund. - Authorization reversal: releases a hold when the authorization was never posted. Do not credit principal that was never debited. Query the original transaction state and card balance to confirm.
- Fee return: inspect
bank_fee_returnand subsequent changes to the original transaction'sfee_paid,fee_dueandfee_state. Principal and fee refunds need not have the same timing or amount. - Separate service fee: preserve
service_feerecords and their direction. Do not ignore non-authrecords or charge twice from both a separate fee record and a fee snapshot. - Top-up, withdrawal and closure return: reconcile with the corresponding order and post once. Do not also count them as purchase refunds.
Use zinfra query data to repair your local transaction projection. Keep any additional retail fees you charge customers in separate merchant records without modifying zinfra's original snapshots.