> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/collect-getting-started/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Getting Started with Collect

> Learn how to accept payments across Africa and the Middle East using CrissCross Collect, with support for cards, mobile money, bank transfers, and more.

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

### 3. Payer ID

Every checkout session returns a `payerId` — a persistent identifier for the customer making the payment. Unlike a session or transaction, which cover a single payment, the Payer ID stays the same across all of a customer's payments, so you can use it to recognise returning customers and link their activity together.

* **Store it**: Persist the `payerId` against your own customer record
* **Reuse it**: Pass it back in `payerDetails.payerId` on future sessions to link a returning payer

See [Payer ID](/payer-id) for full details.

## Integration Methods

CrissCross offers two 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. 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. **Initiate Payment**: Use `POST /v1/payment` to initiate the transaction with the selected payment method
3. **Handle Authorization** (if needed): If the response includes an `authState`, branch on `authState.authMethodType` — `redirect` sends the customer to `authState.redirect.url`, `pendingApproval` and `ussd` complete on the customer's handset, and only `fields` flows (e.g. an OTP) submit via `POST /v1/payment/authorize`
4. **Poll Status**: Use `GET /v1/payment/{transactionId}` to check transaction status, or rely on webhooks for real-time updates
5. **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, Telebirr and the Ethiopian bank wallets
* **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), ETB (Ethiopia), 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 `client_id` and `client_secret`, then include the token in the `Authorization: Bearer ...` header on subsequent requests.

For detailed authentication instructions, see the [Authentication guide](/authentication).

## 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 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:

* [Hosted Checkout](/hosted-checkout)
* [Direct API Integration](/direct-api-integration)

> Accept payments across 20+ markets through one unified API