Skip to main content

Quick Start Guide

Get up and running with GCA Pay API integration in minutes.

Overview​

GCA Pay provides two core payment services for merchant applications:

  • Collections: Accept payments from customers via mobile money
  • Disbursements: Send money to recipients via mobile money
Account Setup Required

Registration, project creation, developer assignments, and KYC verifications are completed through the GCA Pay Merchants Dashboard. Once approved, you'll receive API credentials for integration.

What You Can Integrate​

Collections API​

Accept payments from customers using:

  • Airtel Money (Tanzania - TZS)
  • More networks coming soon

Disbursements API​

Send money to recipients using:

  • Airtel Money B2C (Tanzania - TZS)
  • More networks coming soon

Transaction Callbacks​

Receive real-time status updates for all transactions.

Prerequisites​

Before integration, ensure you have:

  • ✅ Completed registration through GCA Pay Merchants Dashboard
  • ✅ Submitted and approved KYC documents
  • ✅ Received API credentials for your project
  • ✅ Development environment capable of making HTTP requests

Authentication​

All API requests require Bearer token authentication:

Authorization: Bearer YOUR_API_TOKEN

Base URL​

https://gcapay.site/api/v1/

Your First Payment Integration​

Step 1: Test Authentication​

Verify your API token works:

curl -X GET https://gcapay.site/api/v1/user-service/profile \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 2: Accept Your First Payment (Collections)​

Request a payment from a customer:

curl -X POST https://gcapay.site/api/v1/payment-service/airtel/c2b \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+255683542710",
    "amount": "1000"
  }'

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"
}

Step 3: Send Your First Payment (Disbursements)​

Send money to a recipient:

curl -X POST https://gcapay.site/api/v1/payment-service/airtel/b2c \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+255683542710",
    "amount": "1000"
  }'

Response:

{
  "status": "success",
  "message": "Disbursement initiated successfully",
  "transaction_id": "TXN_987654321",
  "reference": "GCA_REF_123456789",
  "amount": "1000",
  "currency": "TZS",
  "phone_number": "+255683542710",
  "status_code": "PROCESSING"
}

Step 4: Check Transaction Status​

Query the status of any transaction:

curl -X GET https://gcapay.site/api/v1/payment-service/transaction/TXN_123456789 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

const gcaPay = axios.create({
  baseURL: 'https://gcapay.site/api/v1',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

// Request payment from customer
async function requestPayment(phoneNumber, amount) {
  try {
    const response = await gcaPay.post('/payment-service/airtel/c2b', {
      phone_number: phoneNumber,
      amount: amount.toString()
    });
    
    console.log('Payment requested:', response.data);
    return response.data;
  } catch (error) {
    console.error('Payment failed:', error.response?.data);
  }
}

// Send money to recipient
async function sendMoney(phoneNumber, amount) {
  try {
    const response = await gcaPay.post('/payment-service/airtel/b2c', {
      phone_number: phoneNumber,
      amount: amount.toString()
    });
    
    console.log('Money sent:', response.data);
    return response.data;
  } catch (error) {
    console.error('Disbursement failed:', error.response?.data);
  }
}

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

Python​

import requests

class GCAPayAPI:
    def __init__(self, api_token):
        self.base_url = "https://gcapay.site/api/v1"
        self.headers = {
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json"
        }
    
    def request_payment(self, phone_number, amount):
        """Request payment from customer"""
        response = requests.post(
            f"{self.base_url}/payment-service/airtel/c2b",
            json={
                "phone_number": phone_number,
                "amount": str(amount)
            },
            headers=self.headers
        )
        return response.json()
    
    def send_money(self, phone_number, amount):
        """Send money to recipient"""
        response = requests.post(
            f"{self.base_url}/payment-service/airtel/b2c",
            json={
                "phone_number": phone_number,
                "amount": str(amount)
            },
            headers=self.headers
        )
        return response.json()

# Usage
api = GCAPayAPI("YOUR_API_TOKEN")
collection = api.request_payment("+255683542710", 1000)
disbursement = api.send_money("+255683542710", 1000)

PHP​

<?php

class GCAPayAPI {
    private $baseUrl = 'https://gcapay.site/api/v1';
    private $headers;
    
    public function __construct($apiToken) {
        $this->headers = [
            'Authorization: Bearer ' . $apiToken,
            'Content-Type: application/json'
        ];
    }
    
    public function requestPayment($phoneNumber, $amount) {
        return $this->makeRequest('/payment-service/airtel/c2b', [
            'phone_number' => $phoneNumber,
            'amount' => (string)$amount
        ]);
    }
    
    public function sendMoney($phoneNumber, $amount) {
        return $this->makeRequest('/payment-service/airtel/b2c', [
            'phone_number' => $phoneNumber,
            'amount' => (string)$amount
        ]);
    }
    
    private function makeRequest($endpoint, $data) {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . $endpoint);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, $this->headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
}

// Usage
$api = new GCAPayAPI('YOUR_API_TOKEN');
$collection = $api->requestPayment('+255683542710', 1000);
$disbursement = $api->sendMoney('+255683542710', 1000);
?>

Integration Checklist​

  • Account Setup: Complete registration and KYC at merchants.gca-pay.com
  • API Credentials: Obtain sandbox and production tokens
  • Test Collections: Successfully request a payment
  • Test Disbursements: Successfully send money
  • Webhook Setup: Implement transaction status callbacks
  • Error Handling: Handle API errors gracefully
  • Production Ready: Switch to production tokens

What's Next?​

Now that you've made your first API calls, dive deeper into: