REST API Reference

The iNPAY REST API provides a comprehensive set of endpoints for creating PayIDs, virtual accounts, and managing transfers. All endpoints use standard HTTP methods and return JSON responses.

🔗 Base URL

Production: https://api.inpaycheckout.com/api/v1/developer
Development: https://sandbox-api.inpaycheckout.com/api/v1/developer

🔑 Authentication

All requests require authentication using your secret key:

Authorization: Bearer sk_live_your_secret_key_here

📋 PayID Endpoints

Create Dynamic PayID

Create a unique PayID for one-time payments.

POST /payid/dynamic

Request Body:

{
  "reference": "unique-ref-123",
  "metadata": {
    "orderId": "ORDER-456",
    "customerEmail": "customer@example.com"
  }
}

Response:

{
  "success": true,
  "message": "Dynamic PayID created successfully",
  "data": {
    "payId": "inpaych456.dpid",
    "name": "iNPAYCheckout-Arowolo Daniel Oluwatosin",
    "reference": "unique-ref-123",
    "expiresAt": "2025-09-15T10:30:00.000Z",
    "status": "active",
    "type": "dynamic"
  }
}

Create Static PayID

Create a custom-branded PayID for recurring payments.

POST /payid/static

Request Body:

{
  "name": "My Custom PayID",
  "reference": "unique-ref-456",
  "metadata": {
    "businessUnit": "sales",
    "region": "lagos"
  }
}

Response:

{
  "success": true,
  "message": "Static PayID created successfully",
  "data": {
    "payId": "mycustom789.spid",
    "name": "My Custom PayID",
    "reference": "unique-ref-456",
    "status": "active",
    "type": "static"
  }
}

Verify PayID

Verify a PayID before using it for transfers.

POST /payid/verify

Request Body:

{
  "payId": "merchant123.dpid"
}

Response:

{
  "success": true,
  "message": "PayID verified successfully",
  "data": {
    "payId": "merchant123.dpid",
    "accountName": "John Doe",
    "isVirtualPayId": true,
    "isActive": true,
    "expiresAt": "2025-09-15T10:30:00.000Z",
    "type": "dynamic"
  }
}

🏦 Virtual Account Endpoints

Create Virtual Account

Create a temporary bank account for specific transactions.

POST /virtual-account

Request Body:

{
  "amount": 50000,
  "name": "Custom Account Name",
  "reference": "unique-ref-789",
  "validityTime": 1440,
  "amountValidation": "A0",
  "metadata": {
    "productId": "PROD-123",
    "campaignId": "CAMP-456"
  }
}

Response:

{
  "success": true,
  "message": "Virtual account created successfully",
  "data": {
    "accountNumber": "9876543210",
    "accountName": "iNPAYCheckout-Custom Account Name",
    "bankName": "VFD Microfinance Bank",
    "reference": "unique-ref-789",
    "amount": 50000,
    "currency": "NGN",
    "expiresAt": "2025-09-15T10:30:00.000Z",
    "validityTime": 1440,
    "amountValidation": "A0"
  }
}

💸 Transfer Endpoints

PayID-to-PayID Transfer

Transfer money between PayIDs.

POST /transfer/payid

Request Body:

{
  "fromPayId": "mywallet123.wallet",
  "toPayId": "customer456.dpid",
  "amount": 5000,
  "narration": "Payment for order #12345",
  "reference": "TXN-789"
}

Response:

{
  "success": true,
  "message": "Transfer completed successfully",
  "data": {
    "transactionId": "iNPAY-1234567890",
    "reference": "TXN-789",
    "fromPayId": "mywallet123.wallet",
    "toPayId": "customer456.dpid",
    "amount": 5000,
    "narration": "Payment for order #12345",
    "status": "completed",
    "completedAt": "2025-09-14T10:30:00.000Z",
    "destinationAccountName": "Customer Name"
  }
}

Verify External Account

Verify a bank account before making external transfers.

POST /transfer/external/verify

Request Body:

{
  "accountNumber": "1234567890",
  "bankCode": "058"
}

Response:

{
  "success": true,
  "message": "Account verification successful",
  "data": {
    "accountNumber": "1234567890",
    "accountName": "John Doe",
    "bankCode": "058",
    "bankName": "GTBank",
    "bankLogo": "https://...",
    "verified": true
  }
}

External Bank Transfer

Transfer money to any Nigerian bank account.

POST /transfer/external

Request Body:

{
  "fromPayId": "mywallet123.wallet",
  "accountNumber": "1234567890",
  "bankCode": "058",
  "amount": 10000,
  "narration": "Payment to supplier",
  "reference": "PAY-456",
  "accountName": "John Doe"
}

Response:

{
  "success": true,
  "message": "External transfer completed successfully",
  "data": {
    "transactionId": "iNPAY-0987654321",
    "reference": "PAY-456",
    "fromPayId": "mywallet123.wallet",
    "toAccountNumber": "1234567890",
    "toAccountName": "John Doe",
    "bankCode": "058",
    "bankName": "GTBank",
    "amount": 10000,
    "narration": "Payment to supplier",
    "status": "completed",
    "completedAt": "2025-09-14T10:30:00.000Z"
  }
}

📊 Transaction Endpoints

Get Transaction Status

Check the status of a transaction.

GET /transaction/status?reference=unique-ref-123

Response (Completed Payment):

{
  "success": true,
  "message": "Transaction status retrieved successfully",
  "data": {
    "reference": "unique-ref-123",
    "type": "virtual_payid",
    "payId": "mydyn456.dpid",
    "status": "completed",
    "verified": true,
    "customerEmail": "customer@example.com",
    "customerName": "Customer",
    "amount": 100000,
    "createdAt": "2025-09-14T10:00:00.000Z",
    "updatedAt": "2025-09-14T10:15:00.000Z"
  }
}

