Webhooks

Available Events

Complete list of webhook events Koard can deliver, with the exact payload your endpoint receives.

Payload shape

Almost every webhook request body is the resource object itself, as flat JSON — for example a batch.accepted body is a Batch, a transaction.sale body is a Transaction. There is no {"event": ..., "data": ...} envelope; the fields shown below are top-level.

The exception is the *.deleted events (account.deleted, terminal.deleted, location.deleted), which carry a sparse id-only payload — just the resource id (and account_id where applicable), not the full object, since the resource no longer exists. Each event's exact body is shown below.

The event type is not in the request body. Koard delivers webhooks through Svix, so the body is the raw payload and the delivery metadata rides in headers (svix-id, svix-timestamp, svix-signature). To know which event an endpoint received, subscribe that endpoint to specific event types in the developer portal (one endpoint per event or per category). Transactions and batches also carry discriminators in the body — branch on transaction_type / status for transactions and on status for batches.

Conventions used in every payload:

  • Money is in minor units (cents) — 5000 means $50.00.
  • Timestamps: transaction created_at is a Unix timestamp in milliseconds; every other resource (batch, account, terminal, location, api_key, credential) uses ISO-8601 strings (opened_at, created_at, …).
  • Secrets are masked: the card is truncated (4113********4242), an API key is "****" + last4, and a credential PIN is "****". Full secrets and hash material are never sent.
  • Unset optional fields are present with a null value.

Transaction outcomes

Transaction webhooks are named after the operation that was attempted — not its result. A sale attempt always fires transaction.sale, an authorization always fires transaction.authorize, and so on — whether the attempt was approved, declined, or errored.

The outcome lives in the payload:

  • status — the resulting state (e.g. authorized, captured, declined, error).
  • status_reason — a machine-readable reason for that status (e.g. approved, insufficient_funds, payment_failed).

So your handler should branch on status to tell success from failure.

Failed and declined attempts fire the same event as a success. A declined or errored auth is still delivered as transaction.authorize; a failed sale as transaction.sale. There is no separate transaction.failed or transaction.declined event — read status / status_reason to handle the result.

Transaction statuses

status reflects the resulting state of the transaction:

status Meaning Outcome
authorized Funds held, not yet captured ✅ Success
captured Funds captured (sale or capture) ✅ Success
settled Funds finalized in a settled batch ✅ Success
refunded Refund completed ✅ Success
reversed Authorization reversed / voided ✅ Success
pending Awaiting external input ⏳ In progress
surcharge_pending Awaiting surcharge confirmation ⏳ In progress
declined Declined by the issuer ❌ Failure
error The attempt could not be completed (host / format / network error) ❌ Failure
canceled Canceled by the user or system ⛔ Not completed

Status reasons

status_reason explains why a transaction ended in its status. Common values:

status_reason Meaning
approved The operation was approved
declined The issuer declined the transaction
insufficient_funds Declined — the account had insufficient funds
invalid_card The card was invalid or expired
payment_failed The host / gateway returned an unclassified failure (not a clean decline)
processor_timeout / timed_out No response from the processor in time
network_connectivity_error Could not reach the processor
invalid_gateway_response / format_error The processor response could not be parsed
invalid_terminal The terminal / BIN is not boarded or is misconfigured
partial_approval Approved for less than the requested amount
incremental_auth_declined An incremental authorization was declined
invalid_tip_adjustment A tip adjustment is not allowed for this transaction
exceeds_original_auth A capture / adjustment exceeds the original authorization
invalid_capture_sequence A capture was attempted in an invalid state
surcharge_declined_by_payer / surcharge_expired The cardholder declined the surcharge, or the prompt expired
user_canceled / merchant_canceled Canceled by the cardholder or the merchant
duplicate_event A duplicate event ID was received

Parsing a transaction webhook

Verify the Svix signature first (see Setting up Webhooks), then read the flat transaction body. This endpoint is subscribed to transaction events, so the body is a Transaction; route on transaction_type and branch on status. 

