Sign in
webhook-event
card-transaction

Card transaction state change

Triggered whenever a new card transaction occurs or is modified. See the Webhooks guide for setup instructions, signature verification, and best practices.

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.

  • 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
postWebhookcards#transaction-state-change

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.

X-Delivery-Idstring uuid

Unique identifier for this webhook delivery attempt.

X-Test-Notificationboolean

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

Payload

OR
OR

Example 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",
    "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": [
      {
        "amount": 1,
        "currency": "EUR",
        "fee_type": "ATM_WITHDRAWAL"
      }
    ],
    "transaction_amount_with_fees": {
      "value": 101,
      "currency": "EUR"
    },
    "billing_amount": {
      "value": 100,
      "currency": "EUR"
    },
    "merchant": {
      "name": "Test Payment",
      "location": {
        "country": "France",
        "city": "Rouen",
        "postCode": "00000"
      },
      "category": {
        "code": "5999",
        "description": "5999 R Miscellaneous and Special"
      }
    },
    "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": [
      {
        "balance_id": 123,
        "debited_amount": {
          "value": 165.96,
          "currency": "AUD"
        },
        "for_amount": {
          "value": 101,
          "currency": "EUR"
        },
        "rate": 0.61223252,
        "fee": {
          "value": 0.99,
          "currency": "AUD"
        },
        "creation_time": "2022-08-15T11:10:41.456Z"
      }
    ],
    "credits": [
      {
        "balance_id": 123,
        "credited_amount": {
          "value": 100,
          "currency": "EUR"
        }
      }
    ],
    "relay_authorisation_data": {
      "response_code": "APPROVED",
      "fallback": true
    }
  }
}

Response

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

statusstring

Example response

{
  "status": "ok"
}

Changes