Webhooks Management

Split tender transactions require special handling of webhooks to ensure merchants receive complete and accurate information about the transaction. This document outlines how webhooks are managed for split tender payments.

Consolidated Transaction Approach

• A single webhook payload represents the entire transaction with detailed status information for both payment components
• The consolidated approach reduces webhook volume while maintaining transaction integrity

Transaction Status Logic

• Component-Level Statuses: Each payment component has its own individual status
• Transaction-Level Status: Determined by a cascading ruleset:
  • If any component is FAILED → Transaction status is FAILED
  • All components must be COMPLETED for transaction status to be COMPLETED

Webhook Triggering Based on Transaction Status

Webhooks for split tender transactions are triggered according to the overall transaction status, which is determined by the statuses of the individual payment components. The key rules are:

• PAYMENT_SUCCEEDED: A webhook is sent when all payment components are successfully completed. The transaction status is set to COMPLETED, and a PAYMENT_SUCCEEDED event is triggered.
• PAYMENT_FAILED: If any payment component fails, a webhook is sent with the transaction status set to FAILED. The PAYMENT_FAILED event is triggered, and the webhook includes detailed status and error information for each component.
• PAYMENT_AUTHORIZED will be sent only for CARD + CARD transactions in the Pre-Authorization (Pre_AUTH) flow. This event indicates that both card components have been successfully authorized, but the transaction is not yet finalized.
• PAYMENT_ACCEPTED will be sent when both ACH components are accepted in ACH + ACH transactions, or in CARD + ACH transactions when the card is authorized and the ACH is accepted. This event provides early notification that the payment process has started, but does not guarantee final success.
• PAYMENT_CANCELLED: If all components are cancelled (e.g., by merchant action), a webhook is sent with the transaction status set to CANCELLED and a PAYMENT_FAILED event, with both payment statuses marked as CANCELLED.

Merchants should use the transaction status and individual payment statuses in the webhook payload to determine the appropriate next steps for order processing and reconciliation.

Lifecycle Event Webhooks

Transaction Webhooks

Transaction Webhook Events

PAYMENT_FAILED

PAYMENT_FAILED event is not final if another attempt is made with the same merchant transaction id. It is only final when no further attempts are possible.

Event Name	Card + Card: Pre-AUTH	Card + Card: Sale	ACH + ACH: Sale	Card + ACH: Sale
PAYMENT_AUTHORIZED	✅ Intermediate	❌	❌	❌
PAYMENT_SUCCEEDED	✅ Final	✅ Final	✅ Final	✅ Final
PAYMENT_ACCEPTED	❌	❌	✅ Intermediate	✅ Intermediate
PAYMENT_FAILED	✅ Intermediate/Final*	✅ Intermediate/Final*	✅ Intermediate/Final*	✅ Intermediate/Final*
PAYMENT_CANCELLED	✅ Final	❌	❌	❌

Refund Webhooks

Refund Webhook Events

Event Name	Refund Transaction Status	Payment 1	Payment 2
REFUND_SUCCESS	✅ COMPLETED	✅ COMPLETED	✅ COMPLETED
REFUND_PARTIAL_SUCCESS	✅ PARTIAL_COMPLETED	❌ FAILED	✅ COMPLETED
REFUND_FAILURE	✅ COMPLETED	❌ FAILED	❌ FAILED
REFUND_FAILURE	⏳ PENDING	⏳ PENDING	⏳ PENDING

Webhook Combinations by PaymentMethod and PaymentType

Card + Card (Parallel Processing)

✅ SUCCESS SCENARIOS

Payment 1	Payment 2	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
AUTHORIZED	AUTHORIZED	PENDING	SALE	NA	NA	NA
COMPLETED	COMPLETED	COMPLETED	SALE	PAYMENT_SUCCEEDED	COMPLETED	COMPLETED

✅ PRE-AUTH SPECIFIC WEBHOOKS

warning

• PAYMENT_CANCELLED event will be triggered when both the payments are CANCELLED by merchant

Payment 1	Payment 2	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
AUTHORIZED	AUTHORIZED	AUTHORIZED	PRE-AUTH	PAYMENT_AUTHORIZED	AUTHORIZED	AUTHORIZED
CANCELLED	CANCELLED	CANCELLED	PRE-AUTH	PAYMENT_CANCELLED	CANCELLED	CANCELLED

❌ FAILURE/CANCELLED SCENARIOS

warning

• For PAYMENT_FAILED event, when any one of the Payment Status is Cancelled
  • cancellationReason and cancellationMessage will include information about CCG Rollback

Payment 1	Payment 2	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
AUTHORIZED	FAILED	FAILED	SALE	PAYMENT_FAILED	CANCELLED	FAILED
FAILED	FAILED	FAILED	SALE	PAYMENT_FAILED	FAILED	FAILED

Card + ACH (Sequential Processing)

✅ SUCCESS SCENARIOS

Payment 1 (Card)	Payment 2 (ACH)	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
AUTHORIZED	ACCEPTED	ACCEPTED	SALE	PAYMENT_ACCEPTED	AUTHORIZED	ACCEPTED
COMPLETED	COMPLETED	COMPLETED	SALE	PAYMENT_SUCCEEDED	COMPLETED	COMPLETED

❌ FAILURE/CANCELLED SCENARIOS

warning

• For PAYMENT_FAILED event, when any one of the Payment Status is CANCELLED
  • cancellationReason and cancellationMessage will include information about CCG Rollback

Payment 1 (Card)	Payment 2 (ACH)	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
FAILED	NA	FAILED	SALE	PAYMENT_FAILED	FAILED	NA
AUTHORIZED	FAILED	FAILED	SALE	PAYMENT_FAILED	CANCELLED	FAILED

ACH + ACH (Parallel Processing)

✅ SUCCESS SCENARIOS

Payment 1	Payment 2	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
ACCEPTED	ACCEPTED	ACCEPTED	SALE	PAYMENT_ACCEPTED	ACCEPTED	ACCEPTED
COMPLETED	COMPLETED	COMPLETED	SALE	PAYMENT_SUCCEEDED	COMPLETED	COMPLETED

❌ FAILURE/CANCELLED SCENARIOS

warning

• For PAYMENT_FAILED event, when any one of the Payment Status is REFUNDED
  • refundReason or metadata will include information about CCG Rollback

Payment 1	Payment 2	Transaction Status	Payment Type	Webhook Event	Webhook Payment 1 Status	Webhook Payment 2 Status
FAILED	COMPLETED	FAILED	SALE	PAYMENT_FAILED	FAILED	REFUNDED
FAILED	FAILED	FAILED	SALE	PAYMENT_FAILED	FAILED	FAILED

Error Handling in Webhooks

• For failed components, detailed error codes and descriptions are provided
• Merchants should examine both the parent transaction status and individual payment statuses

Important

Merchants must properly handle webhooks for split tender transactions to ensure accurate order processing and financial reconciliation. Failing to properly process these webhooks may result in orders being incorrectly marked as paid or unpaid.