PSP Integration Checklist

This document outlines the technical requirements and scope for integrating additional payment gateways (PSPs)into the Shuttle platform. It serves as a guide for understanding what information we need from PSP partners and what capabilities we will implement.

We don't expect all requirements to be met, but we will implement the ones that are.

Integration Standards

Shuttle maintains strict quality standards for all gateway integrations:

All features must be production-ready (beta features will not be implemented)
Implementations must avoid excessive workarounds that compromise reliability
Behavior must be consistent with other gateway integrations on our platform
Performance must meet our SLA requirements with acceptable failure rates

We may disable features that consistently fail to meet these standards.

1. Authentication & Connectivity

Authentication Methods

We need to understand your authentication approach. Please specify which method your gateway uses:

OAuth 2.0 (our preferred method for better security and user experience)
API Key/Credentials (static credentials)
Other authentication methods (please provide details)

Environment Requirements

Our integration must support both live and sandbox environments. We need:

Live environment access for production transactions
Sandbox environment access for testing and development
Sandbox access details: Please specify if sandbox uses different API endpoints, requires separate credentials, or has unique access requirements

Connection Validation

We need a method to verify that merchant credentials are both authenticated and authorized to perform payment operations. Ideally, you provide:

A dedicated API endpoint that validates authentication and payment permissions
Alternatively, a test transaction method (e.g., $0.00 authorization or specific test card numbers that always decline)

This ensures we can distinguish between authentication failures and authorization issues during merchant onboarding.

Account Information Discovery

Upon connecting a merchant account, we attempt to retrieve contextual information to streamline the integration setup. Please specify which of the following can be accessed via API and the endpoints/methods to retrieve them:

Merchant account name or business name
Supported currencies for the account
Accepted card types and brands
Risk management settings (AVS, 3DS requirements)
Account capabilities and restrictions

2. Configuration & Capability Detection

Automated Configuration

We prefer to automatically detect merchant account capabilities via API. This includes:

Payment methods supported: Which payment types are enabled (cards, ACH, SEPA, etc.)
Currency support: Available currencies for transactions
Risk settings: Which security features are enabled (3D Secure, AVS, CVV verification)
Field requirements: Required vs optional fields for each payment type
Transaction limits: Any restrictions on amounts or transaction types

Manual Configuration Fallback

When automated detection isn't available, we'll implement configuration screens allowing merchants to manually specify:

Supported payment methods and currencies
Risk management preferences
Optional feature toggles

Merchant-Configurable Options

Please specify any settings that merchants can configure:

If AVS should be applied
3D Secure triggers and exemption rules
Other gateway-specific preferences

3. Payment Flow Implementation

All payment flows must be accessible via both our REST API and web checkout interface.

Card Payment Processing

Integration Methods

Shuttle is PCI DSS Level 1 and prefer an integration passing RAW PAN for a better user experience and broader platform compatibility. However, we can implement iFrame integration if required. Please specify:

Your preferred integration method
Any PCI compliance requirements
Browser compatibility considerations

Note: Processors that do not allow RAW PAN will not be available in some platforms, for example Twilio IVR payments.

Transaction Types Required

Our platform needs to support, please flag any issues with the following transaction types:

Ecommerce: Card-not-present transactions
MOTO: Mail Order/Telephone Order transactions
Scheduled: Merchant-initiated transactions (submitted as MIT Unscheduled)

Core Payment Operations

We will implement the following payment flows:

Standard Payments
- Direct payment processing
- Payment with simultaneous card tokenization
- Payment using previously saved tokens
Authorization Flows
- Authorization-only transactions
- Authorization with card tokenization
- Authorization using saved tokens
Post-Authorization Operations
- Full capture of authorizations
- Partial capture support
- Void/cancellation before settlement
Refund Operations
- Full refunds
- Partial refunds
- Multiple partial refunds (within original amount)

Advanced Card Features

Tokenization: Store card details for future use (both Ecommerce and MOTO)
3D Secure 2: Implementation approach (iFrame, field collection, or JavaScript injection)
AVS: Address Verification System support
Network Tokens: Support for decrypted network tokens
Digital Wallets: Note, Apple Pay and Google Pay will be implemented via network tokens