# POST https://your-app.com/webhooks/koard  (subscribed to transaction.* events)
from flask import request, jsonify

SUCCESS_STATUSES = {"authorized", "captured", "settled", "refunded", "reversed"}
IN_PROGRESS_STATUSES = {"pending", "surcharge_pending"}

@app.route("/webhooks/koard", methods=["POST"])
def koard_webhook():
    txn = request.get_json()          # the body IS the transaction (flat, no envelope)
    operation = txn["transaction_type"]   # sale / auth / capture / refund / reverse / ...
    status = txn.get("status")

    if status in SUCCESS_STATUSES:
        handle_success(operation, txn)
    elif status in IN_PROGRESS_STATUSES:
        handle_in_progress(operation, status, txn)   # awaiting input; not final yet
    elif status == "canceled":
        handle_canceled(operation, txn)              # not completed
    else:
        # only declined / error land here — status_reason explains why
        handle_failure(operation, status, txn.get("status_reason"), txn)

    return jsonify(received=True), 200

// POST https://your-app.com/webhooks/koard  (subscribed to transaction.* events)
const SUCCESS_STATUSES = new Set([
  "authorized", "captured", "settled", "refunded", "reversed",
]);
const IN_PROGRESS_STATUSES = new Set(["pending", "surcharge_pending"]);

app.post("/webhooks/koard", (req, res) => {
  const txn = req.body;               // the body IS the transaction (flat, no envelope)
  const { transaction_type: operation, status, status_reason } = txn;

  if (SUCCESS_STATUSES.has(status)) {
    handleSuccess(operation, txn);
  } else if (IN_PROGRESS_STATUSES.has(status)) {
    handleInProgress(operation, status, txn);   // awaiting input; not final yet
  } else if (status === "canceled") {
    handleCanceled(operation, txn);             // not completed
  } else {
    // only declined / error land here — `status_reason` explains why
    handleFailure(operation, status, status_reason, txn);
  }

  res.status(200).json({ received: true });
});

# POST https://your-app.com/webhooks/koard  (subscribed to transaction.* events)
SUCCESS_STATUSES     = %w[authorized captured settled refunded reversed].freeze
IN_PROGRESS_STATUSES = %w[pending surcharge_pending].freeze

post "/webhooks/koard" do
  txn       = JSON.parse(request.body.read)   # the body IS the transaction (flat)
  operation = txn["transaction_type"]
  status    = txn["status"]

  if SUCCESS_STATUSES.include?(status)
    handle_success(operation, txn)
  elsif IN_PROGRESS_STATUSES.include?(status)
    handle_in_progress(operation, status, txn)   # awaiting input; not final yet
  elsif status == "canceled"
    handle_canceled(operation, txn)              # not completed
  else
    # only declined / error land here
    handle_failure(operation, status, txn["status_reason"], txn)
  end

  status 200
  { received: true }.to_json
end

// POST https://your-app.com/webhooks/koard  (subscribed to transaction.* events)
private static final Set<String> SUCCESS_STATUSES =
    Set.of("authorized", "captured", "settled", "refunded", "reversed");
private static final Set<String> IN_PROGRESS_STATUSES =
    Set.of("pending", "surcharge_pending");

@PostMapping("/webhooks/koard")
public ResponseEntity<Void> koardWebhook(@RequestBody Map<String, Object> txn) {
    String operation = (String) txn.get("transaction_type");
    String status = (String) txn.get("status");

    if (SUCCESS_STATUSES.contains(status)) {
        handleSuccess(operation, txn);
    } else if (IN_PROGRESS_STATUSES.contains(status)) {
        handleInProgress(operation, status, txn);   // awaiting input; not final yet
    } else if ("canceled".equals(status)) {
        handleCanceled(operation, txn);             // not completed
    } else {
        // only declined / error land here
        handleFailure(operation, status, (String) txn.get("status_reason"), txn);
    }
    return ResponseEntity.ok().build();
}

