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 your 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.

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. Idempotent handling means repeated processing has the same business effect as processing once.

For transaction requests, referenceId provides duplicate prevention: the API enforces uniqueness per merchant and rejects a reference already in use. Keep the same reference for retries of one operation and retrieve the existing transaction to resolve its outcome. The API does not replay the earlier response. See Preventing duplicate requests.

For webhooks, use the payload's event.id so retries and dual delivery do not repeat business actions. See 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.

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.

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.

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:

Reconcile uncertain outcomes before submitting another payment. See Execution status and retries.

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.

Legacy webhooks

The webhook delivery method configured through 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.

Merchant lifecycle event

A notification about a merchant application, merchant approval or rejection, or a pricing-template decision. These events let you 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.

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.

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.

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 is the field that tells you whether a transaction succeeded: only 1 and 2 are approvals. 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. See Transaction response codes for the full list.

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.

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 and Svix verification.

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.

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.

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:

The session-creation response's Pending status describes the new session, not a debit result. See The ACH lifecycle and Retrieving transactions.

Webhook and webhook endpoint

A webhook is an HTTP notification sent to your 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.

Related

• Payments and transactions - what each operation does
• Hosted forms and SDK - browser notifications and sessions
• Settlement and fees - the later deposit and charge records