Introduction

When offering flexible payment options to your B2B customers, Two provides two distinct approaches for splitting payments over time: Order API Instalments and Repay API Plans. While both allow customers to pay in multiple instalments, they serve different use cases and have different implementation approaches.

This guide will help you understand the key differences between these two options and choose the right one for your business model. We'll cover when to use each approach, how they work, and provide practical examples to get you started.

Quick Summary:

• Order API Instalments: Best for simple instalment scenarios on standard product orders
• Repay API Plans: Ideal for lease, rental, subscription, or complex repayment structures

Prerequisites

Before diving in, ensure you have:

• Familiarity with Two's order creation process
• Understanding of your business model and payment requirements
• Access to the appropriate Two APIs based on your chosen approach

Understanding the Two Approaches

Order API Instalments: Integrated Payment Splitting

Order API Instalments allow you to split a standard order's payment directly within the order creation process. This approach integrates instalment terms seamlessly into Two's existing order lifecycle.

Key Characteristics:

• Integration: Built into the standard order creation flow
• Simplicity: Uses familiar Order API endpoints
• Lifecycle: Follows the same fulfilment and invoicing process as standard orders

Repay API Plans: Dedicated Repayment Management

The Repay API provides a separate, specialized service for creating and managing complex repayment plans. This approach is designed for business models that require sophisticated payment structures.

Key Characteristics:

• Separation: Standalone service independent of the Order API
• Flexibility: Supports complex repayment structures and schedules
• Management: Full lifecycle management of repayment plans
• Use Cases: Optimized for lease, rental, and subscription models

When to Use Each Approach

Choose Order API Instalments When:

✅ Simple Instalment Needs

• You want to split a product purchase into equal payments
• The payment structure is straightforward (e.g., 3, 6, or 12 monthly payments)
• You prefer to keep everything within the standard order flow

✅ Standard Product Sales

• Selling physical or digital products with one-time delivery
• The order has a clear fulfilment point
• You want instalment billing to start after order fulfilment

✅ Minimal Complexity

• You don't need custom payment schedules or amounts
• Standard instalment periods (monthly, quarterly) work for your business
• You want to leverage existing Order API integrations

Example Scenarios:

• An office furniture supplier offering 6-month payment plans on desk purchases
• A software company allowing annual license fees to be paid in quarterly instalments
• An equipment vendor providing 12-month payment options for machinery

Choose Repay API Plans When:

✅ Complex Payment Structures

• You need custom payment amounts, dates, or frequencies
• Different instalments have different amounts (e.g., larger final payment)
• You require flexible scheduling beyond standard monthly/quarterly periods

✅ Lease and Rental Models

• Equipment leasing with end-of-term purchase options
• Property or vehicle rentals with ongoing payment schedules
• Service contracts with variable payment structures

✅ Subscription-Style Billing

• Ongoing service agreements with regular payments
• Maintenance contracts with scheduled instalments
• Multi-year agreements with complex payment terms

✅ Advanced Management Needs

• You need detailed control over individual instalment modifications
• Payment plans may need to be paused, modified, or extended
• You require comprehensive reporting on payment plan performance

Example Scenarios:

• A construction equipment company offering 5-year leases with balloon payments
• A SaaS provider with annual contracts paid in unequal quarterly instalments
• A vehicle leasing company with mileage-based payment adjustments

Implementation Comparison

Order API Instalments Implementation

With Order API Instalments, you include instalment terms directly in your order creation request:

What Happens Next: 1. Order is created with instalment terms 2. You fulfil the order using the standard fulfilment endpoint 3. Two automatically creates the instalment schedule 4. Buyer receives the first invoice based on the instalment plan 5. Subsequent invoices are sent according to the schedule

Repay API Plans Implementation

With the Repay API, you create a separate repayment plan:

What Happens Next: 1. Repayment plan is created independently 2. Two manages the entire payment schedule 3. Invoices are sent according to your defined schedule 4. You can modify, pause, or manage the plan through dedicated endpoints

Key Differences Summary

Technical Considerations

Order API Instalments Limitations

• Structure Constraints: Limited to predefined instalment patterns
• Order Dependency: Instalment billing tied to order fulfilment
• Modification Limits: Changes follow standard order modification rules

Repay API Advantages

• Full Control: Complete flexibility over payment structures
• Independent Management: Not tied to order fulfilment cycles
• Advanced Features: Plan modifications, extensions, and detailed reporting
• Scalability: Better suited for high-volume, complex payment scenarios

Integration Effort

Order API Instalments: Lower integration effort if you already use the Order API Repay API Plans: Higher initial setup but more powerful for complex scenarios

Best Practices

For Order API Instalments:

1. Keep It Simple: Use for straightforward, equal-payment scenarios
2. Plan Ahead: Ensure your instalment terms align with your commercial agreement with Two
3. Clear Communication: Make instalment terms clear to buyers at checkout

For Repay API Plans:

1. Design First: Plan your payment structures before implementation
2. Error Handling: Implement robust error handling for plan management
3. Monitoring: Set up monitoring for payment plan performance
4. Documentation: Maintain clear documentation of your payment structures

Migration Considerations

If you're considering moving from one approach to another:

From Order API to Repay API:

• More development work required
• Greater flexibility and control
• Better for growing complexity

From Repay API to Order API:

• Simpler implementation
• Less flexibility
• Only suitable if your needs have simplified

Conclusion

Both Order API Instalments and Repay API Plans offer valuable ways to provide flexible payment options to your B2B customers. The choice between them depends on your business model, complexity requirements, and integration preferences.

Choose Order API Instalments for simple, product-based instalment scenarios where you want to keep everything within the standard order flow.

Choose Repay API Plans for complex payment structures, lease/rental models, or when you need advanced payment plan management capabilities.

Remember that these approaches can complement each other - you might use Order API Instalments for simple product sales and Repay API Plans for your lease offerings.

For specific questions about which approach is right for your use case, or to request access to Order API Instalments, please reach out to your Two account manager or our support team.

Next Steps

• Review the Order API documentation for instalment implementation details
• Explore the Repay API documentation for repayment plan options
• Contact Two support to discuss your specific payment structure requirements
• Test your chosen approach in the sandbox environment before going live