<?php // POST https://your-app.com/webhooks/koard  (subscribed to transaction.* events)
$SUCCESS_STATUSES     = ['authorized', 'captured', 'settled', 'refunded', 'reversed'];
$IN_PROGRESS_STATUSES = ['pending', 'surcharge_pending'];

$txn       = json_decode(file_get_contents('php://input'), true); // body IS the transaction
$operation = $txn['transaction_type'];
$status    = $txn['status'] ?? null;

if (in_array($status, $SUCCESS_STATUSES, true)) {
    handle_success($operation, $txn);
} elseif (in_array($status, $IN_PROGRESS_STATUSES, true)) {
    handle_in_progress($operation, $status, $txn);   // awaiting input; not final yet
} elseif ($status === 'canceled') {
    handle_canceled($operation, $txn);               // not completed
} else {
    // only declined / error land here
    handle_failure($operation, $status, $txn['status_reason'] ?? null, $txn);
}

http_response_code(200);
echo json_encode(['received' => true]);

The examples below show the exact body delivered for each event.

Transaction Events

transaction.authorize

Card authorized — funds held, not yet captured.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "authorized",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "auth",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.sale

Sale — card authorized and captured in one step.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "captured",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "sale",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.capture

A prior authorization was captured for settlement.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "captured",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "capture",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.cancel

Transaction cancelled before settlement.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "canceled",
  "status_reason": "user_canceled",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "sale",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.create

A transaction record was created.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "pending",
  "status_reason": "pending",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "sale",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": null,
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.reverse

Authorization voided/undone after auth, before settlement.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 5000,
  "created_at": 1768470600000,
  "status": "reversed",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "reverse",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.refund

Funds refunded to the cardholder after settlement.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 5000,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "refunded",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "refund",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.increment

An existing authorization amount was increased (incremental auth).

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 6200,
  "tip_amount": 800,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 7000,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "authorized",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "incremental_auth",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

transaction.tip_adjust

A tip was added or changed on a captured transaction.

{
  "transaction_id": "6f6b6d2e-1c3a-4a9e-9d21-2f0e7b8c9a10",
  "event_id": "6F6B6D2E-1C3A-4A9E-9D21-2F0E7B8C9A10",
  "mid": "445566778899",
  "tid": "TERM0001",
  "processor_mid": "5289003",
  "processor_tid": "5289003",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "device_id": "dev_5Hj3Kl8Mn2Pq6Rt",
  "processor": "tsys",
  "gateway": "sierra",
  "currency": "USD",
  "location_id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "gateway_transaction_id": "BG6RJZHK8Q",
  "subtotal": 4200,
  "tip_amount": 1200,
  "tip_type": "amount",
  "tip_capture_mode": null,
  "tax_amount": 0,
  "tax_rate": 0,
  "tax_source": null,
  "tax_basis": null,
  "total_amount": 5400,
  "surcharge_applied": false,
  "surcharge_amount": 0,
  "surcharge_rate": 0,
  "surcharge_source": null,
  "surcharge_basis": null,
  "surcharge_confirmation_required": null,
  "refunded": 0,
  "reversed": 0,
  "created_at": 1768470600000,
  "status": "captured",
  "status_reason": "approved",
  "payment_method": "contactlessIcc",
  "card_type": "credit",
  "card_brand": "visa",
  "card": "4113********4242",
  "additional_details": {},
  "gateway_transaction_response": {
    "responseCode": "A",
    "responseMessage": "APPROVAL",
    "approvalCode": "522841",
    "processorResponseCode": "00"
  },
  "processor_response_code": "00",
  "processor_response_message": "Approved",
  "transaction_type": "tip_adjust",
  "apple_transaction_id": "",
  "reader_identifier": "rdr_8Wq2Er5Ty7Ui",
  "owner_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "merchant_name": "Blue Bottle Coffee",
  "psp": null,
  "batch_id": "batch_6Yh3Uj8Ik2Ol",
  "device_type": null,
  "terminal_details": null,
  "history": []
}

