Available Events

Complete list of webhook events available in Koard.

Transaction Events

Koard sends webhook events for all transaction lifecycle changes, enabling real-time monitoring and integration with your systems.

transaction.created

Triggered when a new transaction is created (initial tap or API call).

{
  "event": "transaction.created",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor_mid": "5289003",
    "processor_tid": "5289003",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "device_id": "0b3b1ec9210ffa18c7f53ce4a915e1653da4b14113259d1d31ec674c14e2c232",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "location_id": "11efaf2f-2b69-40ee-9da1-19ef826d5fed",
    "gateway_transaction_id": "BG6RJZHK8Q",
    "subtotal": 0,
    "tip_amount": 0,
    "tip_type": "percentage",
    "tax_amount": 0,
    "tax_rate": 0,
    "total_amount": 545,
    "surcharge_applied": false,
    "surcharge_amount": 0,
    "surcharge_rate": 0,
    "refunded": 0,
    "reversed": 0,
    "created_at": 1753985520000,
    "status": "authorized",
    "status_reason": "approved",
    "payment_method": "contactlessIcc",
    "card_type": "MasterCard",
    "card_brand": "MasterCard",
    "card": "541333******4111",
    "transaction_type": "auth",
    "apple_transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "reader_identifier": "0b3b1ec9210ffa18c7f53ce4a915e1653da4b14113259d1d31ec674c14e2c232",
    "owner_id": "0c214fba-5bb6-460a-afed-935a8b52f702",
    "parent_account_ids": [
      "bf692281-0052-4515-a7fb-da3633841049",
      "0c214fba-5bb6-460a-afed-935a8b52f702"
    ],
    "merchant_name": "",
    "gateway_transaction_response": {
      "type": "sale",
      "status": "pending",
      "currency": "USD",
      "approvalCode": "522841",
      "responseCode": "A",
      "responseMessage": "APPROVAL",
      "authorizedAmount": 545,
      "processorResponseCode": "00"
    },
    "processor_response_code": "A",
    "processor_response_message": "APPROVAL"
  }
}

transaction.authorized

Triggered when a transaction is authorized.

{
  "event": "transaction.authorized",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "total_amount": 545,
    "status": "authorized",
    "status_reason": "approved",
    "transaction_type": "auth",
    "gateway_transaction_response": {
      "type": "sale",
      "status": "pending",
      "currency": "USD",
      "approvalCode": "522841",
      "responseCode": "A",
      "responseMessage": "APPROVAL",
      "authorizedAmount": 545,
      "processorResponseCode": "00"
    },
    "processor_response_code": "A",
    "processor_response_message": "APPROVAL",
    "authorized_at": 1753985520000
  }
}

transaction.captured

Triggered when a transaction is captured.

{
  "event": "transaction.captured",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "total_amount": 545,
    "status": "captured",
    "status_reason": "approved",
    "transaction_type": "sale",
    "gateway_transaction_response": {
      "type": "sale",
      "status": "ready",
      "currency": "USD",
      "approvalCode": "522841",
      "responseCode": "A",
      "responseMessage": "APPROVAL",
      "authorizedAmount": 545,
      "processorResponseCode": "00"
    },
    "processor_response_code": "A",
    "processor_response_message": "APPROVAL",
    "captured_at": 1753985620000
  }
}

transaction.refunded

Triggered when a transaction is refunded.

{
  "event": "transaction.refunded",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "total_amount": 545,
    "refunded": 545,
    "status": "refunded",
    "status_reason": "approved",
    "transaction_type": "refund",
    "gateway_transaction_response": {
      "type": "sale",
      "status": "complete",
      "currency": "USD",
      "approvalCode": "522841",
      "responseCode": "A",
      "responseMessage": "APPROVAL",
      "authorizedAmount": 545,
      "processorResponseCode": "00"
    },
    "processor_response_code": "A",
    "processor_response_message": "APPROVAL",
    "refunded_at": 1753985720000
  }
}

transaction.reversed

Triggered when a transaction is reversed.

{
  "event": "transaction.reversed",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "total_amount": 545,
    "reversed": 545,
    "status": "reversed",
    "status_reason": "approved",
    "transaction_type": "reverse",
    "gateway_transaction_response": {
      "type": "sale",
      "status": "reversal",
      "currency": "USD",
      "approvalCode": "522841",
      "responseCode": "A",
      "responseMessage": "APPROVAL",
      "authorizedAmount": 545,
      "processorResponseCode": "00"
    },
    "processor_response_code": "A",
    "processor_response_message": "APPROVAL",
    "reversed_at": 1753985820000
  }
}

transaction.adjusted

Triggered when a transaction amount is adjusted (incremental auth or modification).

{
  "event": "transaction.adjusted",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "previous_amount": 5000,
    "total_amount": 7000,
    "adjustment_amount": 2000,
    "status": "authorized",
    "status_reason": "approved",
    "transaction_type": "auth",
    "adjusted_at": 1753985720000
  }
}

