Collect

Getting Started with Collect

Accept payments across 20+ markets through one unified API

The CrissCross Collect API enables you to accept payments from customers across 20+ markets in Africa and the Middle East through a single, unified interface. As your merchant of record, CrissCross handles all payment provider relationships, domestic acquiring, and compliance, allowing you to accept payments without registering with individual providers.

Key Features

  • Unified API: Accept payments across multiple payment methods and regions through one integration
  • Merchant of Record: CrissCross handles all payment provider relationships, so you can accept payments without registering with individual providers
  • 20+ Market Coverage: Accept payments across 20+ markets in Africa and the Middle East
  • Multiple Payment Methods: Support for cards, mobile money, bank transfers, and region-specific payment methods
  • Intelligent Routing: Automatic failover and intelligent routing to optimize transaction success rates
  • Hosted Checkout: Optional hosted checkout solution that handles the entire payment flow
  • Real-time Status Updates: Monitor payment status through webhooks and polling

Core Concepts

1. Checkout Sessions

A checkout session represents a payment intent and contains the details needed to process a payment. Sessions can be created for hosted or direct integrations and include information about the amount, currency, payer details, and payment preferences.

  • Create Session: Use POST /v1/checkout/session to create a checkout session
  • Get Session: Retrieve session details using GET /v1/checkout/session
  • Session Lifecycle: Sessions can be used to initiate payments and track the payment flow

2. Payments (Transactions)

In CrissCross, a payment is modeled as a transaction. Each transaction represents a complete payment attempt and can include multiple payment attempts if retries are required.

  • Initiate Payment: Use POST /v1/payment to initiate a payment transaction
  • Poll Status: Use GET /v1/payment/{transactionId} to check transaction status
  • List Payments: Use GET /v1/payment?merchantIds=... with cursor-based pagination (nextCursor / backCursor)
  • Authorize: Use POST /v1/payment/authorize when additional authorization is required

Integration Methods

CrissCross offers three integration approaches to suit different needs:

1. Hosted Checkout

The simplest integration method where CrissCross handles the entire payment flow:

  • Minimal Development: Redirect customers to a CrissCross-hosted checkout page
  • Automatic Payment Method Display: Payment methods are automatically shown based on customer location
  • Low Compliance Burden: CrissCross handles PCI compliance and security requirements

2. Secure Fields

A middle-ground approach that provides more control while maintaining low compliance:

  • Custom UI: Build your own checkout UI while using CrissCross’s secure field components
  • Tokenization: Payment details are tokenized before reaching your server
  • Reduced PCI Scope: Minimize your PCI compliance requirements

3. Direct API Integration

Full control over the payment experience:

  • Complete Customization: Build a fully custom checkout experience
  • Server-to-Server: Handle all payment logic on your backend
  • Maximum Flexibility: Ideal for complex payment flows or unique requirements

Workflow Overview

The typical Collect payment flow follows these steps:

  1. Create Checkout Session: Use POST /v1/checkout/session to create a session with payment details
  2. Get Available Methods (optional): Use GET /v1/payment/available-methods to see which payment methods are available
  3. Initiate Payment: Use POST /v1/payment to initiate the transaction with the selected payment method
  4. Handle Authorization (if needed): If the response includes an authState, follow the required steps (e.g., redirect) and use POST /v1/payment/authorize
  5. Poll Status: Use GET /v1/payment/{transactionId} to check transaction status, or rely on webhooks for real-time updates
  6. Process Refunds (if needed): Use the refund endpoints to process full or partial refunds

Supported Payment Methods

CrissCross supports payment methods across 20+ markets:

  • Card Payments: Visa, Mastercard, and other major card networks
  • Mobile Money: M-Pesa (Kenya, Tanzania, etc.), MTN MoMo, Airtel Mobile Money
  • Bank Transfers: Instant EFT, bank transfers, and direct debit
  • Regional Methods: Pay By Bank (South Africa), and other market-specific solutions

Payment methods are automatically configured based on your account settings and the customer’s location.

Supported Currencies and Markets

Collect supports payments in multiple currencies across Africa and the Middle East:

  • Fiat Currencies: USD, EUR, NGN (Nigeria), KES (Kenya), ZAR (South Africa), GHS (Ghana), XOF (West Africa), XAF (Central Africa), EGP (Egypt), TZS (Tanzania), MZN (Mozambique), ZMW (Zambia), UGX (Uganda), and more

Authentication

All Collect API requests require OAuth 2.0 authentication. You obtain an access token by calling the Authentication endpoint with your merchantId and clientSecret, then include the token in the Authorization: Bearer ... header on subsequent requests.

For detailed authentication instructions, see the Authentication guide.

Next Steps

  1. Set Up Your Account: Complete account setup and enable the payment methods you want to offer
  2. Choose Integration Method: Select Hosted Checkout, Secure Fields, or Direct API Integration based on your needs
  3. Configure Payment Rules: Set up routing rules and preferences in the CrissCross dashboard
  4. Test Your Integration: Use the sandbox environment to test your integration before going live
  5. Go Live: Once testing is complete, contact your account manager to enable production access

For detailed integration guides, see: