> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/glossary/webhooks-and-outcomes.md). # Webhooks and outcomes Definitions of payment outcomes, processing states, webhook delivery, and verification terms used by the API. These terms describe processing results and the notifications used to keep the ISV's backend informed. A request result, a payment decision, and a settlement record answer different questions. ## Acceptance and asynchronous processing Acceptance means the payment system has received an instruction and agreed to process it. Asynchronous processing means the final outcome becomes available after the initiating API call or browser response. An accepted ACH transfer can return `resultCode: 0` and `status: Processing` while bank settlement remains pending. See [The ACH lifecycle](/payments/ach.md#the-asynchronous-lifecycle). ## Acknowledgement A receiver's confirmation that it has accepted a message. For webhooks, your endpoint acknowledges a verified event by returning a successful HTTP response after saving it durably. This tells the delivery service that the event was received; it does not tell the customer whether a payment was approved. `Acknowledged` is also a transaction lifecycle state for an initial gateway response. ## Approval A processing decision that permits the requested payment operation for an indicated amount. Transaction responses report approval with `responseCode: 1` and partial approval with `responseCode: 2`. An approved authorization still needs capture, and a payment approval does not establish that a merchant deposit has occurred. ## Decline A payment outcome in which the issuer, bank, terminal, or processing system does not approve the operation. `transactionResponses[].responseCode` reports the decision, with `10` for a general decline and other codes for specific causes. A declined transaction can have lifecycle `status: Completed` because processing finished. There is no `Declined` transaction lifecycle state. ## Deduplication and idempotency Deduplication is detecting that the same event or operation has already been handled. For webhooks, use the payload's `event.id` so retries and dual delivery do not repeat business actions. Idempotent handling means repeated processing has the same business effect as processing once. The transaction `referenceId` supports lookup and correlation; it is not an idempotency key for payment requests. See [Deduplicate on event ID](/webhooks/webhooks.md#deduplicate-on-event-id). ## Delivery and dual delivery A webhook delivery is an HTTP attempt to send an event to a configured endpoint. Dual delivery means the same transaction or token event is sent independently through both legacy and Svix webhooks when both are configured. An event can therefore arrive through two delivery methods, as well as through retries. See [Webhooks](/webhooks/webhooks.md). ## Error code and error envelope An error code identifies a request, validation, session, or SDK failure. The standard error envelope is the JSON object containing `code`, execution `status`, `message`, `timestamp`, and optional diagnostic fields such as `traceId` or `errorDetails`. Hosted iframe error callbacks also have a legacy shape with fields such as `errorCode` and `errorMessage`. See [Errors and rate limits](/get-started/errors-and-rate-limits.md). ## Event and event type An event is a record that something happened, such as a transaction finishing, a token being created, or a merchant application changing status. The event type, such as `sale.completed`, tells a webhook consumer which kind of change the payload represents. A transaction event ending in `.completed` can describe a decline; inspect the payment result inside the payload. See [Event catalog](/webhooks/events.md). ## Event ID and message ID The event ID in `event.id` identifies the underlying business event and stays the same across delivery retries. Use it for deduplication, including when moving between legacy and Svix webhooks. A Svix message ID in `svix-id` identifies the delivery service's message and participates in signature verification; it stays constant across retries of that message. ## Execution status The standard error object's `status` reports how far request execution is known to have progressed. It helps determine whether an attempted payment could have had side effects: | Value | Definition | | ------------- | ---------------------------------------------------------------------------------------------------------- | | `Completed` | Request execution finished. Interpret the accompanying operation result to determine its business outcome. | | `Rejected` | The request was rejected before execution or by the gateway. Inspect and correct the stated cause. | | `Interrupted` | Execution was interrupted and the final outcome is unknown; a charge may already have occurred. | | `Unknown` | The service could not determine the execution outcome. | Reconcile uncertain outcomes before submitting another payment. See [Execution status and retries](/get-started/errors-and-rate-limits.md#status-is-what-tells-you-whether-to-retry). ## HMAC-SHA256 A keyed message-authentication calculation that combines message bytes and a key to produce a value the receiver can verify. Webhook verification uses it to check the sender and message integrity with an endpoint signing secret. Legacy webhooks, Svix webhooks, and hosted redirects use different inputs and keys; their verification procedures are not interchangeable. ## HTTP status The response code at the HTTP layer, such as `200`, `401`, or `429`. It describes handling of the HTTP request. A `200` response can still contain a declined transaction, so inspect the API body as well. The separate `responseCode`, `resultCode`, and `status` fields describe other parts of the outcome. See [HTTP status codes](/get-started/errors-and-rate-limits.md#http-status-codes). ## Legacy webhooks The webhook delivery method configured through Fiska support for a merchant's transaction and token events. Deliveries carry an `x-fsk-wh-chksm` HMAC-SHA256 checksum over the raw body, calculated with an endpoint's shared secret. The signature has no timestamp component. See [Legacy webhooks](/webhooks/legacy.md). ## Merchant lifecycle event A notification about a merchant application, merchant approval or rejection, or a pricing-template decision. These events let the ISV track onboarding and review progress. They use an `event` envelope and shared `data` shape, with null values for fields that do not apply. They are delivered through Svix only and are currently in beta. See [Merchant lifecycle events](/webhooks/events.md#merchant-lifecycle-events). ## Payload and envelope A payload is the structured data sent in a request, response, callback, or webhook. An envelope is the outer object that identifies or organizes that data. For example, a webhook's `event` metadata identifies the event, while an iframe message wraps its inner result in `data`. Read the shape documented for the specific delivery channel. ## Polling Repeatedly retrieving a resource to learn whether its state or result has become available. Transaction retrieval can help reconcile a missed response or webhook. A request can still be in flight before a transaction record exists, so an empty lookup is not evidence that retrying the payment is safe. See [Retrieving transactions](/payments/transaction-retrieval.md). ## Rate limit and backoff A rate limit restricts how frequently requests can be made. The API reports an exceeded limit with HTTP `429`. Backoff is a delay before another attempt; exponential backoff increases that delay after repeated failures. Honor `Retry-After` when supplied. Delaying a retry does not resolve an uncertain payment outcome. See [Rate limiting](/get-started/errors-and-rate-limits.md#rate-limiting). ## Raw body The exact bytes of an HTTP request body as received, before JSON parsing or reformatting. Webhook signatures are verified against these bytes. Parsing and re-serializing the JSON can change whitespace or ordering and make a valid signature fail verification. ## Replay and replay protection A replay is a later delivery of an event that was sent before, either through a portal action or by resending captured traffic. Replay protection uses signed timing information to reject deliveries outside an allowed time window. Svix verification checks timestamps; legacy signatures contain no time component. Deduplication on `event.id` remains necessary for events received more than once. ## Response code The numeric payment outcome on an entry in `transactionResponses`, exposed as `responseCode`. It distinguishes approval, partial approval, declines, pending results, and other processing conditions. For example, `1` means approved, `10` means declined, and `57` means an asynchronous outcome is pending. It is separate from the HTTP status and top-level `resultCode`. ## Result code and result text The transaction's `resultCode` classifies the result of processing the request, and `resultText` provides a human-readable explanation when available. A `resultCode` of `0` can accompany a decline inside `transactionResponses` or immediate ACH acceptance. Evaluate it with the response codes and lifecycle status. See [Transaction result codes](/get-started/errors-and-rate-limits.md#transaction-result-codes-are-different). ## Retry A new attempt after a delivery or request did not complete as expected. Webhook retries resend an existing event. Retrying a payment request can initiate another charge, so first resolve an interrupted or unknown attempt through authenticated retrieval, configured webhooks, or support. ## Signature, checksum, and signing secret A webhook signature or checksum is the message-authentication value sent in the delivery headers. The signing secret is the private value shared with the endpoint so the receiver can verify that signature. Legacy webhooks use `x-fsk-wh-chksm`; Svix uses `svix-id`, `svix-timestamp`, and `svix-signature`. Compare calculated values using a constant-time comparison, which avoids exposing matching prefixes through comparison timing. See [Legacy verification](/webhooks/legacy/verifying-the-checksum.md) and [Svix verification](/webhooks/svix/verifying-signatures.md). ## Success flag The browser result's `success` boolean expresses how the hosted form or SDK classified the immediate outcome. For card payments, `false` can indicate a decline or processing failure. For ACH, `true` can mean accepted for processing while settlement is still pending. Confirm the backend outcome before fulfilling an order. See [Callback payloads](/payment-sdk/responses.md). ## Svix webhooks The webhook delivery method with endpoint management, signing-secret rotation, delivery inspection, and replay in the partner portal. It supports transaction, token, and merchant lifecycle events and uses timestamped signatures. Access is currently invite only. See [Svix webhooks](/webhooks/svix.md). ## Trace ID A diagnostic identifier returned as `traceId` when available on an error. It lets support locate the processing logs for the failing request. Keep it with your error logs; use transaction IDs and references to identify payment records in API requests. ## Transaction lifecycle status The transaction request's stage of processing, exposed as `status`. It describes progress separately from approval or decline: | Value | Definition | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Unknown` | The processing stage is not known. | | `Created` | The request has been created. | | `Pending` | The request is waiting for customer interaction. | | `Submitted` | The request has been sent to the gateway and is waiting for an initial response. | | `Acknowledged` | An initial gateway response has been received. | | `Processing` | The request is still being processed. | | `AwaitingSettlement` | A bank-transfer request is waiting for the later bank outcome. | | `Completed` | Processing has finished with a result that can be approved or declined. An immediate ACH response can report this value while bank settlement is still pending. | | `Failed` | Processing stopped because of a technical issue, and the request is closed. | | `Abandoned` | The customer did not complete the flow before gateway submission, and the request was closed. | The session-creation response's `Pending` status describes the new session, not a debit result. See [The ACH lifecycle](/payments/ach.md#the-asynchronous-lifecycle) and [Retrieving transactions](/payments/transaction-retrieval.md). ## Webhook and webhook endpoint A webhook is an HTTP notification sent to the ISV's backend when a subscribed event occurs. A webhook endpoint is the URL on that backend that receives it. Webhooks operate independently of the customer's browser, can arrive more than once or out of order, and must be verified before their payloads are acted on. See [Webhooks](/webhooks/webhooks.md). ## Related * [Payments and transactions](/glossary/payments-and-transactions.md) - what each operation does * [Hosted forms and SDK](/glossary/hosted-forms-and-sdk.md) - browser notifications and sessions * [Settlement and fees](/glossary/settlement-and-fees.md) - the later deposit and charge records