Skip to content

Card transaction state change
Webhook

Request

Triggered whenever a new card transaction occurs or is modified.

  • Event type: cards#transaction-state-change
  • Profile level subscriptions: Not Supported
  • Application level subscriptions: Supported

Transaction categorisation

Transactions can be categorized based on the guidelines below, though the results may not always be consistent.

  • Active card check: transaction_amount is 0 or 1 and merchant.category.code does not equal 6011.
  • ATM balance check: transaction_amount is 0 and merchant.category.code equals 6011.
  • Pre-Authorisation: is_amount_confirmed is false and transaction_state equals IN_PROGRESS.

Events may not be delivered in the order they occurred. Use data.occurred_at to reconcile the order. See the Event ordering guide for details.

See the Webhooks guide for setup instructions, signature verification, and best practices.

Headers
X-Signature-SHA256string

RSA-SHA256 signature of the request body, Base64 encoded. Verify this against the Wise public key to ensure the request is authentic and has not been tampered with.

Example:t7FMhk3OARMgwqz0LJXO...
X-Delivery-Idstring, (uuid)

Unique identifier for this webhook delivery attempt.

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Test-Notificationboolean

Present with the value true if this is a test notification sent to verify your callback URL during subscription setup.

Example:true
Bodyapplication/json
schema_versionstring

Version of the event schema. Determined by the schema_version on your webhook subscription.

Value:"4.0.0"
Example:"4.0.0"
Discriminator
subscription_idstring, (uuid)

ID of the webhook subscription that triggered this event.

Example:"568da36b-7335-4608-ad1b-e5c2d32273b6"
event_typestring

Event type identifier

Example:"cards#transaction-state-change"
sent_atstring, (date-time)

Timestamp when the event was sent.

Example:"2022-08-15T11:10:46.123Z"
dataobject
Payload
{
  "schema_version": "4.0.0",
  "subscription_id": "568da36b-7335-4608-ad1b-e5c2d32273b6",
  "event_type": "cards#transaction-state-change",
  "sent_at": "2022-08-15T11:10:46.123Z",
  "data": {
    "resource": {
      "profile_id": 123456,
      "client_id": "your-bank",
      "card_token": "136b29e4-7eab-4dac-a017-438d494ef6cb",
      "card_last_digits": "1234",
      "type": "card"
    },
    "transaction_id": 12345,
    "transaction_type": "CASH_WITHDRAWAL",
    "transaction_step_type": "CAPTURE",
    "transaction_state": "COMPLETED",
    "decline_reason": null,
    "detailed_decline_reason": null,
    "creation_time": "2022-08-15T11:10:41.456Z",
    "occurred_at": "2022-08-15T11:10:41.789Z",
    "purge_time": "2022-08-22T11:10:41.123Z",
    "transaction_amount": {
      "value": 100,
      "currency": "EUR"
    },
    "fees": [
      { … }
    ],
    "transaction_amount_with_fees": {
      "value": 101,
      "currency": "EUR"
    },
    "billing_amount": {
      "value": 100,
      "currency": "EUR"
    },
    "merchant": {
      "name": "Test Payment",
      "location": { … },
      "category": { … }
    },
    "authorisation_method": "MANUAL_ENTRY",
    "approval_code": "913647",
    "arn": "04300014127798385983852",
    "pin_validation_result": "ONLINE_PIN_VALIDATED",
    "balance_channel_reference_id": "6e71018d-2f4d-4fc3-6711-f517f4664712",
    "debits": [
      { … }
    ],
    "credits": [
      { … }
    ],
    "relay_authorisation_data": {
      "response_code": "APPROVED",
      "fallback": true
    }
  }
}

Responses

Return any 2xx status to acknowledge receipt of the event.

Bodyapplication/json
statusstring
Example:"ok"
Response
{
  "status": "ok"
}