Sign in

v5

latestOpenAPI 3.1.02026-07-262421791.5 MB
webhook-event
card-transaction

Card transaction state change

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.

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"
}