Batch Events

batch.opened

A settlement batch was opened.

{
  "id": "batch_6Yh3Uj8Ik2Ol",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "processor_name": "tsys",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "open",
  "captured_amount": 0,
  "refunded_amount": 0,
  "transaction_count": 0,
  "processor_batch_id": null,
  "opened_at": "2026-01-15T08:00:00Z",
  "closed_at": null,
  "response": null,
  "batch_metadata": {}
}

batch.rejected

The processor rejected the batch.

{
  "id": "batch_6Yh3Uj8Ik2Ol",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "processor_name": "tsys",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "rejected",
  "captured_amount": 128400,
  "refunded_amount": 5000,
  "transaction_count": 37,
  "processor_batch_id": "TSYS-BATCH-000481",
  "opened_at": "2026-01-15T08:00:00Z",
  "closed_at": null,
  "response": {
    "rejection_reason": "Host unavailable \u2014 retry"
  },
  "batch_metadata": {}
}

batch.accepted

The processor accepted the batch for settlement.

{
  "id": "batch_6Yh3Uj8Ik2Ol",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "processor_name": "tsys",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "accepted",
  "captured_amount": 128400,
  "refunded_amount": 5000,
  "transaction_count": 37,
  "processor_batch_id": "TSYS-BATCH-000481",
  "opened_at": "2026-01-15T08:00:00Z",
  "closed_at": "2026-01-15T20:00:00Z",
  "response": null,
  "batch_metadata": {}
}

batch.partially_accepted

The processor accepted the batch with some rejected records.

{
  "id": "batch_6Yh3Uj8Ik2Ol",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "processor_name": "tsys",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "partially_accepted",
  "captured_amount": 128400,
  "refunded_amount": 5000,
  "transaction_count": 37,
  "processor_batch_id": "TSYS-BATCH-000481",
  "opened_at": "2026-01-15T08:00:00Z",
  "closed_at": "2026-01-15T20:00:00Z",
  "response": {
    "accepted": 35,
    "rejected": 2
  },
  "batch_metadata": {}
}

batch.edited

A batch's transactions were edited before close.

{
  "id": "batch_6Yh3Uj8Ik2Ol",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "processor_name": "tsys",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "open",
  "captured_amount": 128400,
  "refunded_amount": 5000,
  "transaction_count": 36,
  "processor_batch_id": "TSYS-BATCH-000481",
  "opened_at": "2026-01-15T08:00:00Z",
  "closed_at": null,
  "response": null,
  "batch_metadata": {}
}

batch.submitted

A batch was submitted to the processor for settlement.

{
  "id": "batch_6Yh3Uj8Ik2Ol",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "processor_name": "tsys",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "submitted",
  "captured_amount": 128400,
  "refunded_amount": 5000,
  "transaction_count": 37,
  "processor_batch_id": "TSYS-BATCH-000481",
  "opened_at": "2026-01-15T08:00:00Z",
  "closed_at": null,
  "response": null,
  "batch_metadata": {}
}

Account Events

account.created

A new account was created.

{
  "id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "organization_id": null,
  "has_access_to_mms": false,
  "has_access_to_apple_config": false,
  "available_processor_configs": [],
  "tax_id": null,
  "mcc": "5812",
  "type": "merchant",
  "status": "active",
  "name": "Blue Bottle Coffee",
  "description": "Specialty coffee roaster",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null
}

account.updated

An account's details were updated.

{
  "id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "organization_id": null,
  "has_access_to_mms": false,
  "has_access_to_apple_config": false,
  "available_processor_configs": [],
  "tax_id": null,
  "mcc": "5812",
  "type": "merchant",
  "status": "active",
  "name": "Blue Bottle Coffee Co.",
  "description": "Specialty coffee roaster",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null
}

account.blocked

An account was blocked (deactivated).

