PesaVoucher Other Payments API

Live URL: https://payments.pesavoucher.com/api/v1/
Sandbox URL: https://sandbox.payments.pesavoucher.com/api/v1/

Live Testing Note To perform real live transactions or trigger a live test webhook, please contact us: support@pesavoucher.com Telegram: Join our channel → t.me/Dev_PesaVoucher

Overview

PesaVoucher provides a unified payment API focused on Paystack (Nigeria). This guide covers authentication, payment initiation, and webhook setup.

Authentication

All requests require these headers:

X-API-KEY: your_api_key
X-API-SECRET: your_api_secret
Content-Type: application/json

Get your credentials from your merchant dashboard.

Paystack Payment (Nigeria)

Endpoint: POST /api/v1/paystack/initiate

Supports: card, bank transfer, ussd, bank account

1. Card Payment

{
  "channel": "card",
  "amount": 5000,
  "customer_email": "customer@example.com",
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Doe"
  }
}

2. Bank Account Payment

{
  "channel": "bank",
  "amount": 5000,
  "customer_email": "customer@example.com",
  "bank": {
    "code": "057",
    "account_number": "0123456789"
  },
  "birthday": "1990-01-01"
}

3. Pay with Transfer (Dynamic Account)

{
  "channel": "transfer",
  "amount": 5000,
  "customer_email": "customer@example.com"
}

4. USSD Payment

{
  "channel": "ussd",
  "amount": 5000,
  "customer_email": "customer@example.com",
  "ussd": {
    "type": "737"
  }
}

Success Response

{
  "success": true,
  "message": "Payment initialized successfully",
  "data": {
    "payment_id": "12345",
    "reference": "T1234567890abcdef",
    "amount": 5000,
    "authorization_url": "https://checkout.paystack.com/xxxxxx",
    "access_code": "xxxxxx"
  }
}

Required Fields

Field	Required	Notes
`channel`	Yes	card, bank, transfer, ussd
`amount`	Yes	In Naira (e.g., 5000 = ₦50)
`customer_email`	Yes	Valid email

Webhook Setup (Payment Notifications)

Your Webhook URL

Set this in your merchant dashboard:
https://merchant.site.com/webhooks/pesavoucher

Paystack Success Callback (You Will Receive This)

{
  "event": "payment.success",
  "payment_id": "12345",
  "reference": "T1234567890abcdef",
  "amount": 5000,
  "currency": "NGN",
  "status": "success",
  "channel": "card",
  "paid_at": "2025-04-05T12:00:00Z",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "metadata": {
    "order_id": "12345"
  },
  "timestamp": "2025-04-05 12:00:00"
}

Headers Sent to Your Webhook

X-Callback-Source: Pesavoucher
X-Callback-Type: Payment-Success
Content-Type: application/json

Testing

Sandbox URL

https://sandbox.payments.pesavoucher.com/api/v1/

Paystack Test Cards

Card Number	Result
4084084084084081	Success
5060666666666666666	Declined

Test Flow

Use sandbox URL + test API keys
Initiate payment
Complete with test card
Receive webhook instantly

Error Responses

{
  "success": false,
  "error": "Invalid amount",
  "timestamp": "2025-04-05 12:00:00"
}

Common Errors

Code	Message	Solution
400	Invalid email	Use valid email format
400	Amount must be ≥ 100	Minimum ₦1.00
401	Invalid credentials	Check API key/secret
429	Rate limit exceeded	Max 100 requests/min

Best Practices

Always respond to webhooks with 200 OK within 5 seconds
Make webhook handling idempotent (handle duplicates safely)
Store payment_id and reference for reconciliation
Use metadata to pass your internal order IDs
Never expose API keys in frontend code
Test thoroughly in sandbox before going live