Getting Started

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.

$
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": "[email protected]",
>
      "location": "ZAF"
>
    }
>
  }'

The example above includes the required fields, amount, currency, merchantReference, merchantId, integrationType, and payerDetails (which must include location), plus the optional redirectUrl. To test connectivity, leave the optional fields out completely: rateLockId, paymentAttributes, and the payer’s emailAddress, 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 or 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, USD).

The full set of supported currency values is ZAR, NGN, UGX, ZMW, GHS, KES, TZS, 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):

1
{
2
  "sessionId": "550e8400-e29b-41d4-a716-446655440003",
3
  "paymentLink": "https://crisscross.money/checkout/550e8400-e29b-41d4-a716-446655440003",
4
  "payerId": "550e8400-e29b-41d4-a716-446655770987",
5
  "signature": "a8fdc205a9f19cc1fuyf5a60c4f01b13d11d7fd0"
6
}

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:

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

Expected Response:

1
{
2
  "session": {
3
    "id": "550e8400-e29b-41d4-a716-446655440003",
4
    "amount": 10000,
5
    "currencyId": "ZAR",
6
    "merchantReference": "ORDER-12345",
7
    "redirectUrl": "https://crisscross.money/payment/callback",
8
    "merchantId": "550e8400-e29b-41d4-a716-446655440000",
9
    "expiresAt": "2024-03-01T10:30:00.000Z",
10
    "customerId": "550e8400-e29b-41d4-a716-446655440001",
11
    "payerLocation": "ZAF"
12
  },
13
  "payerId": "550e8400-e29b-41d4-a716-446655440001"
14
}

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:

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

Payouts API

Fetch recent payout history:

$
curl -X GET "https://api.crisscross.money/v1/payouts/history?limit=1" \
>
  -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.