Skip to main content

Card payments overview

A card payment is a single record that represents the full lifecycle of a payment made with a managed card — the initial authorization, any settlements, and any later reversal, refund, expiry, or original credit — grouped under one stable id.

Authorization and settlement used to be surfaced as separate transactions. A card payment brings them together: each scheme message in the lifecycle becomes an event on the same card payment, so you can follow a payment from authorization through to final settlement without stitching transactions together yourself.

Lifecycle​

A typical purchase moves through these stages, each recorded as an event on the card payment:

  • Authorization: when a merchant requests funds, at a point of sale or online, the system checks the card details, the available funds, and the spend controls. If the payment is approved, the system places a hold on the card for the authorization amount. Funds can stay on hold for up to 30 days. Online payments may require strong customer authentication.
  • Settlement: when the merchant confirms the payment, the held funds are deducted from the card and sent to the merchant. A payment can settle in a single message or in several.
  • Reversal, refund, and original credit: a hold can be reversed by a merchant void, an expiry, or an explicit cancellation; a settled payment can be refunded; and a card can receive a pushed credit, known as an original credit transaction. Each is recorded as a further event on the card payment.

Status​

The status field reflects where the payment is in that lifecycle:

StatusMeaning
SETTLEMENT_IN_PROGRESSAuthorised, but not yet — or not fully — settled. The hold is still on the card.
SETTLEDFully settled. Funds have moved to the merchant.
DECLINEDThe authorization was declined.
CANCELLEDThe authorization was cancelled or voided before it settled.
EXPIREDThe authorization hold expired before the payment settled.

Type​

The type field is the high-level kind of card payment, derived from its first event:

TypeDescription
PURCHASEA standard purchase at a merchant.
REFUNDA refund from a merchant.
ORIGINAL_CREDITA pushed credit to the card.
ACCOUNT_FUNDINGAn account funding payment.
CASH_WITHDRAWALA cash withdrawal, for example at an ATM.
BALANCE_INQUIRYA balance inquiry.

Strong customer authentication​

To protect against fraud, when a card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. makes an online payment they may need to complete an extra verification step before the authorization proceeds. This is commonly referred to as 3D Secure. See our 3D Secure guide for how to configure it for your app and your customers' cards.

Webhooks​

For near-real-time notifications as a payment progresses, subscribe to the card authorization and settlement webhooks. Anything delivered by webhook is also retrievable through the card payments endpoints, so there are no channel-specific gaps.

How card payments relate to statements and transaction activity​

  • Once a card payment has settled, it appears as a single entry in the account statement or card statement, with a transaction.type of card_payments. Pending authorizations don't appear in statements.
  • The card payment events feed is the card-level view of transaction activity: every scheme message in a payment's lifecycle, including the pending ones a statement omits.

Working with card payments​