PayID Creation

PayIDs are unique payment identifiers that allow customers to send money using simple, memorable addresses. iNPAY supports both dynamic and static PayIDs to fit different use cases.

🎯 What are PayIDs?

PayIDs are user-friendly payment addresses that make it easy for customers to send money or merchant to recieve payment without needing to know complex bank account details. Think of them as iNPAY username for money!

Examples:

• merchant123.dpid - Dynamic PayID (auto-generated)
• mystore.spid - Static PayID (custom branded)

🔄 Dynamic PayIDs

Dynamic PayIDs are automatically generated and perfect for one-time payments, e-commerce transactions, or when you need a unique payment link for each transaction.

When to Use Dynamic PayIDs

• E-commerce: One payment link per order
• Invoice Payments: Unique link for each invoice
• Donations: Individual donation links
• Event Tickets: Payment link for each ticket purchase

Creating a Dynamic PayID

REST API

curl -X POST https://api.inpaycheckout.com/api/v1/developer/payid/dynamic \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-123",
    "metadata": {
      "orderId": "ORDER-456",
      "customerEmail": "customer@example.com",
      "productName": "Premium Plan"
    }
  }'

GraphQL

mutation CreateDynamicPayId($input: CreateDynamicPayIdInput!) {
  createDynamicPayId(input: $input) {
    success
    message
    data {
      payId
      name
      reference
      expiresAt
      status
      type
    }
  }
}

Variables:

{
  "input": {
    "reference": "order-123",
    "metadata": {
      "orderId": "ORDER-456",
      "customerEmail": "customer@example.com",
      "productName": "Premium Plan"
    }
  }
}

Response Example

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

🏷️ Static PayIDs

Static PayIDs are custom-branded payment addresses that remain consistent. Perfect for businesses, freelancers, or anyone who wants a memorable payment address.

When to Use Static PayIDs

• Business Payments: Consistent payment address for your business
• Freelancer Invoices: Memorable payment link for clients
• Subscription Services: Recurring payment collection
• Marketplace Sellers: Branded payment addresses

Creating a Static PayID

REST API

curl -X POST https://api.inpaycheckout.com/api/v1/developer/payid/static \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom PayID",
    "reference": "business-setup-456",
    "metadata": {
      "businessUnit": "sales",
      "region": "lagos",
      "customerEmail": "business@example.com",
      "phoneNumber": "+2348123456789"
    }
  }'

GraphQL

mutation CreateStaticPayId($input: CreateStaticPayIdInput!) {
  createStaticPayId(input: $input) {
    success
    message
    data {
      payId
      name
      reference
      status
      type
    }
  }
}

Variables:

{
  "input": {
    "name": "My Custom PayID",
    "reference": "business-setup-456",
    "metadata": {
      "businessUnit": "sales",
      "region": "lagos",
      "customerEmail": "business@example.com",
      "phoneNumber": "+2348123456789"
    }
  }
}

Response Example

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

💻 Code Examples

JavaScript/Node.js

const axios = require('axios');

class PayIDManager {
  constructor(secretKey, baseUrl = 'https://api.inpaycheckout.com') {
    this.secretKey = secretKey;
    this.baseUrl = baseUrl;
    this.headers = {
      'Authorization': `Bearer ${secretKey}`,
      'Content-Type': 'application/json'
    };
  }

  // Create Dynamic PayID
  async createDynamicPayID(reference, metadata = {}) {
    try {
      const response = await axios.post(
        `${this.baseUrl}/api/v1/developer/payid/dynamic`,
        {
          reference,
          metadata
        },
        { headers: this.headers }
      );
      
      return response.data;
    } catch (error) {
      console.error('Error creating dynamic PayID:', error.response?.data || error.message);
      throw error;
    }
  }

  // Create Static PayID
  async createStaticPayID(name, reference, metadata = {}) {
    try {
      const response = await axios.post(
        `${this.baseUrl}/api/v1/developer/payid/static`,
        {
          name,
          reference,
          metadata
        },
        { headers: this.headers }
      );
      
      return response.data;
    } catch (error) {
      console.error('Error creating static PayID:', error.response?.data || error.message);
      throw error;
    }
  }

