Direct API Integration

Overview

Direct API Integration with CrissCross allows merchants to manage their own checkout screens and directly interact with CrissCross APIs for payments. This approach offers full control over the user experience but requires the merchant to adhere to strict PCI-DSS compliance if sensitive card data is handled.

How It Works

1. Create a Checkout Session: Create a checkout session that captures the amount, currency, and payer details.

2. Present Payment Options: Display the payment methods returned from CrissCross on your custom checkout page.

3. Capture and Process Payment Details: For card payments, you will need to capture card details and submit them securely to CrissCross.

4. Receive Payment Status Updates: Use webhooks to get real-time status updates for payments (e.g., authorized, declined).

Example: Create a Checkout Session

Start by creating a checkout session. This returns a sessionId and (for hosted flows) may include a paymentLink. For direct integrations, you typically proceed by selecting a method and initiating a transaction via POST /payment.

1
{
2
  "merchantId": "YOUR_MERCHANT_ID",
3
  "merchantReference": "ORDER_12345",
4
  "amount": 15000,
5
  "currency": "NGN",
6
  "integrationType": "direct",
7
  "redirectUrl": "https://merchant-site.com/redirect",
8
  "payerDetails": {
9
    "emailAddress": "[email protected]",
10
    "location": "NGA",
11
    "fullName": "Jane Doe"
12
  }
13
}

Sample Response:

1
{
2
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a"
3
}

Handling Card Payments

If the customer selects a card payment, the merchant must collect the card details securely. This requires PCI compliance to ensure the safety of sensitive card information.

Example of a card payment submission:

$
curl --request POST 'https://api.crisscross.money/v1/payment' \
>
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
>
  --header 'Content-Type: application/json' \
>
  --data-raw '{
$
    "paymentMethodId": "card",
$
    "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
$
    "paymentDetails": {
$
      "type": "card",
$
      "encryptedCardNumber": "EV_OR_PROVIDER_TOKEN",
$
      "encryptedCardCvv": "EV_OR_PROVIDER_TOKEN",
$
      "cardExpiryMonth": "12",
$
      "cardExpiryYear": "2028",
$
      "cardHolderName": "Jane Doe",
$
      "payerEmail": "[email protected]"
$
    }
$
  }'

If a transaction requires additional user interaction (e.g. redirect/challenge), use GET /v1/payment/{transactionId} to poll for authState, then submit additional data using POST /v1/payment/authorize.

Webhooks for Payment Status

CrissCross will notify merchants via webhooks about the status of transactions. Make sure your server is set up to receive and handle these notifications.

Sample webhook payload:

1
{
2
  "event": "payment.authorized",
3
  "data": {
4
    "transaction_id": "txn_7890",
5
    "status": "authorized",
6
    "amount": 10000,
7
    "currency": "NGN"
8
  }
9
}

Best Practices

• Secure Payment Handling: Use tokenization where possible to avoid direct exposure to sensitive data.
• Monitor API Usage: Ensure you are using the API efficiently to avoid rate limits.
• Webhooks: Use webhooks for real-time updates on payment statuses.
• Error Handling: Implement retry mechanisms for failed payments based on CrissCross’s error codes.