# Card payment update

Notification that a card payment (the aggregate of related authorisations,
settlements, reversals, refunds and chargebacks) has been created or updated.
The payload carries the full current state of the CardPayment, including
its event history with snapshots of running totals after each event.

Endpoint: POST /managed_cards/payments/watch
Version: v2

## Header parameters:

  - `call-ref` (string)
    A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

  - `published-timestamp` (integer, required)
    The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

  - `signature` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key.

  - `signature-v2` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `call-ref + payload + published-timestamp` using your API key.

## Request fields (application/json):

  - `eventType` (string, required)
    Type of event recorded against a CardPayment. The `reversal` flag on each event distinguishes a reversal from the original action.
    Enum: "AUTHORISATION", "SETTLEMENT", "REFUND", "ORIGINAL_CREDIT"

  - `cardPayment` (object, required)
    One card transaction's full lifecycle — authorisation, settlement, refunds — as a single resource that the platform keeps up to date as scheme events arrive.
Designed for two audiences:
- **Building UI?** Read the top-level summary fields (`displayAmount`, `status`, `type`, `merchant`, `card`). They are platform-maintained — show them as-is. No need to understand auth-vs-clearing, reversals, or scheme messages. The debit/credit direction is implicit from `type` (purchases / cash withdrawals / account funding debit the card; refunds / original credits credit it). For the issuer authorisation code, walk `events[]` — every event in the lifecycle carries it.
- **Need scheme-level detail?** Walk `events[]` for the full per-step audit trail — every authorisation, clearing, reversal, and refund step — with original scheme amounts (merchant + card currency, with exchange rates), reason codes, and fees attached to the event that triggered them.

Each card payment corresponds to one card-scheme lifecycle (Visa Transaction Identifier / Mastercard TLID). Related-but-separate transactions (refunds, tips, recurring follow-ups) are separate card payments linked via `relatedCardPaymentId` (direct parent).

  - `cardPayment.id` (string, required)
    Stable identifier across the entire payment lifecycle.

  - `cardPayment.profileId` (string)
    The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

  - `cardPayment.type` (string, required)
    High-level type of card payment, derived from the first event.
- `PURCHASE` — standard purchase at a merchant. A purchase of zero is the check a merchant runs to prove the card is live before storing it on file: no money moves, no hold is placed, and it is `SETTLED` on arrival since nothing further will follow. If the merchant later charges the same purchase, the card payment adopts the real type and amount.
- `REFUND` — refund from a merchant to the cardholder.
- `ORIGINAL_CREDIT` — push credit to the cardholder (OCT).
- `ACCOUNT_FUNDING` — load funds onto an account.
- `CASH_WITHDRAWAL` — cash withdrawn at ATM or scheme cash service.
- `BALANCE_INQUIRY` — non-financial balance check.
    Enum: "PURCHASE", "REFUND", "ORIGINAL_CREDIT", "ACCOUNT_FUNDING", "CASH_WITHDRAWAL", "BALANCE_INQUIRY"

  - `cardPayment.card` (object, required)
    Information about a managed card — used wherever a card appears (the card on a card payment, or the access instrument that initiated a transaction).

  - `cardPayment.card.id` (string, required)
    The unique identifier of the managed card.

  - `cardPayment.card.type` (string, required)
    Enum: "managed_cards"

  - `cardPayment.card.mode` (string)
    The mode the card was created in.