{
  "id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "organization_id": null,
  "has_access_to_mms": false,
  "has_access_to_apple_config": false,
  "available_processor_configs": [],
  "tax_id": null,
  "mcc": "5812",
  "type": "merchant",
  "status": "blocked",
  "name": "Blue Bottle Coffee",
  "description": "Specialty coffee roaster",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null
}

account.unblocked

A blocked account was reactivated.

{
  "id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "organization_id": null,
  "has_access_to_mms": false,
  "has_access_to_apple_config": false,
  "available_processor_configs": [],
  "tax_id": null,
  "mcc": "5812",
  "type": "merchant",
  "status": "active",
  "name": "Blue Bottle Coffee",
  "description": "Specialty coffee roaster",
  "parent_account_ids": [
    "acct_0Pp1Qq2Rr3Ss4Tt"
  ],
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null
}

account.deleted

An account was deleted (soft-deleted).

{
  "id": "acct_2Nk9Lm4Pq7Rs1Tv"
}

Terminal Events

terminal.created

A new terminal was created.

{
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "name": "Front Counter \u2014 Register 1",
  "description": "Android EMV COTS device",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "mid": "445566778899",
  "tid": "TERM0001",
  "store_number": "SN-COTS-00481",
  "bin": "412345",
  "vid": null,
  "agent_bank_number": null,
  "merchant_category_code": "5812",
  "terminal_capability": "5",
  "currency_code": "USD",
  "country_code": "US",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "active",
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null,
  "merchant_name": "Blue Bottle Coffee",
  "transactions": [],
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "var_sheet": null,
  "batching": null
}

terminal.updated

A terminal's configuration was updated.

{
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "name": "Front Counter \u2014 Register 2",
  "description": "Android EMV COTS device",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "mid": "445566778899",
  "tid": "TERM0001",
  "store_number": "SN-COTS-00481",
  "bin": "412345",
  "vid": null,
  "agent_bank_number": null,
  "merchant_category_code": "5812",
  "terminal_capability": "5",
  "currency_code": "USD",
  "country_code": "US",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "active",
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null,
  "merchant_name": "Blue Bottle Coffee",
  "transactions": [],
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "var_sheet": null,
  "batching": null
}

terminal.blocked

A terminal was blocked (deactivated).

{
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "name": "Front Counter \u2014 Register 1",
  "description": "Android EMV COTS device",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "mid": "445566778899",
  "tid": "TERM0001",
  "store_number": "SN-COTS-00481",
  "bin": "412345",
  "vid": null,
  "agent_bank_number": null,
  "merchant_category_code": "5812",
  "terminal_capability": "5",
  "currency_code": "USD",
  "country_code": "US",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "blocked",
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null,
  "merchant_name": "Blue Bottle Coffee",
  "transactions": [],
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "var_sheet": null,
  "batching": null
}

terminal.unblocked

A blocked terminal was reactivated.

{
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "name": "Front Counter \u2014 Register 1",
  "description": "Android EMV COTS device",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "mid": "445566778899",
  "tid": "TERM0001",
  "store_number": "SN-COTS-00481",
  "bin": "412345",
  "vid": null,
  "agent_bank_number": null,
  "merchant_category_code": "5812",
  "terminal_capability": "5",
  "currency_code": "USD",
  "country_code": "US",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "status": "active",
  "created_at": "2026-01-15T09:30:00Z",
  "deleted_at": null,
  "updated_at": null,
  "merchant_name": "Blue Bottle Coffee",
  "transactions": [],
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "var_sheet": null,
  "batching": null
}

terminal.deleted

A terminal was deleted (soft-deleted).

{
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv"
}

Location Events

location.created

A new location was created.

{
  "id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "name": "Ferry Building",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "phone": "+14155551234",
  "email": "ferry@bluebottle.example",
  "status": "active",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "country_code": "US",
  "currency": "USD",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "metadata": null,
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": null,
  "updated_at": null,
  "deleted_at": null
}

location.updated

