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

# Getting Started

> Verify your connection to the CrissCross API, create a checkout session, and confirm your integration is set up correctly.

### Overview

This guide takes you from credentials to your first successful API call. You will confirm that authentication works, create a checkout session, and use it to verify connectivity to the Collect API. The same connectivity checks apply to the Exchange and Payouts APIs.

Every CrissCross client is onboarded with hands-on support from our solutions engineering team, so if anything here does not behave as expected, you are never troubleshooting alone.

### Before you begin

You will need:

* A valid OAuth 2.0 access token with the scopes for the API you are calling.
* The base URL `https://api.crisscross.money`.
* Network access to that host from your environment.
* Your sandbox `merchantId`, shared with you alongside your `client_id` and `client_secret` during onboarding.

### Step 1: Create a checkout session

Most Collect API calls operate on a checkout session, so the first step is to create one. This returns a `sessionId` that you use in later requests.

```bash
curl -X POST "https://api.crisscross.money/v1/checkout/session" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "ZAR",
    "merchantReference": "ORDER-12345",
    "redirectUrl": "https://crisscross.money/payment/callback",
    "merchantId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationType": "hosted",
    "payerDetails": {
      "emailAddress": "john.doe@example.com",
      "location": "ZAF"
    }
  }'
```

The example above includes the required fields — `amount`, `currency`, `merchantReference`, `merchantId`, `integrationType`, and `payerDetails` (which must include `emailAddress` and `location`) — plus the optional `redirectUrl`. To test connectivity, leave the optional fields out completely: `rateLockId`, `paymentAttributes`, and the payer's `fullName` and `phoneNumber`.

`redirectUrl` is the page the buyer is returned to after payment. If you do not have your own return page, you can use the CrissCross-hosted URL shown above.

RedirectUrl is optional. Omit it completely if you don't need a return page. If you do include it, it must be a valid URL (for example [https://yourdomain.com/callback](https://yourdomain.com/callback) or [https://crisscross.money/payment/callback](https://crisscross.money/payment/callback)), or the request is rejected with 422.

`amount` is an integer in the currency's minor units, so `10000` represents ZAR 100.00. Most supported currencies use two minor units (`ZAR`, `NGN`, `ZMW`, `GHS`, `KES`, `TZS`, `ETB`, `USD`).

> **Tip**
>
> Important to note: `UGX`, `XAF`, and `XOF` have no minor unit, so for these the integer represents whole currency units (`100` means UGX 100).

The full set of supported `currency` values is `ZAR`, `NGN`, `UGX`, `ZMW`, `GHS`, `KES`, `TZS`, `ETB`, `USD`, `XAF`, and `XOF`.

`payerDetails.location` is an ISO 3166-1 alpha-3 country code, such as `ZAF`, `NGA`, or `KEN`. `integrationType` is either `hosted` or `direct`.

**Expected Response (`201 Created`):**

```json
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLink": "https://checkout.crisscross.money/session/550e8400-e29b-41d4-a716-446655440003?signature=kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM",
  "payerId": "550e8400-e29b-41d4-a716-446655770987",
  "signature": "kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM"
}
```

Copy the `sessionId` from the response. This is the value you pass in the next step. For `hosted` integrations, `paymentLink` is the URL you redirect the buyer to.

### Step 2: Test connectivity with an authenticated call

With a session in hand, make a simple request to a lightweight endpoint that requires authentication. A clean response confirms your credentials, network path, and integration are all working.

#### Collect API

Fetch the checkout session you just created:

```bash
curl -X GET "https://api.crisscross.money/v1/checkout/session?sessionId=YOUR_SESSION_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Expected Response:**

```json
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "amount": 10000,
    "currencyId": "ZAR",
    "merchantReference": "ORDER-12345",
    "redirectUrl": "https://crisscross.money/payment/callback",
    "merchantId": "550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2024-03-01T10:30:00.000Z",
    "customerId": "550e8400-e29b-41d4-a716-446655440001",
    "payerLocation": "ZAF"
  },
  "payerId": "550e8400-e29b-41d4-a716-446655440001"
}
```

Once a payment has been initiated against the session, the response also includes an `activeTransaction` object with the transaction status.

#### Exchange API

Fetch account balances:

```bash
curl -X GET "https://api.crisscross.money/v1/balances" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Payouts API

List recent payouts:

```bash
curl -X GET "https://api.crisscross.money/v1/payout?merchantIds=YOUR_MERCHANT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Troubleshooting

If a call fails, work through these checks:

* **Verify your access token.** Confirm the OAuth 2.0 token is current and carries the scopes required for the endpoint you are calling.
* **Check network settings.** Confirm no firewall or network policy is blocking access to `api.crisscross.money`.
* **Inspect the request.** Tools like Postman or a verbose `curl -v` help isolate whether the issue is authentication, networking, or the request itself.

### Contact support

If problems persist, contact CrissCross support with the details of your request and any error responses you received. Our solutions engineers will work with you directly to get your integration running.