Integration Guide

Get PayGate integrated into your application in minutes

Quick Start

1

Get Your API Key

Sign up for PayGate and generate your API keys from the dashboard.

Your secret key will look like: sk_live_xxxxxxxxxxxxx

2

Install SDK or Use REST API

Choose your preferred integration method.

npm install @paygate/sdk
# or use REST API directly with curl
3

Create Your First Payment

Initialize a payment transaction with a few lines of code.

import PayGate from '@paygate/sdk';

const paygate = new PayGate('sk_live_xxxxx');

const payment = await paygate.payments.create({
  amount: 10000,
  currency: 'NGN',
  customer_email: 'customer@example.com',
  description: 'Order #12345'
});

console.log(payment.payment_link);
4

Handle Webhooks

Listen for payment events and update your application state.

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

  if (event.type === 'payment.completed') {
    const payment = event.data;
    // Update order status
    updateOrderStatus(payment.id, 'paid');
  }

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

Implementation Examples

E-Commerce Checkout

Accept payments for online store orders with automatic inventory management.

async function handleCheckout(cartItems, customerEmail) {
  const total = cartItems.reduce((sum, item) => 
    sum + (item.price * item.quantity), 0
  );

  const payment = await paygate.payments.create({
    amount: total * 100, // Amount in cents
    currency: 'NGN',
    customer_email: customerEmail,
    description: `Order: ${cartItems.map(i => i.name).join(', ')}`,
    metadata: {
      order_id: generateOrderId(),
      items: cartItems
    }
  });

  // Redirect customer to payment page
  window.location.href = payment.payment_link;
}

Marketplace with Escrow

Hold buyer funds until seller completes the transaction.

async function createMarketplaceTransaction(buyer, seller, service) {
  const payment = await paygate.payments.create({
    amount: service.price * 100,
    currency: 'NGN',
    customer_email: buyer.email,
    description: `Service: ${service.name} - Seller: ${seller.name}`,
    escrow: true,
    metadata: {
      buyer_id: buyer.id,
      seller_id: seller.id,
      service_id: service.id,
      type: 'marketplace'
    }
  });

  // Save transaction reference
  await db.transactions.create({
    paygate_id: payment.id,
    buyer_id: buyer.id,
    seller_id: seller.id,
    status: 'awaiting_payment'
  });

  return payment;
}

SaaS Subscription Billing

Charge customers on a recurring basis for your service.

async function setupSubscription(user, plan) {
  // Create initial payment
  const payment = await paygate.payments.create({
    amount: plan.monthly_price * 100,
    currency: 'NGN',
    customer_email: user.email,
    customer_id: user.id,
    description: `Subscription: ${plan.name}`,
    metadata: {
      plan_id: plan.id,
      user_id: user.id,
      billing_type: 'subscription'
    }
  });

  // Store subscription details
  await db.subscriptions.create({
    user_id: user.id,
    plan_id: plan.id,
    paygate_customer_id: user.id,
    status: 'active',
    next_billing_date: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)
  });

  return payment;
}

Security Best Practices

Always keep your secret API key private - never expose it in client-side code

Verify webhook signatures to ensure requests come from PayGate

Use HTTPS for all communication with the PayGate API

Store sensitive data (API keys, customer info) in environment variables

Implement proper rate limiting to protect against abuse

Validate all user inputs before sending to PayGate

Use idempotency keys for critical operations to prevent duplicate charges

Testing with Sandbox

Sandbox Environment

Use our sandbox environment to test your integration before going live.

// Sandbox credentials
API Key: sk_sandbox_xxxxxxxxxxxxx
Base URL: https://sandbox-api.paygate.liper.io

// Test card numbers
Visa: 4242 4242 4242 4242
Mastercard: 5555 5555 5555 4444
Verve: 5061 0411 0511 0010

Test Successful Payment

Use test card 4242 4242 4242 4242 with any future expiry date

Test Failed Payment

Use test card 4000 0000 0000 0002 to trigger a decline

Test 3D Secure

Use test card 4000 0027 6000 3184 for 3D Secure flow

View Test Transactions

All test transactions appear in your sandbox dashboard

Troubleshooting

401 Unauthorized Error

Check that your API key is correct and being sent in the Authorization header. Make sure you're using your secret key, not the publishable key.

Webhook Events Not Received

Verify your webhook endpoint is publicly accessible and returning a 200 status code. Check your endpoint URL in the PayGate dashboard.

Payment Amount Mismatch

Ensure amounts are sent in the smallest currency unit (e.g., cents for USD, kobo for NGN). Multiply by 100 if working with decimal amounts.

CORS Issues in Browser

Use your backend API as a proxy for PayGate requests. Never make API calls directly from the browser.

Rate Limiting (429 Error)

Implement exponential backoff for retries. Contact support if you need higher rate limits.

Ready to Deploy?

You've completed the integration guide. Here's what's next:

Test your implementation in the sandbox environment

Review our API documentation for advanced features

Deploy to production with your live API keys

Monitor transactions in your PayGate dashboard

View Full API Docs