ACH Payment Processing

For ACH transactions, we need to:

Collect account type, routing number, and account number
Submit via your API
Support full and partial refunds
Enable tokenization for recurring use

SEPA Payment Processing

For SEPA transactions, we need to:

Collect and validate IBAN
Submit via your API
Support full and partial refunds
Enable tokenization for recurring use

Hosted Payment Solutions

If certain payment methods require a hosted experience, we can implement:

Single-button redirect to your hosted payment page
Return URL handling for completed transactions
Support for refunds and tokenization of hosted payments

4. Data Requirements & Response Handling

Transaction Data Submission

We will send the following data with each transaction:

Required Fields

Transaction Reference: Unique ID generated by Shuttle for each payment attempt
Order Reference: Merchant's order/basket ID (may not be unique)
Order Description: Brief description (e.g., "Ticket Sales")
Billing Address: Sent when AVS is enabled
Customer IP Address: For fraud prevention

Optional Fields (when available)

Customer details (name, email, phone)
Shipping information
Line items/basket contents

Response Mapping

We need to map all possible gateway responses to our standardized status codes:

APPROVED: Transaction successful
PENDING: Payment in progress or held for review
DECLINED: Validation error requiring customer action
DECLINED_BLOCK: Card/account blocked
DECLINED_CALL_BANK: Bank contact required (e.g., insufficient funds)
DECLINED_RETRY: Temporary issue, retry permitted
DECLINED_ERROR: Configuration/merchant error
UNRESOLVED: Status unknown due to upstream error

Please provide your response codes and their meanings for accurate mapping.

Financial Data Extraction

From transaction responses, we need to extract (where available):

Settlement currency
Processing fees
Net settlement amount
Detailed error messages
Gateway-specific metadata

5. Resilience & Event Management

Webhook Requirements

We prefer webhook notifications for:

Payment status updates (approved, declined, pending resolution)
Refund confirmations
Chargeback notifications (recorded as refunds with notation)

Our webhook handling will:

Ignore transactions not initiated through Shuttle
Track external captures/refunds for Shuttle-initiated transactions
Process status updates for pending transactions

Polling Fallback

If webhooks aren't available, we'll implement polling for:

Pending transaction status updates
Settlement confirmation

6. Conditional Features

These features are only implemented when they're core to your gateway's value proposition:

Buy Now, Pay Later (BNPL)

If BNPL is a primary offering (ie its your branded BNPL product), we can integrate:

Credit line or individual purchase financing
Marketing messages for product, basket, and checkout pages
BNPL-specific workflows

Express Checkout

For express checkout solutions that capture customer, shipping, and payment data from the basket page.

7. Governance & Compliance

Security Requirements

As a PCI DSS Level 1 certified payment service provider, Shuttle requires all integrated gateways to maintain equivalent security standards:

PCI DSS Level 1 Certification: Your gateway must maintain current PCI DSS Level 1 certification
Annual AOC Submission: We require an updated Attestation of Compliance (AOC) annually
Data Security Agreement: We need either:
- A formal contract outlining data security responsibilities
- A written statement confirming your commitment to securing payment details transmitted through your gateway - typically a statement to this affect on your T&Cs is sufficient

Testing Documentation

For sandbox environment testing, please provide:

Test Card Numbers: A comprehensive list of test cards for different scenarios:
- Successful transactions
- Various decline reasons
- 3D Secure test cases
- Network-specific test cards (Visa, Mastercard, Amex, etc.)
Test Data Documentation: Any other test credentials or data needed for comprehensive testing
Sandbox Limitations: Any differences between sandbox and production behavior

8. Scope Exclusions

The following are explicitly outside our integration scope:

Third-party wallets with direct customer relationships (PayPal, Klarna accounts)
Unmatched refunds exceeding original transaction amounts
Gateway-managed recurring billing (we handle scheduling internally)
Customer receipts (managed by merchant platforms)
Chargeback dispute workflows
Authorization extensions beyond initial authorization period