transaction.cancelled

Triggered when a transaction is cancelled (full reversal or refund to 0).

{
  "event": "transaction.cancelled",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "total_amount": 5000,
    "status": "cancelled",
    "status_reason": "voided",
    "cancelled_at": 1753985920000
  }
}

transaction.settled

Triggered when a transaction is settled by the processor.

{
  "event": "transaction.settled",
  "data": {
    "transaction_id": "d7fa08cf-9c29-4629-96ae-921c226c32cf",
    "event_id": "C55A7E4B-DD7C-4CFA-A59D-303156F78F5F",
    "mid": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "tid": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "processor": "tsys",
    "gateway": "sierra",
    "currency": "USD",
    "total_amount": 5000,
    "batch_id": "batch_1234567890",
    "status": "settled",
    "settled_at": 1753986020000
  }
}

Account Events

account.created

Triggered when a new account is created.

{
  "event": "account.created",
  "data": {
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "name": "Test Merchant Account",
    "status": "active",
    "created_at": 1753985520000
  }
}

account.updated

Triggered when account information is updated.

{
  "event": "account.updated",
  "data": {
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "updated_fields": ["settings", "status"],
    "status": "active",
    "updated_at": 1753985520000
  }
}

account.deleted

Triggered when an account is deleted (soft delete).

{
  "event": "account.deleted",
  "data": {
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "deleted_at": 1753985620000
  }
}

account.restored

Triggered when a deleted account is restored.

{
  "event": "account.restored",
  "data": {
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "restored_at": 1753985720000
  }
}

Terminal Events

terminal.created

Triggered when a new terminal is created.

{
  "event": "terminal.created",
  "data": {
    "terminal_id": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "location_id": "11efaf2f-2b69-40ee-9da1-19ef826d5fed",
    "processor": "tsys",
    "gateway": "sierra",
    "processor_mid": "5289003",
    "processor_tid": "5289003",
    "status": "active",
    "created_at": 1753985520000
  }
}

terminal.updated

Triggered when terminal configuration is updated.

{
  "event": "terminal.updated",
  "data": {
    "terminal_id": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "updated_fields": ["processor_config", "status"],
    "status": "active",
    "updated_at": 1753985620000
  }
}

terminal.deleted

Triggered when a terminal is deleted (soft delete).

{
  "event": "terminal.deleted",
  "data": {
    "terminal_id": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "deleted_at": 1753985720000
  }
}

terminal.restored

Triggered when a deleted terminal is restored.

{
  "event": "terminal.restored",
  "data": {
    "terminal_id": "cd20477b-6936-4d62-9656-89b5de34dd20",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "restored_at": 1753985820000
  }
}

Location Events

location.created

Triggered when a new location is created.

{
  "event": "location.created",
  "data": {
    "location_id": "11efaf2f-2b69-40ee-9da1-19ef826d5fed",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "name": "Main Store",
    "address": "123 Main St, City, ST 12345",
    "status": "active",
    "created_at": 1753985520000
  }
}

location.updated

Triggered when location information is updated.

{
  "event": "location.updated",
  "data": {
    "location_id": "11efaf2f-2b69-40ee-9da1-19ef826d5fed",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "updated_fields": ["name", "address"],
    "updated_at": 1753985620000
  }
}

location.deleted

Triggered when a location is deleted (soft delete).

{
  "event": "location.deleted",
  "data": {
    "location_id": "11efaf2f-2b69-40ee-9da1-19ef826d5fed",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "deleted_at": 1753985720000
  }
}

location.restored

Triggered when a deleted location is restored.

{
  "event": "location.restored",
  "data": {
    "location_id": "11efaf2f-2b69-40ee-9da1-19ef826d5fed",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "restored_at": 1753985820000
  }
}

API Key Events

apikey.created

Triggered when a new API key is created.

{
  "event": "apikey.created",
  "data": {
    "apikey_id": "key_1234567890",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "name": "Production API Key",
    "scopes": ["read:transactions", "write:transactions"],
    "created_at": 1753985520000
  }
}

apikey.revoked

Triggered when an API key is revoked.

{
  "event": "apikey.revoked",
  "data": {
    "apikey_id": "key_1234567890",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "revoked_at": 1753985620000
  }
}

Credentials Events

credentials.created

Triggered when new processor credentials are created.

{
  "event": "credentials.created",
  "data": {
    "credentials_id": "cred_1234567890",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "processor": "tsys",
    "gateway": "sierra",
    "created_at": 1753985520000
  }
}

credentials.revoked

Triggered when processor credentials are revoked.

{
  "event": "credentials.revoked",
  "data": {
    "credentials_id": "cred_1234567890",
    "account_id": "ae4e8b9b-9841-44c2-9080-85ca72e8b59c",
    "processor": "tsys",
    "gateway": "sierra",
    "revoked_at": 1753985620000
  }
}

Batch Events

batch.created

