payload-billing/docs/test-provider-example.md

Advanced Test Provider Example

The advanced test provider allows you to test complex payment scenarios with an interactive UI for development purposes.

Basic Configuration

import { billingPlugin, testProvider } from '@xtr-dev/payload-billing'

// Configure the test provider
const testProviderConfig = {
  enabled: true, // Enable the test provider
  defaultDelay: 2000, // Default delay in milliseconds
  baseUrl: process.env.PAYLOAD_PUBLIC_SERVER_URL || 'http://localhost:3000',
  customUiRoute: '/test-payment', // Custom route for test payment UI
  testModeIndicators: {
    showWarningBanners: true, // Show warning banners in test mode
    showTestBadges: true, // Show test badges
    consoleWarnings: true, // Show console warnings
  }
}

// Add to your payload config
export default buildConfig({
  plugins: [
    billingPlugin({
      providers: [
        testProvider(testProviderConfig)
      ]
    })
  ]
})

Custom Scenarios

You can define custom payment scenarios:

const customScenarios = [
  {
    id: 'quick-success',
    name: 'Quick Success',
    description: 'Payment succeeds in 1 second',
    outcome: 'paid' as const,
    delay: 1000,
    method: 'creditcard' as const
  },
  {
    id: 'network-timeout',
    name: 'Network Timeout',
    description: 'Simulates network timeout',
    outcome: 'failed' as const,
    delay: 10000
  },
  {
    id: 'user-abandonment',
    name: 'User Abandonment',
    description: 'User closes payment window',
    outcome: 'cancelled' as const,
    delay: 5000
  }
]

const testProviderConfig = {
  enabled: true,
  scenarios: customScenarios,
  // ... other config
}

Available Payment Outcomes

• paid - Payment succeeds
• failed - Payment fails
• cancelled - Payment is cancelled by user
• expired - Payment expires
• pending - Payment remains pending

Available Payment Methods

• ideal - iDEAL (Dutch banking)
• creditcard - Credit/Debit Cards
• paypal - PayPal
• applepay - Apple Pay
• banktransfer - Bank Transfer

Using the Test UI

1. Create a payment using the test provider
2. The payment will return a paymentUrl in the provider data
3. Navigate to this URL to access the interactive test interface
4. Select a payment method and scenario
5. Click "Process Test Payment" to simulate the payment
6. The payment status will update automatically based on the selected scenario

React Components

Use the provided React components in your admin interface:

import { TestModeWarningBanner, TestModeBadge, TestPaymentControls } from '@xtr-dev/payload-billing/client'

// Show warning banner when in test mode
<TestModeWarningBanner visible={isTestMode} />

// Add test badge to payment status
<div>
  Payment Status: {status}
  <TestModeBadge visible={isTestMode} />
</div>

// Payment testing controls
<TestPaymentControls
  paymentId={paymentId}
  onScenarioSelect={(scenario) => console.log('Selected scenario:', scenario)}
  onMethodSelect={(method) => console.log('Selected method:', method)}
/>

API Endpoints

The test provider automatically registers these endpoints:

• GET /api/payload-billing/test/payment/:id - Test payment UI
• POST /api/payload-billing/test/process - Process test payment
• GET /api/payload-billing/test/status/:id - Get payment status

Development Tips

1. Console Warnings: Keep consoleWarnings: true to get notifications about test mode
2. Visual Indicators: Use warning banners and badges to clearly mark test payments
3. Custom Scenarios: Create scenarios that match your specific use cases
4. Automated Testing: Use the test provider in your e2e tests for predictable payment outcomes
5. Method Testing: Test different payment methods to ensure your UI handles them correctly

Production Safety

The test provider includes several safety mechanisms:

• Must be explicitly enabled with enabled: true
• Clearly marked with test indicators
• Console warnings when active
• Separate endpoint namespace (/payload-billing/test/)
• No real payment processing

Important: Never use the test provider in production environments!