A location's details were updated.

{
  "id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "name": "Ferry Building Plaza",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "phone": "+14155551234",
  "email": "ferry@bluebottle.example",
  "status": "active",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "country_code": "US",
  "currency": "USD",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "metadata": null,
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": null,
  "updated_at": null,
  "deleted_at": null
}

location.blocked

A location was blocked (deactivated).

{
  "id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "name": "Ferry Building",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "phone": "+14155551234",
  "email": "ferry@bluebottle.example",
  "status": "blocked",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "country_code": "US",
  "currency": "USD",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "metadata": null,
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": null,
  "updated_at": null,
  "deleted_at": null
}

location.unblocked

A blocked location was reactivated.

{
  "id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "name": "Ferry Building",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "address": {
    "street_line1": "1500 Market St",
    "street_line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103",
    "country": "US"
  },
  "phone": "+14155551234",
  "email": "ferry@bluebottle.example",
  "status": "active",
  "processor_config_id": "pcfg_4Df7Gh1Jk8Lm",
  "country_code": "US",
  "currency": "USD",
  "terminal_id": "term_5Hj3Kl8Mn2Pq6Rt",
  "metadata": null,
  "surcharge_rate": null,
  "surcharge_confirmation_required": null,
  "surcharge_basis": null,
  "tax_rate": null,
  "tax_basis": null,
  "created_at": null,
  "updated_at": null,
  "deleted_at": null
}

location.deleted

A location was deleted (soft-deleted).

{
  "id": "loc_7Bd4Cf9Gh2Jk5Lm",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv"
}

API Key Events

api_key.created

A new API key was issued.

{
  "id": "key_1Ab2Cd3Ef4Gh5Ij",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "name": "Production integration",
  "status": "active",
  "key": "****4x9Q",
  "key_last4": "4x9Q",
  "expires_at": null,
  "created_at": "2026-01-15T09:30:00Z"
}

api_key.revoked

An API key was revoked (denied at auth until reinstated).

{
  "id": "key_1Ab2Cd3Ef4Gh5Ij",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "name": "Production integration",
  "status": "revoked",
  "key": "****4x9Q",
  "key_last4": "4x9Q",
  "expires_at": null,
  "created_at": "2026-01-15T09:30:00Z"
}

api_key.reinstated

A previously revoked API key was reinstated.

{
  "id": "key_1Ab2Cd3Ef4Gh5Ij",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "name": "Production integration",
  "status": "active",
  "key": "****4x9Q",
  "key_last4": "4x9Q",
  "expires_at": null,
  "created_at": "2026-01-15T09:30:00Z"
}

api_key.deleted

An API key was deleted.

{
  "id": "key_1Ab2Cd3Ef4Gh5Ij",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "name": "Production integration",
  "status": "deleted",
  "key": "****4x9Q",
  "key_last4": "4x9Q",
  "expires_at": null,
  "created_at": "2026-01-15T09:30:00Z"
}

Credential Events

credential.created

A new merchant credential was created.

{
  "id": "cred_7Kl8Mn9Op0Qr1St",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "code": "bluebottle-ferry",
  "pin": "****",
  "is_active": true,
  "created_at": "2026-01-15T09:30:00Z"
}

credential.blocked

A merchant credential was blocked (deactivated).

{
  "id": "cred_7Kl8Mn9Op0Qr1St",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "code": "bluebottle-ferry",
  "pin": "****",
  "is_active": false,
  "created_at": "2026-01-15T09:30:00Z"
}

credential.unblocked

A blocked merchant credential was reactivated.

{
  "id": "cred_7Kl8Mn9Op0Qr1St",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "code": "bluebottle-ferry",
  "pin": "****",
  "is_active": true,
  "created_at": "2026-01-15T09:30:00Z"
}

credential.deleted

A merchant credential was deleted.