Triggered when a new batch is created.

{
  "event": "batch.created",
  "data": {
    "batch_id": "batch_1234567890",
    "name": "Daily Batch - 2024-01-15",
    "transaction_count": 150,
    "total_amount": 150000,
    "currency": "USD",
    "processor": "tsys",
    "gateway": "sierra",
    "created_at": 1753985520000,
    "status": "open"
  }
}

batch.completed

Triggered when a batch is completed.

{
  "event": "batch.completed",
  "data": {
    "batch_id": "batch_1234567890",
    "status": "completed",
    "transaction_count": 150,
    "total_amount": 150000,
    "currency": "USD",
    "processor": "tsys",
    "gateway": "sierra",
    "completed_at": 1753985620000
  }
}

Event Processing

Handling Events

function processWebhook(payload) {
  const { event, data } = payload;
  
  switch (event) {
    // Transaction events
    case 'transaction.created':
      handleTransactionCreated(data);
      break;
    case 'transaction.authorized':
      handleTransactionAuthorized(data);
      break;
    case 'transaction.captured':
      handleTransactionCaptured(data);
      break;
    case 'transaction.adjusted':
      handleTransactionAdjusted(data);
      break;
    case 'transaction.cancelled':
      handleTransactionCancelled(data);
      break;
    case 'transaction.refunded':
      handleTransactionRefunded(data);
      break;
    case 'transaction.reversed':
      handleTransactionReversed(data);
      break;
    case 'transaction.settled':
      handleTransactionSettled(data);
      break;
    
    // Account events
    case 'account.created':
      handleAccountCreated(data);
      break;
    case 'account.updated':
      handleAccountUpdated(data);
      break;
    case 'account.deleted':
      handleAccountDeleted(data);
      break;
    case 'account.restored':
      handleAccountRestored(data);
      break;
    
    // Terminal events
    case 'terminal.created':
      handleTerminalCreated(data);
      break;
    case 'terminal.updated':
      handleTerminalUpdated(data);
      break;
    case 'terminal.deleted':
      handleTerminalDeleted(data);
      break;
    case 'terminal.restored':
      handleTerminalRestored(data);
      break;
    
    // Location events
    case 'location.created':
      handleLocationCreated(data);
      break;
    case 'location.updated':
      handleLocationUpdated(data);
      break;
    case 'location.deleted':
      handleLocationDeleted(data);
      break;
    case 'location.restored':
      handleLocationRestored(data);
      break;
    
    // API Key events
    case 'apikey.created':
      handleAPIKeyCreated(data);
      break;
    case 'apikey.revoked':
      handleAPIKeyRevoked(data);
      break;
    
    // Credentials events
    case 'credentials.created':
      handleCredentialsCreated(data);
      break;
    case 'credentials.revoked':
      handleCredentialsRevoked(data);
      break;
    
    // Batch events
    case 'batch.created':
      handleBatchCreated(data);
      break;
    case 'batch.completed':
      handleBatchCompleted(data);
      break;
    
    default:
      console.log('Unknown event:', event);
  }
}

Idempotency

Webhook events are idempotent. You can safely process the same event multiple times without side effects. Use the event_id field to track processed events.

Event Ordering

Events are delivered in the order they occurred, but network issues may cause out-of-order delivery. Always check timestamps and implement proper ordering logic if needed.

Event Filtering

You can filter events by:

Event Type: Subscribe to specific event types
Transaction Type: Filter by transaction_type (auth, sale, refund, reverse)
Status: Filter by status (authorized, captured, declined, refunded, reversed)
Processor: Filter by processor (tsys, payroc, etc.)
Gateway: Filter by gateway (sierra, etc.)

Complete Event List

Event	Description	Category
`transaction.created`	Transaction initiated	Transaction
`transaction.authorized`	Transaction authorized	Transaction
`transaction.captured`	Transaction captured	Transaction
`transaction.adjusted`	Transaction amount adjusted	Transaction
`transaction.cancelled`	Transaction cancelled	Transaction
`transaction.refunded`	Transaction refunded	Transaction
`transaction.reversed`	Transaction reversed	Transaction
`transaction.settled`	Transaction settled	Transaction
`account.created`	Account created	Account
`account.updated`	Account updated	Account
`account.deleted`	Account deleted	Account
`account.restored`	Account restored	Account
`terminal.created`	Terminal created	Terminal
`terminal.updated`	Terminal updated	Terminal
`terminal.deleted`	Terminal deleted	Terminal
`terminal.restored`	Terminal restored	Terminal
`location.created`	Location created	Location
`location.updated`	Location updated	Location
`location.deleted`	Location deleted	Location
`location.restored`	Location restored	Location
`apikey.created`	API key created	API Key
`apikey.revoked`	API key revoked	API Key
`credentials.created`	Credentials created	Credentials
`credentials.revoked`	Credentials revoked	Credentials
`batch.created`	Batch created	Batch
`batch.completed`	Batch completed	Batch