Z Zise Developers 简体中文
Card Issuance › Guides

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

  1. Verify the signature and deduplicate by event_id. Persist the notification before acknowledging it.
  2. Query GET /v1/cards/{id}/transactions?id=ctx_... using data.card_id, data.id and the member's x-on-behalf-of header.
  3. 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.
  4. Delivery can be retried. Settlement and fee changes generate further notifications for the same transaction. Periodically query all pages to catch omissions. from / to filter 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.

ValueMeaning
authPurchase authorization or purchase record
corrective_authPurchase adjustment
verificationCard verification, possibly for zero amount
voidPurchase reversal or authorization release
refundMerchant refund, possibly partial or without an original-transaction link
corrective_refundRefund adjustment
corrective_refund_voidRefund-adjustment cancellation
refund_reversalRefund reversal
rechargeFunds added to the card
recharge_returnCard balance returned
discard_recharge_returnBalance returned on card closure
service_feeSeparate service-fee record
fund_inFunds in
atm_inquiryATM balance inquiry
atm_withdrawalsATM withdrawal
atm_inquiry_failed_returnATM inquiry fee returned
atm_withdrawals_failed_returnATM withdrawal returned
auth_failed_returnFailed 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

statusMeaning and handling
pending / processingProcessing; query again
authorizedAuthorized but not yet settled; available spending capacity may be held
succeedTransaction processing succeeded; still distinguish principal, funding movements and fees
failedTransaction failed; fees may still be charged or returned separately
voidOriginal 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.

FieldMeaning
amountCard-currency display amount: stored card movement, otherwise authorization hold; not the increment for this update
bill_amountKnown card-currency bill amount, preferring settlement; may be omitted when unknown, with no live currency conversion
bank_feeCurrently known cumulative bank fee, not an additional charge per notification
bank_fee_returnCumulative bank-fee return known on this record; may appear on a reversal/refund record
zinfra_feeCurrent zinfra fee; use the returned value instead of assuming it is always zero
fee_paidCurrent net collection in the spending-fee workflow; may decrease after a refund and is not historical gross collection
fee_dueCurrent outstanding amount in the spending-fee workflow
fee_statenone: no fee workflow; reserved: authorization stage; processing: processing; due: awaiting collection; refunding: refunding; settled: settled; review: needs review
fee_currency / fee_scaleFee 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

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.

Related endpoints