Quick Start Guide

This guide walks you through the steps to get your API keys, create your first payment session, and test a checkout using the Xtopay sandbox simulator.

1. Retrieve your Client Credentials

To authenticate requests with the Xtopay API, you need your Client ID and Client Secret. You can find them in the Xtopay Dashboard under Developer Settings > API Keys.

Xtopay supports two environments:

• Sandbox (Test Mode): Use this for development and testing.
• Live Mode: Use this for real production transactions.

Keep your Client Secret safe and never expose it in client-side code (like frontend scripts or mobile apps).

2. Process a Test Payment

To accept a payment, you will generate a secure checkout session. The following steps show how to create a payment session and process it.

Step A: Create a Payment Session via API

Send a POST request to the /v1/payments endpoint with the payment details. You can authenticate using curl by passing the client credentials with the -u flag.

curl https://api.xtopay.co/v1/payments \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "GHS",
    "description": "Premium Subscription Plan Purchase",
    "customer": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "phone": "+233240000000"
    },
    "metadata": {
      "orderId": "order_abc123"
    }
  }'

Response Payload

{
  "success": true,
  "data": {
    "id": "pay_cl8z2e8z20000g...",
    "reference": "cl8z2e8z20000g...",
    "amount": 5000,
    "currency": "GHS",
    "status": "PENDING",
    "description": "Premium Subscription Plan Purchase",
    "checkoutUrl": "https://checkout.xtopay.co/pay/cl8z2e8z20000g...",
    "metadata": {
      "orderId": "order_abc123"
    },
    "createdAt": "2026-06-05T12:00:00Z"
  }
}

Step B: Redirect the Customer

Redirect your customer to the checkoutUrl returned in the response payload. They will see the secure Xtopay Checkout page, populated with their transaction details.

Step C: Simulate the Payment

In Sandbox mode, you can test different payment methods:

• Cards: Enter any valid card number. When prompted for 3D Secure verification, click Authorize to simulate a successful payment or Decline to test a failure.
• Mobile Money: Select MTN, Telecel, or AirtelTigo. Enter a phone number, click pay, and use the interactive push notification mock modal to click Confirm and input a simulated PIN.
• Bank Transfer: Choose Bank Transfer to display a temporary virtual account. Click Simulate Transfer to mock the bank sending payment notification in the background.

Once completed, the checkout window will redirect the user back to the redirect URL configured on your dashboard or passed in the request.

3. Listen for Webhooks

Once the transaction is successfully completed, Xtopay will deliver a real-time event to your webhook URL.

{
  "id": "evt_0987654321fedcba",
  "event": "payment.succeeded",
  "environment": "TEST",
  "createdAt": "2026-06-05T12:00:05Z",
  "data": {
    "id": "pay_cl8z2e8z20000g...",
    "reference": "cl8z2e8z20000g...",
    "status": "SUCCEEDED",
    "amount": 5000,
    "currency": "GHS",
    "fee": 75,
    "net": 4925,
    "description": "Premium Subscription Plan Purchase",
    "paidAt": "2026-06-05T12:00:04Z",
    "metadata": {
      "orderId": "order_abc123"
    },
    "customer": {
      "id": "cust_8283723923...",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  }
}

To learn how to verify webhook signatures securely, head over to the Webhooks guide.