Payment Lifecycle

Implementing a reliable payment process requires understanding how transactions flow through different states and how to handle each state appropriately. This guide explains Shuttle's transaction types, their possible states, and best practices for handling them.

Transaction Types

Shuttle supports three primary transaction types:

Additional transaction types that follow from the primary ones:

• Capture: Collects funds from a previous authorization (can be refunded)
• Void: Cancels a previous authorization
• Refund: Returns funds from a previous payment or capture

Transaction States

Every transaction in Shuttle can exist in one of three states:

• Successful: The transaction completed successfully. For payments and captures, funds have been secured.
• Unsuccessful: The transaction was declined or failed for a specific reason.
• Pending: The transaction is still in progress and requires additional time or action before resolving to either successful or unsuccessful. Shuttle uses two distinct pending statuses:
  • PENDING: Will be progressed automatically by the payment processor
  • UNRESOLVED: Requires user intervention (e.g., merchant approval in fraud tool)

Transaction State Flow

The diagram below illustrates how transactions move through different states and the appropriate actions to take at each stage:

flowchart LR
  A[Payment Initiated] --> B{Initial Status?}
  B -->|Success| C[Confirm order]
  B -->|Declined| D[Inform user]
  B -->|Pending| E[Show processing]
  
  E -->|Webhook Received| F{Final Status?}
  F -->|Success| G[Confirm order & notify user]
  F -->|Declined| H[Notify user, offer retry options]

Understanding Pending Transactions

Pending transactions are a critical part of the payment lifecycle that require special handling in your integration. A transaction may be pending for various reasons:

Common Causes for Pending Status

• Processing Delay: Some payment methods like ACH/BACS may take days to clear
• Manual Review: Transactions flagged by fraud tools requiring merchant intervention

Handling Pending Transactions

1. Initial Response: When a transaction returns with a pending status, inform the user that their payment is being processed
2. Order Status: Consider creating an "awaiting payment confirmation" status in your order system
3. Webhook Listeners: Implement webhook handlers to receive updates when pending transactions resolve
4. Automated Actions: Configure your system to trigger appropriate actions when a transaction status changes:
   • Success → Confirm order, trigger fulfillment, send confirmation email
   • Declined → Notify user, provide retry options, update order status

Integration Options and Handling Flows

Shuttle's Checkout Component

When using Shuttle's checkout component in your user experience:

• Your platform receives a JavaScript notification PAYMENT_SUCCESS (or redirects to the success_url) for BOTH successful and pending transactions (check status field to follow the appropriate flow)
• Declines are managed within the checkout UI (retry options presented to the customer)

Using Shuttle's API Directly

When integrating directly with Shuttle's API:

• Your platform must handle all transaction states (SUCCESS, DECLINED, PENDING, UNRESOLVED - treat both PENDING and UNRESOLVED as pending)
• You need to implement appropriate user journeys for each state, both at time of API response, and upon webhook notification

Best Practices for Robust Payment Processing

1. Always check transaction status before proceeding with order fulfillment
2. Implement webhook handlers for all transaction types
3. Design for asynchronous resolution of pending transactions
4. Provide clear user communication about transaction status
5. Provide the user with next steps for failed asynchronous transactions
6. Test all transaction states in your sandbox environment, you can use the sandbox gateway (see "Developer Options" -> Pending -> Seconds, to a value > 0 eg 600 for 10 minutes)

Decline Types

When a payment or authorization transaction is declined, Shuttle provides detailed information about the type of decline through the field gateway_status. Understanding these decline categories helps you provide appropriate guidance to your users:

When implementing your own payment UI (rather than using Shuttle's checkout component), you should inspect the gateway_status field to determine the appropriate message and next steps to present to your users. This helps guide them toward successful payment completion rather than simply informing them of a generic decline.

API Reference

For detailed information on implementing payment flows and handling transaction states, see the Payments API Reference.