Online Checkout API

Accept payments via mobile money, cards, and digital wallets with Xtopay's seamless checkout solution.

Quick Start

Try our interactive demo or jump to the implementation guide.

Overview

The Xtopay Online Checkout API enables merchants to accept payments through:

Customers can pay via a secure, hosted checkout page that supports multiple payment methods.

Choose between two integration methods:

Redirect Checkout

Redirect customers to Xtopay's optimized checkout page.

Customer clicks pay button on your site

Redirected to Xtopay checkout

Selects payment method and completes transaction

Redirected back to your return URL

View implementation

Onsite Checkout

Embed the checkout directly in your website (iframe).

Payment form loads within your site

Customer selects payment method

Completes payment without leaving your site

Receives confirmation in your UI

View implementation

API Reference

POST

/v1/checkout/initiate

Authentication

All requests require API key authentication.

Request Parameters

Parameter	Type	Required	Description
amount	number	Yes	Transaction amount (2 decimal places)
currency	string	Yes	Currency code (GHS, USD, etc.)
description	string	Yes	Transaction description
callbackUrl	string	Yes	URL for payment notifications
returnUrl	string	Yes	URL after successful payment
cancelUrl	string	Yes	URL if payment is canceled
clientReference	string	Yes	Your unique transaction ID (max 32 chars)
customer	object	No	Customer details object
customer.name	string	No	Customer full name
customer.phone	string	No	Customer phone number
customer.email	string	No	Customer email address

Sample Request

javascript

curl -X POST https://api.xtopay.co/v1/checkout/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "currency": "GHS",
    "description": "Online Store Purchase",
    "callbackUrl": "https://yourdomain.com/webhooks/payment",
    "returnUrl": "https://yourdomain.com/order/123",
    "cancelUrl": "https://yourdomain.com/order/123/cancel",
    "clientReference": "order_123456",
    "customer": {
      "name": "Kwame Asante",
      "phone": "233244123456",
      "email": "kwame@example.com"
    }
  }'

Response

javascript

{
  "success": true,
  "data": {
    "checkoutUrl": "https://pay.xtopay.co/xtp_xyz123",
    "checkoutId": "xyz123",
    "expiresAt": "2025-07-21T23:59:59Z",
    "clientReference": "order_123456"
  }
}

Implementation Guides

Redirect Checkout

Implement a basic checkout flow that redirects to Xtopay's hosted payment page.

Frontend Implementation

javascript

// React example
async function initiateCheckout() {
  const response = await fetch('/api/create-checkout-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: 100.50,
      description: 'Online Purchase'
    })
  });
  
  const { checkoutUrl } = await response.json();
  window.location.href = checkoutUrl;
}

// Vanilla JS example
document.getElementById('payButton').addEventListener('click', initiateCheckout);

Backend Implementation

javascript

// Node.js (Express) example
app.post('/api/create-checkout-session', async (req, res) => {
  try {
    const response = await fetch('https://api.xtopay.co/v1/checkout/initiate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.XTOPAY_API_KEY}`
      },
      body: JSON.stringify({
        amount: req.body.amount,
        currency: 'GHS',
        description: req.body.description,
        callbackUrl: `${process.env.BASE_URL}/api/webhooks/payment`,
        returnUrl: `${process.env.BASE_URL}/checkout/success`,
        cancelUrl: `${process.env.BASE_URL}/checkout/cancel`,
        clientReference: generateUniqueId()
      })
    });
    
    const data = await response.json();
    res.json(data);
  } catch (error) {
    res.status(500).json({ error: 'Checkout creation failed' });
  }
});

Onsite Checkout

Embed the checkout directly in your site using our JavaScript SDK.

html

<!-- Load Xtopay SDK -->
<script src="https://js.xtopay.co/v2/"></script>

<!-- Add payment button -->
<button id="xtopay-button">Pay Now</button>

<script>
  // Configure Xtopay
  const xtopay = Xtopay('YOUR_PUBLIC_KEY');
  
  document.getElementById('xtopay-button').addEventListener('click', () => {
    xtopay.open({
      amount: 100.50,
      currency: 'GHS',
      description: 'Online Purchase',
      onSuccess: (payment) => {
        console.log('Payment successful', payment);
        // Update your UI
      },
      onClose: () => {
        console.log('Checkout closed');
      }
    });
  });
</script>

Handling Payments

Webhook Notifications

Implement a webhook endpoint to receive real-time payment notifications.

javascript

// Node.js webhook handler example
app.post('/api/webhooks/payment', async (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-xtopay-signature'];
  const isValid = verifyWebhookSignature(req.body, signature);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;
  
  switch (event) {
    case 'payment.success':
      // Update order status in your database
      await markOrderAsPaid(data.clientReference);
      break;
      
    case 'payment.failed':
      // Handle failed payment
      console.log('Payment failed:', data.reason);
      break;
  }

  res.status(200).send('OK');
});

Transaction Status API

Important

Always verify transaction status if you don't receive a webhook within 5 minutes.

bash

curl -X GET \
  https://api.xtopay.co/v1/transactions/status?clientReference=order_123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Codes

Code	Description	Action
200	Success - Transaction processed	Fulfill order
400	Invalid request parameters	Check request data
401	Authentication failed	Verify API keys
402	Payment failed	Customer should retry
429	Rate limit exceeded	Wait and retry
5xx	Server error	Contact support