{
  "id": "cred_7Kl8Mn9Op0Qr1St",
  "account_id": "acct_2Nk9Lm4Pq7Rs1Tv",
  "code": "bluebottle-ferry",
  "pin": "****",
  "is_active": false,
  "created_at": "2026-01-15T09:30:00Z"
}

Event Processing

Identifying the event

Because the event type is not in the body, don't switch on a body field. Instead:

  1. Recommended — subscribe per event type. Point one endpoint at each event type (or category) you care about in the developer portal. The endpoint's URL then tells you what it received.
  2. In-body discriminators. Transactions carry transaction_type + status; batches carry status. Lifecycle events for accounts, terminals, locations, API keys, and credentials do not carry the verb in the body (terminal.created and terminal.updated have identical shapes), so rely on the endpoint subscription for those.

Idempotency

Delivery is at-least-once — the same message may arrive more than once (e.g. on retry). Deduplicate on the svix-id header: it is the canonical delivery id and stays constant across every retry of a message, so it's the key to track processed events (store it, e.g. in Redis with a 24-hour expiry, and skip anything you've already seen).

The transaction event_id field is a separate, application-level correlation id for the underlying transaction event — useful for tying a webhook back to a transaction, but not the delivery-dedup key.

Event ordering

Events are generally delivered in the order they occurred, but retries can cause out-of-order delivery. Use the timestamps in the payload / svix-timestamp header if you need strict ordering.

Event filtering

Configure filters per endpoint in the developer portal:

  • Event type — subscribe to specific event types (recommended for production).
  • Transaction type — branch on transaction_type (sale, auth, capture, refund, reverse, tip_adjust, incremental_auth).
  • Status — branch on status (authorized, captured, declined, refunded, reversed, …).
  • Processor — branch on processor (tsys, payroc, …).

Complete Event List

Event Description Category
transaction.authorize Card authorized — funds held, not yet captured. transaction
transaction.sale Sale — card authorized and captured in one step. transaction
transaction.capture A prior authorization was captured for settlement. transaction
transaction.cancel Transaction cancelled before settlement. transaction
transaction.create A transaction record was created. transaction
transaction.reverse Authorization voided/undone after auth, before settlement. transaction
transaction.refund Funds refunded to the cardholder after settlement. transaction
transaction.increment An existing authorization amount was increased (incremental auth). transaction
transaction.tip_adjust A tip was added or changed on a captured transaction. transaction
batch.opened A settlement batch was opened. batch
batch.rejected The processor rejected the batch. batch
batch.accepted The processor accepted the batch for settlement. batch
batch.partially_accepted The processor accepted the batch with some rejected records. batch
batch.edited A batch's transactions were edited before close. batch
batch.submitted A batch was submitted to the processor for settlement. batch
account.created A new account was created. account
account.updated An account's details were updated. account
account.blocked An account was blocked (deactivated). account
account.unblocked A blocked account was reactivated. account
account.deleted An account was deleted (soft-deleted). account
terminal.created A new terminal was created. terminal
terminal.updated A terminal's configuration was updated. terminal
terminal.blocked A terminal was blocked (deactivated). terminal
terminal.unblocked A blocked terminal was reactivated. terminal
terminal.deleted A terminal was deleted (soft-deleted). terminal
location.created A new location was created. location
location.updated A location's details were updated. location
location.blocked A location was blocked (deactivated). location
location.unblocked A blocked location was reactivated. location
location.deleted A location was deleted (soft-deleted). location
api_key.created A new API key was issued. api_key
api_key.revoked An API key was revoked (denied at auth until reinstated). api_key
api_key.reinstated A previously revoked API key was reinstated. api_key
api_key.deleted An API key was deleted. api_key
credential.created A new merchant credential was created. credential
credential.blocked A merchant credential was blocked (deactivated). credential
credential.unblocked A blocked merchant credential was reactivated. credential
credential.deleted A merchant credential was deleted. credential

See also

  • Setting up Webhooks — configuring endpoints, event subscriptions, and signature verification
Previous
Setting up Webhooks
Next
PIN Validation