  // Verify PayID
  async verifyPayID(payId) {
    try {
      const response = await axios.post(
        `${this.baseUrl}/api/v1/developer/payid/verify`,
        { payId },
        { headers: this.headers }
      );
      
      return response.data;
    } catch (error) {
      console.error('Error verifying PayID:', error.response?.data || error.message);
      throw error;
    }
  }
}

// Usage Examples
const payIDManager = new PayIDManager(process.env.INPAY_SECRET_KEY);

// Create dynamic PayID for e-commerce
const dynamicPayID = await payIDManager.createDynamicPayID('order-123', {
  orderId: 'ORDER-456',
  customerEmail: 'customer@example.com',
  productName: 'Premium Plan',
  amount: 50000 // ₦500.00
});

// Create static PayID for business
const staticPayID = await payIDManager.createStaticPayID('My Store', 'business-setup', {
  businessUnit: 'sales',
  region: 'lagos',
  customerEmail: 'business@example.com'
});

// Verify PayID before using
const verification = await payIDManager.verifyPayID('merchant123.dpid');

Python

import requests
import os

class PayIDManager:
    def __init__(self, secret_key, base_url='https://api.inpaycheckout.com'):
        self.secret_key = secret_key
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {secret_key}',
            'Content-Type': 'application/json'
        }

    def create_dynamic_payid(self, reference, metadata=None):
        """Create a dynamic PayID"""
        url = f"{self.base_url}/api/v1/developer/payid/dynamic"
        data = {
            'reference': reference,
            'metadata': metadata or {}
        }
        
        response = requests.post(url, headers=self.headers, json=data)
        response.raise_for_status()
        return response.json()

    def create_static_payid(self, name, reference, metadata=None):
        """Create a static PayID"""
        url = f"{self.base_url}/api/v1/developer/payid/static"
        data = {
            'name': name,
            'reference': reference,
            'metadata': metadata or {}
        }
        
        response = requests.post(url, headers=self.headers, json=data)
        response.raise_for_status()
        return response.json()

    def verify_payid(self, pay_id):
        """Verify a PayID"""
        url = f"{self.base_url}/api/v1/developer/payid/verify"
        data = {'payId': pay_id}
        
        response = requests.post(url, headers=self.headers, json=data)
        response.raise_for_status()
        return response.json()

# Usage Examples
payid_manager = PayIDManager(os.getenv('INPAY_SECRET_KEY'))

# Create dynamic PayID for e-commerce
dynamic_payid = payid_manager.create_dynamic_payid('order-123', {
    'orderId': 'ORDER-456',
    'customerEmail': 'customer@example.com',
    'productName': 'Premium Plan',
    'amount': 50000  # ₦500.00
})

# Create static PayID for business
static_payid = payid_manager.create_static_payid('My Store', 'business-setup', {
    'businessUnit': 'sales',
    'region': 'lagos',
    'customerEmail': 'business@example.com'
})

# Verify PayID before using
verification = payid_manager.verify_payid('merchant123.dpid')

PHP

<?php
class PayIDManager {
    private $secretKey;
    private $baseUrl;
    
    public function __construct($secretKey, $baseUrl = 'https://api.inpaycheckout.com') {
        $this->secretKey = $secretKey;
        $this->baseUrl = $baseUrl;
    }
    
    private function makeRequest($method, $endpoint, $data = null) {
        $url = $this->baseUrl . $endpoint;
        $headers = [
            'Authorization: Bearer ' . $this->secretKey,
            'Content-Type: application/json'
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        
        if ($data && in_array($method, ['POST', 'PUT', 'PATCH'])) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode >= 400) {
            throw new Exception('API Error: ' . $response);
        }
        
        return json_decode($response, true);
    }
    
    public function createDynamicPayID($reference, $metadata = []) {
        return $this->makeRequest('POST', '/api/v1/developer/payid/dynamic', [
            'reference' => $reference,
            'metadata' => $metadata
        ]);
    }
    
