Example request headers

curl -X POST https://api.globpay.app/api/v1/collection \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -d '{ ... }'

Example request

{
  "phone": "255712345678",
  "amount": 10000,
  "operator": "mpesa",
  "reference": "ORDER-001",
  "description": "Payment for Order #001"
}

Example request

{
  "amount": 25000,
  "reference": "INV-2024-001",
  "description": "Monthly subscription",
  "expires_in": 1440
}

POST /v1/paylink
{
  "title": "Pay Globpay",
  "currency": "USD",
  "payment_method": "virtual_account"
}

Example request

{
  "phone": "255712345678",
  "amount": 5000,
  "operator": "mpesa",
  "reference": "PAYOUT-001",
  "description": "Salary payment"
}

Example response (200)

{
  "request_ref": "PAY-A1B2C3D4E5F6",
  "type": "collection",
  "amount": 10000,
  "charge": 200,
  "phone": "255712345678",
  "operator": "mpesa",
  "status": "completed",
  "operator_ref": "MPESA123456",
  "reference": "ORDER-001",
  "created_at": "2026-01-15T10:30:00.000000Z",
  "completed_at": "2026-01-15T10:30:45.000000Z"
}

Example response (200)

{
  "account_id": 1,
  "currency": "KES",
  "collection_total": "5000.00",
  "disbursement_total": "1200.00",
  "overall_balance": "6200.00",
  "has_multiple_currencies": true,
  "by_currency": [
    {
      "currency": "KES",
      "collection_total": "5000.00",
      "disbursement_total": "1200.00",
      "overall_balance": "6200.00"
    }
  ],
  "wallets": [
    {
      "operator": "M-Pesa Kenya",
      "wallet_type": "collection",
      "balance": 5000,
      "held_balance": 0,
      "available": 5000,
      "currency": "KES",
      "status": "active"
    },
    {
      "operator": "M-Pesa Kenya",
      "wallet_type": "disbursement",
      "balance": 1200,
      "held_balance": 0,
      "available": 1200,
      "currency": "KES",
      "status": "active"
    }
  ]
}

Example: GET /v1/transactions?date_from=2026-01-01&status=completed&per_page=10

{
  "data": [
    {
      "request_ref": "PAY-A1B2C3D4E5F6",
      "external_ref": "ORDER-001",
      "type": "collection",
      "phone": "255712345678",
      "amount": 10000,
      "platform_charge": 200,
      "currency": "TZS",
      "operator": "M-Pesa",
      "status": "completed",
      "receipt_number": "RCP123456",
      "created_at": "2026-01-15T10:30:00.000000Z",
      "updated_at": "2026-01-15T10:30:45.000000Z"
    }
  ],
  "current_page": 1,
  "per_page": 10,
  "total": 156,
  "last_page": 16
}

Example response (200)

{
  "request_ref": "PAY-A1B2C3D4E5F6",
  "external_ref": "ORDER-001",
  "operator_ref": "MPESA123456",
  "receipt_number": "RCP123456",
  "type": "collection",
  "phone": "255712345678",
  "amount": 10000,
  "platform_charge": 200,
  "operator_charge": 0,
  "currency": "TZS",
  "operator": "M-Pesa",
  "status": "completed",
  "error": null,
  "callback_status": "delivered",
  "description": "Payment for Order #001",
  "created_at": "2026-01-15T10:30:00.000000Z",
  "updated_at": "2026-01-15T10:30:45.000000Z"
}

Example response (200)

{
  "request_ref": "PAY-A1B2C3D4E5F6",
  "external_ref": "ORDER-001",
  "transaction_status": "completed",
  "callback_status": "delivered",
  "callback_url": "https://yoursite.com/webhook/payin",
  "total_attempts": 1,
  "webhooks": [
    {
      "attempt": 1,
      "url": "https://yoursite.com/webhook/payin",
      "http_status": 200,
      "status": "delivered",
      "response_time_ms": 245,
      "error_message": null,
      "sent_at": "2026-01-15T10:30:46.000000Z"
    }
  ]
}

Example response (200)

[
  {
    "name": "M-Pesa",
    "code": "mpesa",
    "country": "Tanzania",
    "currency": "TZS",
    "supports_collection": true,
    "supports_disbursement": true,
    "min_amount": 100,
    "max_amount": 10000000
  },
  {
    "name": "Tigo Pesa",
    "code": "tigopesa",
    "country": "Tanzania",
    "currency": "TZS",
    "supports_collection": true,
    "supports_disbursement": true,
    "min_amount": 100,
    "max_amount": 5000000
  }
]

{
  "request_ref": "PAY-A1B2C3D4E5F6",
  "type": "collection",
  "status": "completed",
  "amount": 10000,
  "charge": 200,
  "phone": "255712345678",
  "operator": "mpesa",
  "operator_ref": "MPESA123456",
  "reference": "ORDER-001",
  "completed_at": "2026-01-15T10:30:45.000000Z"
}

app.post('/webhook/payin', async (req, res) => {
    const payload = req.body;

    // Always verify with Globpay.ai API
    const status = await fetch(
        `https://api.globpay.app/api/v1/status/${payload.request_ref}`,
        {
            headers: {
                'X-API-Key': process.env.PAYIN_API_KEY,
                'X-API-Secret': process.env.PAYIN_API_SECRET,
            }
        }
    );

    const data = await status.json();
    if (status.ok && data.status === 'completed') {
        // Process the successful payment
        await Order.updateOne(
            { reference: payload.reference },
            { payment_status: 'paid' }
        );
    }

    res.json({ received: true });
});

# Collect payment
curl -X POST https://api.globpay.app/api/v1/collection \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"phone":"255712345678","amount":10000,"operator":"mpesa","reference":"ORDER-001"}'

# Create invoice
curl -X POST https://api.globpay.app/api/v1/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"amount":25000,"reference":"INV-001","description":"Monthly subscription"}'

# Virtual account invoice (KES / USD / EUR — VA is auto-assigned)
curl -X POST https://api.globpay.app/api/v1/invoice \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"amount":1500,"reference":"INV-KES-001","currency":"KES","payment_method":"virtual_account"}'

# Create virtual account
curl -X POST https://api.globpay.app/api/v1/virtual-accounts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"currency":"USD","label":"Main USD"}'

# Virtual account paylink (VA auto-created)
curl -X POST https://api.globpay.app/api/v1/paylink \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"title":"Pay Globpay","currency":"USD","payment_method":"virtual_account"}'

# Disburse funds
curl -X POST https://api.globpay.app/api/v1/disbursement \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"phone":"255712345678","amount":5000,"operator":"mpesa","reference":"PAYOUT-001"}'

# Transfer collection → disbursement (requires Auto Transfer)
curl -X POST https://api.globpay.app/api/v1/transfer \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -d '{"amount":1000,"operator":"mpesake","currency":"KES"}'

# Check status
curl https://api.globpay.app/api/v1/status/PAY-A1B2C3D4E5F6 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

# Get balance
curl https://api.globpay.app/api/v1/balance \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

# List transactions (with filters)
curl "https://api.globpay.app/api/v1/transactions?status=completed&date_from=2026-01-01&per_page=10" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

# Lookup transaction
curl https://api.globpay.app/api/v1/transaction/ORDER-001 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

# Check webhook delivery
curl https://api.globpay.app/api/v1/webhooks/PAY-A1B2C3D4E5F6 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

# List operators
curl https://api.globpay.app/api/v1/operators \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"

{
  "message": "Insufficient wallet balance.",
  "errors": {
    "amount": ["The amount must be at least 100."]
  }
}