Getting Started

Introduction

Welcome to the Payment API documentation. This API allows you to accept and send payments using mobile money and other payment methods across Africa.

Our API follows an asynchronous communication model. When you initiate a transaction, you'll receive an immediate acknowledgment, but the final status will be delivered via webhook callbacks.

Base URL

https://genesyspay.com/api/v2

Transaction Handling

Communication with the API follows an asynchronous model:

1. Initial Request: Send a payment request to the API
2. Acknowledgment: Receive an immediate response confirming the request was received
3. Status Check: Query the transaction status using search endpoints
4. Webhook Callback: Receive final status notifications at your configured callback URL

Quick Start

Follow these steps to start integrating:

1. Get Your API Keys

Login to your merchant dashboard and navigate to API Settings to get your private key.

2. Make Your First Request

Here's a basic PayIn request example:

curl -X POST https://genesyspay.com/api/v2/payins \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PRIVATE_KEY" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "country": "CI",
    "channel": "mobile_money",
    "method": "mtn-ci",
    "phone_number": "0707070707",
    "tx_ref": "unique-transaction-ref",
    "callback_url": "https://yoursite.com/webhook"
  }'

3. Handle Webhook Callbacks

Set up a webhook endpoint to receive transaction status updates. The webhook will receive transaction details including the final status. See the Webhooks documentation for detailed implementation guide.

Response Format

All API responses follow this standard format:

{
  "status": "success",
  "data": {
    // Response data
  }
}

Error responses:

{
  "status": "error",
  "message": "Error description",
  "error_code": "ERROR_CODE",
  "errors": {
    // Validation errors (if applicable)
  }
}

Rate Limiting

To maintain optimal uptime and safeguard against abuse or bursts of incoming traffic, we enforce rate limits on API requests.

If you exceed the rate limit, you'll receive an HTTP 429 (Too Many Requests) response. Rate limits apply per API key and are subject to change based on system load and security requirements.

Tips to Prevent Rate Limiting

• Use Webhooks: Rather than polling perpetually, monitor transaction status changes via webhooks. This is the recommended approach for real-time updates.
• Structured Polling: Do not poll indefinitely to get transaction status. Instead, call endpoints in a structured and sparse manner or in response to specific events.
• Batch Operations: Where possible, retrieve multiple records in a single request using list endpoints with pagination.
• Cache Responses: Cache static data like payment methods, currencies, and countries rather than fetching them repeatedly.

Handling Rate Limits Gracefully

Implement a retry mechanism with exponential backoff when you receive a 429 response:

// Example retry logic (pseudo-code)
function makeRequest(url, retries = 3, delay = 1000) {
  try {
    return apiCall(url);
  } catch (error) {
    if (error.status === 429 && retries > 0) {
      // Wait with exponential backoff
      wait(delay);
      return makeRequest(url, retries - 1, delay * 2);
    }
    throw error;
  }
}

Support

If you need assistance integrating the API:

• Check the detailed documentation sections
• Contact our support team through your merchant dashboard
• Review error codes for troubleshooting