    public function createStaticPayID($name, $reference, $metadata = []) {
        return $this->makeRequest('POST', '/api/v1/developer/payid/static', [
            'name' => $name,
            'reference' => $reference,
            'metadata' => $metadata
        ]);
    }
    
    public function verifyPayID($payId) {
        return $this->makeRequest('POST', '/api/v1/developer/payid/verify', [
            'payId' => $payId
        ]);
    }
}

// Usage Examples
$payidManager = new PayIDManager($_ENV['INPAY_SECRET_KEY']);

// Create dynamic PayID for e-commerce
$dynamicPayID = $payidManager->createDynamicPayID('order-123', [
    'orderId' => 'ORDER-456',
    'customerEmail' => 'customer@example.com',
    'productName' => 'Premium Plan',
    'amount' => 50000 // ₦500.00
]);

// Create static PayID for business
$staticPayID = $payidManager->createStaticPayID('My Store', 'business-setup', [
    'businessUnit' => 'sales',
    'region' => 'lagos',
    'customerEmail' => 'business@example.com'
]);

// Verify PayID before using
$verification = $payidManager->verifyPayID('merchant123.dpid');
?>

🔍 PayID Verification

Before using any PayID for transfers, always verify it first:

curl -X POST https://api.inpaycheckout.com/api/v1/developer/payid/verify \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }
}

📊 PayID Types Comparison

Feature	Dynamic PayID	Static PayID
Generation	Auto-generated	Custom name
Expiration	Yes (24 hours)	No
Use Case	One-time payments	Recurring payments
Branding	Generic	Custom branded
Reference	Required	Required
Metadata	Supported	Supported

🚨 Error Handling

Common Errors

Duplicate Reference

{
  "success": false,
  "message": "Reference already exists",
  "code": "DUPLICATE_REFERENCE"
}

Invalid PayID Format

{
  "success": false,
  "message": "PayID not found or inactive",
  "code": "PAYID_NOT_FOUND"
}

Error Handling Example

try {
  const payID = await payIDManager.createDynamicPayID('order-123');
  console.log('PayID created:', payID.data.payId);
} catch (error) {
  if (error.response?.data?.code === 'DUPLICATE_REFERENCE') {
    console.log('Reference already exists, using existing PayID');
    // Handle duplicate reference
  } else {
    console.error('Failed to create PayID:', error.message);
  }
}

💡 Best Practices

✅ Do's

• Use unique references: Ensure each reference is unique across your system
• Include meaningful metadata: Add relevant information for tracking
• Verify before use: Always verify PayIDs before transfers
• Handle expiration: Dynamic PayIDs expire after 24 hours
• Monitor payments: Set up webhooks to track payments

❌ Don'ts

• Don't reuse references: Each PayID should have a unique reference
• Don't expose PayIDs: Keep PayIDs secure like any payment information
• Don't ignore expiration: Check expiration dates for dynamic PayIDs
• Don't skip verification: Always verify PayIDs before transfers

🎯 Use Case Examples

E-commerce Store

// Create PayID for each order
const payID = await payIDManager.createDynamicPayID(`order-${orderId}`, {
  orderId: orderId,
  customerEmail: customer.email,
  productName: order.productName,
  amount: order.totalAmount,
  shippingAddress: customer.address
});

// Send PayID to customer
await sendPaymentLink(customer.email, payID.data.payId);

Freelancer Invoice

// Create static PayID for business
const payID = await payIDManager.createStaticPayID('john-doe-design', 'business-setup', {
  businessType: 'freelancer',
  services: ['web-design', 'branding'],
  contactEmail: 'john@example.com'
});

// Use in invoice
const invoice = {
  payID: payID.data.payId,
  amount: 150000, // ₦1,500.00
  description: 'Website Design Project'
};

---

Next Steps:

• Virtual Accounts Guide - Create virtual account payments
• Transfers Guide - Send money between PayIDs
• Webhooks Guide - Handle payment notifications