1Pay API Documentation

Accept payments from anywhere in Africa. Mobile money, cards, bank transfers, and crypto — all through one API.

Quick Start

Get your first payment in 3 steps:

1. Get your API key

   Sign up at 1pay.app, then go to Settings → API Keys and create a key. Keep it secret.

2. Create a payment

   Send a POST request to create a payment session:

   bash Copy

   curl -X POST https://1pay.s.co.tz/api/v1/payments \
     -H "Authorization: Bearer sk_live_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 50000,
       "currency": "TZS",
       "method": "mobile_money",
       "customer_phone": "+255712345678",
       "customer_name": "John Doe",
       "description": "Order #1234"
     }'

3. Handle the response

   You'll get back a payment object with a status. For mobile money, the customer receives an STK push on their phone.

   json Copy

   {
     "success": true,
     "data": {
       "id": 1,
       "reference": "PAY-2026-XXXXX",
       "amount": 50000,
       "currency": "TZS",
       "status": "pending",
       "payment_type": "mobile",
       "provider": "daraja"
     }
   }

Authentication

Authenticate with your API key via the Authorization header:

Authorization: Bearer sk_live_your_api_key

API keys come in two types:

Environments

Switch environments by using sk_test_ or sk_live_ API keys. The base URL stays the same.

Create Payment

<?php
$response = file_get_contents('https://your-domain.com/api/v1/payments', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Authorization: Bearer sk_live_your_key\r\nContent-Type: application/json",
        'content' => json_encode([
            'amount'        => 50000,
            'currency'      => 'TZS',
            'method'        => 'mobile_money',
            'customer_phone' => '+255712345678',
            'customer_name'  => 'John Doe',
        ]),
    ],
]));

$data = json_decode($response, true);
echo $data['data']['reference'];

Get Payment

{
  "success": true,
  "data": {
    "id": 1,
    "reference": "PAY-2026-XXXXX",
    "amount": 50000,
    "net_amount": 47500,
    "fees": 2500,
    "currency": "TZS",
    "status": "completed",
    "payment_type": "mobile",
    "channel_provider": "daraja",
    "customer_name": "John Doe",
    "customer_phone": "+255712345678",
    "created_at": "2026-07-18T10:30:00Z"
  }
}

List Payments

Create Payout

Get Payout

List Payouts

Mobile Money

Accept mobile money payments via M-Pesa, Airtel Money, Tigo Pesa, and Halotel across East Africa.

How it works

1. Customer enters their phone number on the checkout page
2. An STK push (prompt) is sent to their phone
3. Customer enters their PIN to confirm
4. Payment is confirmed via webhook

Card Payments

Accept Visa and Mastercard payments from anywhere in the world.

Flow

1. Customer enters card details on the secure checkout page
2. For 3D Secure cards, customer is redirected to their bank's verification page
3. After verification, payment is processed and confirmed

Cryptocurrency

Accept Bitcoin, Ethereum, USDT, Litecoin, and Dogecoin payments with automatic conversion.

Supported Coins

Flow

1. Customer selects cryptocurrency and coin type
2. A unique wallet address and amount are generated via NOWPayments
3. Customer sends the exact amount to the address
4. Blockchain monitoring detects the transaction and confirms after required block confirmations

QR Code Payments

Generate dynamic QR codes that customers can scan with any mobile wallet.

QR payments work with any mobile wallet that supports QR scanning (M-Pesa, Airtel Money, etc.).

Webhooks

1Pay sends webhooks to notify your server when payment events occur.

Webhook Payload

{
  "event": "payment.completed",
  "data": {
    "id": 1,
    "reference": "PAY-2026-XXXXX",
    "amount": 50000,
    "net_amount": 47500,
    "fee": 2500,
    "currency": "TZS",
    "status": "completed",
    "payment_type": "mobile",
    "customer_name": "John Doe",
    "customer_phone": "+255712345678",
    "session_token": "abc123...",
    "created_at": "2026-07-18T10:30:00Z"
  }
}

Verifying Webhooks

Every webhook includes an X-Webhook-Signature header. Verify it using HMAC-SHA256:

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $webhook_secret);

if (!hash_equals($expected, $signature)) {
    // Invalid signature — reject
    http_response_code(403);
    exit;
}

$event = json_decode($payload, true);
// Process event...

Events

Error Handling

1Pay uses standard HTTP status codes. Errors return a JSON body:

{
  "success": false,
  "error": "Invalid API key"
}

SDKs & Libraries

Official client libraries coming soon. For now, use any HTTP client:

const response = await fetch('https://your-domain.com/api/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 50000,
    currency: 'TZS',
    method: 'mobile_money',
    customer_phone: '+255712345678',
  }),
});

const data = await response.json();
console.log(data);

Rate Limits

API requests are limited to prevent abuse: