payment-providers

Payment Provider Integration Best Practices

Field Consistency and Data Mapping

Database Field Usage

• ALWAYS store order IDs in both orderId and processorOrderId fields during import for maximum compatibility
• NEVER assume a single field will contain the data - different providers may use different conventions
• Use consistent field naming patterns across all providers in src/server/providers/

Provider Import Methods

When implementing importPayments() in provider classes:

// ✅ CORRECT: Store in both fields
await db.insert(payments).values({
  orderId: processorOrderId,           // For display compatibility
  processorOrderId: processorOrderId,  // For provider-specific operations
  // ... other fields
});

// ❌ WRONG: Only storing in one field
await db.insert(payments).values({
  processorOrderId: processorOrderId,  // Missing orderId for display
  // ... other fields
});

Service Layer Display Logic

In src/server/services/payment-service.ts, always implement fallback logic:

// ✅ CORRECT: Fallback logic
orderId: payment.orderId || payment.processorOrderId || "",

// ❌ WRONG: Single field dependency
orderId: payment.orderId ?? "",

Provider Integration Patterns

Required Provider Methods

Every payment provider must implement consistent data mapping:

• getAllOrders() - Must include proper order ID mapping
• getOrdersByEmail() - Must use same mapping as getAllOrders
• importPayments() - Must store data in compatible database fields
• handleWebhookEvent() - Must use consistent field mapping

Data Validation

• ALWAYS validate that imported data contains expected fields
• ALWAYS test the complete data flow: Provider API → Import → Database → Service → UI
• NEVER assume provider APIs return data in expected formats

Error Handling

• Log detailed information when field mapping fails
• Provide meaningful fallback values for missing data
• Document which fields are required vs optional for each provider