Response (Pending Payment):

{
  "success": true,
  "message": "Transaction status retrieved successfully",
  "data": {
    "reference": "unique-ref-123",
    "type": "virtual_account",
    "accountNumber": "1036262911",
    "status": "pending",
    "verified": false,
    "customerEmail": "customer@example.com",
    "customerName": "Customer",
    "amount": 100000,
    "createdAt": "2025-09-14T10:00:00.000Z",
    "updatedAt": "2025-09-14T10:00:00.000Z"
  }
}

Note: The amount field behavior:

When status is pending: Returns the expected amount (in kobo) that was specified when creating the virtual account/PayID
When status is completed: Returns the actual amount received (in kobo) from the transaction record

This ensures:

Backward compatibility: amount is always a number, never null
Merchants see the expected amount while waiting for payment
Once payment is received, merchants see the actual amount (which may differ if user sent less than expected)
The status field clearly indicates whether payment is pending or completed

Verify Transaction

Manually verify a transaction.

POST /transaction/verify

Request Body:

{
  "reference": "unique-ref-123"
}

Response (Verified - Completed):

{
  "success": true,
  "message": "Transaction verified successfully",
  "data": {
    "reference": "unique-ref-123",
    "type": "virtual_account",
    "accountNumber": "1036262911",
    "status": "completed",
    "verified": true,
    "customerEmail": "customer@example.com",
    "customerName": "John Doe",
    "amount": 100000,
    "createdAt": "2025-09-14T10:00:00.000Z",
    "updatedAt": "2025-09-14T10:15:00.000Z"
  }
}

Response (Not Verified - Pending):

{
  "success": true,
  "message": "Payment verification completed",
  "data": {
    "reference": "unique-ref-123",
    "type": "virtual_account",
    "accountNumber": "1036262911",
    "status": "pending",
    "verified": false,
    "customerEmail": "customer@example.com",
    "customerName": "John Doe",
    "amount": 100000,
    "createdAt": "2025-09-14T10:00:00.000Z",
    "updatedAt": "2025-09-14T10:00:00.000Z"
  }
}

Note: The amount field behavior:

When status is pending: Returns the expected amount (in kobo) that was specified when creating the virtual account/PayID
When status is completed: Returns the actual amount received (in kobo) from the transaction record

This ensures:

Backward compatibility: amount is always a number, never null
Merchants see the expected amount while waiting for payment
Once payment is received, merchants see the actual amount (which may differ if user sent less than expected)
The status field clearly indicates whether payment is pending or completed

🏪 Utility Endpoints

Get Bank List

Retrieve the list of supported banks for external transfers.

GET /banks

Response:

{
  "success": true,
  "message": "Bank list retrieved successfully",
  "data": {
    "banks": [
      {
        "bankCode": "058",
        "bankName": "GTBank",
        "logoUrl": "https://..."
      },
      {
        "bankCode": "011",
        "bankName": "First Bank",
        "logoUrl": "https://..."
      }
    ],
    "total": 25
  }
}

Health Check

Check the API server status.

GET /health

Response:

{
  "success": true,
  "message": "Proxy server is healthy",
  "timestamp": "2025-09-14T10:30:00.000Z",
  "version": "1.0.0"
}

🚨 Error Responses

All endpoints return consistent error responses:

{
  "success": false,
  "message": "Error description",
  "code": "ERROR_CODE"
}

Common Error Codes

Code	Description
`INVALID_SECRET_KEY`	Secret key is invalid or inactive
`DUPLICATE_REFERENCE`	Reference already exists
`INVALID_AMOUNT`	Amount is below minimum (₦100)
`PAYID_NOT_FOUND`	PayID does not exist or is inactive
`INSUFFICIENT_FUNDS`	Insufficient funds in source wallet
`EXTERNAL_ACCOUNT_VERIFICATION_FAILED`	Failed to verify external bank account

📝 Request/Response Format

Headers

All requests should include:

Content-Type: application/json
Authorization: Bearer sk_live_your_secret_key_here

Amount Format

All amounts are specified in kobo:

₦100.00 = 10000 kobo
₦500.00 = 50000 kobo
₦1000.00 = 100000 kobo

Response Format

All responses follow this structure:

{
  "success": boolean,
  "message": string,
  "data": object | null,
  "code": string | null
}

Next Steps:

GraphQL API Reference - Learn about GraphQL operations
Resources - Addons and integration tools
Webhooks Guide - Handle real-time notifications

🔗 Base URL​

🔑 Authentication​

📋 PayID Endpoints​

Create Dynamic PayID​

Create Static PayID​

Verify PayID​

🏦 Virtual Account Endpoints​

Create Virtual Account​

💸 Transfer Endpoints​

PayID-to-PayID Transfer​

Verify External Account​

External Bank Transfer​

📊 Transaction Endpoints​

Get Transaction Status​

Verify Transaction​

🏪 Utility Endpoints​

Get Bank List​

Health Check​

🚨 Error Responses​

Common Error Codes​

📝 Request/Response Format​

Headers​

Amount Format​

Response Format​

🔗 Base URL

🔑 Authentication

📋 PayID Endpoints

Create Dynamic PayID

Create Static PayID

Verify PayID

🏦 Virtual Account Endpoints

Create Virtual Account

💸 Transfer Endpoints

PayID-to-PayID Transfer

Verify External Account

External Bank Transfer

📊 Transaction Endpoints

Get Transaction Status

Verify Transaction

🏪 Utility Endpoints

Get Bank List

Health Check

🚨 Error Responses

Common Error Codes

📝 Request/Response Format

Headers

Amount Format

Response Format