Managed cards

Card authorization

Sent each time an authorization is processed on a managed card — a merchant asking for funds, or an existing hold being adjusted or released. No money moves until the authorization clears.

This reports authorizations after the fact. To approve or decline them as they happen, use Approve or reject card payments instead.

Match against the corresponding settlement using authCode.

Enable and configure webhooks in the Embedder Portal; recent events are listed on its Webhook Logs page. Weavr sends this event to {Webhook URL}/managed_cards/authorisations/watch.

postWebhook/managed_cards/authorisations/watch

Headers

call-refstring

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-timestampinteger required

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signaturestring 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-v2string 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.

Payload

type'AUTHORISATION' | 'SETTLEMENT' | 'REFUND' | 'ORIGINAL_CREDIT' required

Type of event recorded against a CardPayment. The reversal flag on each event distinguishes a reversal from the original action.

idstring required
subtype'sale_purchases' | 'cash_withdrawals' | 'sales_with_cashback' | 'mail_or_telephone_orders' | 'account_funding' required

Card-scheme network classification of the underlying transaction, representing the type of activity the authorization is for. Reversal-vs-original lives on the separate reversal field.

reversalboolean

True when this event is a reversal of a prior authorization in the same lifecycle (e.g. merchant void, expiry, explicit cancellation). False for originals.

result'APPROVED' | 'DECLINED'

Outcome of an authorization event.

authorisationCategory'PRE_AUTH' | 'FINAL_AUTH'

The category of the authorization.

declineReason'NO_REASON' | 'PHYSICAL_NOT_ACTIVATED' | 'INSUFFICIENT_BALANCE' | 'CVV_CHECKS_FAILED' | 'CVV_RETRIES_EXCEEDED' | 'CARD_STATUS_NOT_ALLOWED' | 'PIN_CHECKS_FAILED' | 'PIN_RETRIES_EXCEEDED' | 'CARD_EXPIRY_CHECKS_FAILED' | 'AVS_CHECKS_FAILED' | 'ATM_WITHDRAWAL_LIMIT_EXCEEDED' | 'SCA_REQUIRED' | 'AUTH_RULE_CHECKS_FAILED' | 'TRANSACTION_NOT_PERMITTED' | 'TIMEOUT' | 'SINGLE_SPEND'

Reason an authorization was declined; populated only when result = DECLINED. Mirrors the legacy authorization webhook's decline reason values.

authRuleFailedReasonstring

The specific auth rule that caused the decline. Present when declineReason is AUTH_RULE_CHECKS_FAILED. Mirrors the legacy authorization webhook's authRuleFailedReason.

cancellationReasonstring

Free-text reason for an explicit cancellation of an authorization hold. Populated on reversal: true events driven by explicit cancellation rather than network reversal.

authCodestring

Issuer authorization code on this scheme message (ISO 8583 DE 38). Echoed by subsequent settlement, refund, OCT messages in the same lifecycle.

timestampinteger required

When this event occurred at the point-of-interaction, Epoch milliseconds.

processedTimestampinteger

When this event was processed by the platform, Epoch milliseconds.

cardPaymentIdstring required

Id of the parent CardPayment this event belongs to.

Example payload

{
  "id": "123456789",
  "authForwardingDetails": {
    "triggered": true
  },
  "cancellationReason": "Cancelled at the customer's request",
  "transactionAmount": {
    "currency": "GBP",
    "amount": 1250
  },
  "billingAmount": {
    "currency": "GBP",
    "amount": 1250
  },
  "forex": {
    "exchangeRate": {
      "value": 1250,
      "scale": 2
    },
    "padding": {
      "currency": "GBP",
      "amount": 1250
    }
  },
  "userAmount": {
    "currency": "GBP",
    "amount": 1250
  },
  "userExchangeRate": {
    "value": 1250,
    "scale": 2
  },
  "authCode": "123456",
  "timestamp": 1786118400000,
  "processedTimestamp": 1786118401250,
  "cardPaymentId": "123456789",
  "card": {
    "id": "234567890",
    "friendlyName": "Travel card",
    "nameOnCard": "Alex Smith",
    "cardNumberFirstSix": "453201",
    "cardNumberLastFour": "0366",
    "linkedUserId": "987654321",
    "parentManagedAccountId": "123456789"
  },
  "merchant": {
    "id": "MID123456",
    "name": "Coffee Corner",
    "nameOther": "Coffee Corner Ltd",
    "networkId": "NET123456",
    "categoryCode": "5812",
    "description": "Coffee shop",
    "street": "1 High Street",
    "city": "London",
    "state": "Greater London",
    "postalCode": "W1A 1AA",
    "country": "GB",
    "telephone": "+442079460000",
    "url": "https://www.coffeecorner.example",
    "contact": "info@coffeecorner.example",
    "reference": "ORD-20260803-0001",
    "logoUrl": "https://www.coffeecorner.example/logo.png"
  }
}

Response

Event received.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.