- `prepaid`: The card has its own balance and can have funds transferred to or from it.
- `debit`: The card has no balance of its own; it draws on its parent managed account up to a configurable spend limit.
    Enum: "prepaid", "debit"

  - `cardPayment.card.friendlyName` (string)
    The friendly name chosen for the card.

  - `cardPayment.card.nameOnCard` (string)
    The cardholder name printed on the card.

  - `cardPayment.card.cardBrand` (string)
    The scheme of the card. Restricted to schemes supported by card payments.
    Enum: "MASTERCARD", "VISA"

  - `cardPayment.card.cardNumberFirstSix` (string)
    The first six digits of the card number (BIN range).

  - `cardPayment.card.cardNumberLastFour` (string)
    The last four digits of the card number.

  - `cardPayment.card.linkedUserId` (string)
    Identifier of the authorised user the card is assigned to. Populated only when the card has been assigned to a specific user.

  - `cardPayment.card.parentManagedAccountId` (string)
    Identifier of the managed account this card draws funds from. Populated only when `mode` is `debit`.

  - `cardPayment.merchant` (object, required)
    Information about a merchant — used wherever a merchant appears in card-payment flows, statement entries, and transaction activity.

  - `cardPayment.merchant.id` (string, required)
    Merchant identifier (MID) — the acquirer-assigned code that identifies the merchant on card-scheme messages (ISO 8583 DE 42 Card Acceptor Identification Code).

  - `cardPayment.merchant.name` (string, required)
    Merchant name (DBA name).

  - `cardPayment.merchant.nameOther` (string)
    Alternative merchant name as supplied by the card network, when present.

  - `cardPayment.merchant.networkId` (string)
    Identifier assigned by the acquirer or scheme to the merchant.

  - `cardPayment.merchant.categoryCode` (string)
    ISO 18245 merchant category code (MCC).

  - `cardPayment.merchant.description` (string)
    Free-text description of the merchant.

  - `cardPayment.merchant.street` (string)
    Street address of the merchant terminal.

  - `cardPayment.merchant.city` (string)
    City of the merchant terminal.

  - `cardPayment.merchant.state` (string)
    Subdivision (state, province, region) of the merchant terminal.

  - `cardPayment.merchant.postalCode` (string)
    Postal code of the merchant terminal.

  - `cardPayment.merchant.country` (string)
    ISO 3166-1 alpha-2 country code of the merchant terminal.

  - `cardPayment.merchant.telephone` (string)
    Merchant telephone.

  - `cardPayment.merchant.url` (string)
    Merchant website.

  - `cardPayment.merchant.contact` (string)
    Merchant contact (name or email of a representative, when present).

  - `cardPayment.merchant.reference` (string)
    Merchant-supplied reference for the transaction (the merchant's own identifier for what they billed).

  - `cardPayment.merchant.logoUrl` (string)
    Merchant logo URL, when available.

  - `cardPayment.displayAmount` (object, required)
    The object representing a monetary amount in a particular currency.

  - `cardPayment.displayAmount.currency` (string, required)
    The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

  - `cardPayment.displayAmount.amount` (integer, required)
    The monetary amount, scaled to the lowest denomination of the currency.

Example, an amount of 1000 for a EUR currency is actually 1000 Euro cents or EUR 10.00.

  - `cardPayment.status` (string, required)
    Lifecycle status of a CardPayment.
- `SETTLEMENT_IN_PROGRESS` — authorised, not yet (or not fully) settled. The hold is still on the card.
- `SETTLED` — terminal; nothing further is expected. The customer has been charged, except for a zero-amount card check, which settles on arrival without a charge.
- `DECLINED` — the latest authorisation was declined; no money moved.
- `CANCELLED` — the authorisation was cancelled/reversed before settlement; no charge applied.
- `EXPIRED` — the authorisation timed out without settling.
    Enum: "SETTLEMENT_IN_PROGRESS", "SETTLED", "DECLINED", "CANCELLED", "EXPIRED"

  - `cardPayment.relatedCardPaymentId` (string)
    Direct parent linkage — id of the single prior card payment that this payment derives from. Set on:
- `REFUND` payments referring to the original purchase
- `ORIGINAL_CREDIT` payments referring to the prior purchase being credited
- Tip / add-on payments referring to the original ride / fare / service
- Installment / recurring payments referring to the initial setup transaction

Corresponds to Visa's "Original Transaction ID" linkage and Mastercard's DE 105 subelement 002 (Economically Related Transaction Identifier). Not used for messages that share a single lifecycle — those are events on the same card payment.

  - `cardPayment.events` (array, required)
    Ordered event stream — every scheme message in this card payment's lifecycle. For headline display use `displayAmount`; walk this when you need scheme-level detail (per-event amounts, fees, reason codes, reversals).

  - `cardPayment.creationTimestamp` (integer, required)
    When the first event for this payment was received, Epoch millis.

  - `cardPayment.lastUpdatedTimestamp` (integer)
    When the most recent event for this payment was received, Epoch millis.