Skip to main content

Collections API

Accept payments from customers via mobile money networks.

Overview​

The Collections API allows you to request payments from customers using their mobile money accounts. Currently supporting Airtel Money in Tanzania.

Endpoint​

POST /payment-service/airtel/c2b

Authentication​

Requires Bearer token authentication:

Authorization: Bearer YOUR_API_TOKEN

Request Parameters​

ParameterTypeRequiredDescription
phone_numberstringYesCustomer's phone number (E.164 format)
amountstringYesAmount to collect (minimum 500 TZS)
external_idstringNoYour unique transaction reference

Request Example​

{
  "phone_number": "+255683542710",
  "amount": "1000"
}

Response Example​

Success Response​

{
  "status": "success",
  "message": "Payment request sent successfully",
  "transaction_id": "TXN_123456789",
  "reference": "GCA_REF_987654321",
  "amount": "1000",
  "currency": "TZS",
  "phone_number": "+255683542710",
  "status_code": "PENDING"
}

Error Response​

{
  "status": "error",
  "message": "Invalid phone number format",
  "error_code": "INVALID_PHONE_NUMBER"
}

Status Codes​

CodeDescription
PENDINGPayment request sent to customer
SUCCESSPayment completed successfully
FAILEDPayment failed or was rejected
TIMEOUTPayment request timed out

Implementation Example​

JavaScript/Node.js​

const axios = require('axios');

async function requestPayment(phoneNumber, amount) {
  try {
    const response = await axios.post(
      'https://gcapay.site/api/v1/payment-service/airtel/c2b',
      {
        phone_number: phoneNumber,
        amount: amount.toString()
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Payment initiated:', response.data);
    return response.data;
  } catch (error) {
    console.error('Payment failed:', error.response?.data);
    throw error;
  }
}

// Usage
requestPayment('+255683542710', 1000);

Python​

import requests

def request_payment(phone_number, amount):
    url = "https://gcapay.site/api/v1/payment-service/airtel/c2b"
    
    headers = {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json"
    }
    
    payload = {
        "phone_number": phone_number,
        "amount": str(amount)
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Payment request failed: {e}")
        raise

# Usage
result = request_payment("+255683542710", 1000)
print(result)

PHP​

<?php

function requestPayment($phoneNumber, $amount) {
    $url = 'https://gcapay.site/api/v1/payment-service/airtel/c2b';
    
    $data = array(
        'phone_number' => $phoneNumber,
        'amount' => (string)$amount
    );
    
    $headers = array(
        'Authorization: Bearer YOUR_API_TOKEN',
        'Content-Type: application/json'
    );
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Payment request failed: " . $response);
    }
}

// Usage
try {
    $result = requestPayment('+255683542710', 1000);
    echo json_encode($result, JSON_PRETTY_PRINT);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
?>

Best Practices​

Phone Number Format​

  • Always use E.164 format: +255683542710
  • Validate format before sending requests
  • Handle international prefixes correctly

Amount Handling​

  • Send amounts as strings to avoid floating-point issues
  • Minimum amount: 500 TZS
  • Validate amounts are positive integers

Error Handling​

  • Implement retry logic for network failures
  • Log all transactions for reconciliation
  • Handle timeout scenarios gracefully

Security​

  • Never expose API tokens in client-side code
  • Implement rate limiting on your endpoints
  • Validate all input parameters

Testing​

Use the following test credentials in sandbox environment:

  • Test Phone: +255683542710
  • Test Amount: 1000
  • Expected Result: Success response

Transaction Flow​

  1. Initiate: Send payment request to GCA Pay
  2. Customer Prompt: Customer receives payment prompt on their phone
  3. Authorization: Customer enters PIN to authorize payment
  4. Completion: Transaction completes and webhook is sent
  5. Confirmation: You receive final status via webhook

Next Steps​