API Documentation

Everything you need to integrate GrandPay into your application.

Documentation

Getting Started

Welcome to the GrandPay API documentation.

Step 1: Create Account

Create a GrandPay account and verify your business details.

Step 2: Get API Keys

Navigate to Settings > API Keys to generate your API credentials.

Step 3: Make Your First Request

Use your API key to authenticate requests and start accepting payments.

Authentication

All API requests must be authenticated using your API key.

Your API key should be kept secret.
Header 
Authorization: Bearer YOUR_API_KEY

Two-Factor Authentication (2FA)

Enhance your account security with Time-based One-Time Password (TOTP) authentication using authenticator apps like Google Authenticator, Authy, or Microsoft Authenticator.

Why Enable 2FA?

Two-factor authentication adds an extra layer of security to your account. Even if someone obtains your password, they cannot access your account without the 2FA code from your authenticator app.

Setting Up 2FA
  1. Navigate to Security Settings
    Go to your dashboard and click on "Security" or navigate to /two-factor/setup
  2. Scan the QR Code
    Open your authenticator app and scan the QR code displayed on the screen. Alternatively, you can manually enter the secret key.
  3. Enter Verification Code
    Enter the 6-digit code from your authenticator app to confirm setup.
  4. Save Recovery Codes
    Store your recovery codes in a safe place. You'll need them if you lose access to your authenticator app.
Supported Authenticator Apps
Google Authenticator
iOS & Android
Authy
iOS, Android & Desktop
Microsoft Authenticator
iOS & Android
Login with 2FA

When logging in with 2FA enabled:

Login Flow 
1. Enter your email and password
2. You'll be redirected to the 2FA challenge page
3. Enter the 6-digit code from your authenticator app
4. Alternatively, use a recovery code if you've lost access to your app
5. Upon successful verification, you'll be logged in
API Endpoints
Method Endpoint Description
GET /two-factor/setup Display 2FA setup page with QR code
POST /two-factor/confirm Confirm 2FA setup with verification code
GET /two-factor/challenge Display 2FA challenge during login
POST /two-factor/verify Verify 2FA code during login
POST /two-factor/disable Disable 2FA (requires current password)
GET /two-factor/recovery-codes View recovery codes
POST /two-factor/regenerate-recovery-codes Regenerate recovery codes
Recovery Codes

Each recovery code can only be used once. After using all 8 recovery codes, you must regenerate new ones. Keep your recovery codes stored securely - they are the only way to access your account if you lose your authenticator device.

Wallet API

Integrate GrandPay wallet functionality into your website or application. Accept payments directly into your wallet and process withdrawals to M-Pesa.

Wallet Integration Benefits

Receive payments from customers directly into your GrandPay wallet. Withdraw funds to your M-Pesa at any time. Track all transactions via API.

Base URL
https://grandpay.grandtek.co.ke/api/v1/wallet
API Endpoints
Method Endpoint Description
POST /balance Get current wallet balance
POST /deposit Initiate deposit via M-Pesa STK Push
POST /withdraw Request withdrawal to M-Pesa
POST /transactions Get wallet transaction history
POST /status Check specific transaction status
1. Get Wallet Balance
POST /api/v1/wallet/balance 
{
    "api_key": "your_api_key",
    "email": "your@email.com"
}

Response: Returns wallet_balance, currency, and last_updated

2. Deposit (STK Push)
POST /api/v1/wallet/deposit 
{
    "api_key": "your_api_key",
    "email": "your@email.com",
    "amount": 1000,
    "msisdn": "254712345678"
}

Response: Initiates M-Pesa STK Push. Customer completes payment on their phone. Wallet credited upon success.

3. Withdraw (to M-Pesa)
POST /api/v1/wallet/withdraw 
{
    "api_key": "your_api_key",
    "email": "your@email.com",
    "amount": 500,
    "msisdn": "254712345678"
}

Response: Initiates B2C payment. Funds sent to the specified M-Pesa number.

4. Transaction History
POST /api/v1/wallet/transactions 
{
    "api_key": "your_api_key",
    "email": "your@email.com",
    "limit": 20,
    "type": "all"  // "deposit", "withdrawal", or "all"
}
5. Check Transaction Status
POST /api/v1/wallet/status 
{
    "api_key": "your_api_key",
    "email": "your@email.com",
    "transaction_reference": "WDEP-ABC123-1234567890"
}
Fees & Limits

Minimum: KES 10 | Maximum: KES 150,000 per transaction
Deposit and withdrawal fees apply based on tariff configuration.

STK Push

Initiate M-Pesa STK Push payments.

POST /api/v1/stk-push
Parameters
Parameter Description
phone Customer phone
amount Amount in KES
Response
{"success": true}

Webhooks

Receive real-time payment notifications.

Setup

Configure your webhook URL in dashboard settings.

Payload Example
{"event": "payment.completed"}

Need Help?

Our developer support team is available 24/7.

Email Support

developers@grandpay.co.ke

Phone Support

+254 700 000 000