API Reference

Integrate Vaendora into your custom application using our REST API. This guide covers authentication, endpoints, and webhooks.

REST API

Standard HTTP endpoints for all operations

API Keys

Secure authentication using API keys

Webhooks

Real-time notifications for events

Test Mode

Test integrations without real money

Authentication

All API requests require authentication using your API key:

Getting Your API Keys

  1. Log in to your Vaendora dashboard
  2. Go to Settings → API Keys
  3. Copy your Merchant ID and API Key

Using API Keys

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY
X-Merchant-ID: YOUR_MERCHANT_ID

Test vs Live Keys

  • Test API Key - Use for development and testing. Transactions are simulated.
  • Live API Key - Use for production. Real money is transferred.
Keep Keys Secret
Never expose your API keys in client-side code, public repositories, or share them with unauthorized parties.

Base URL

All API requests use the following base URL:

https://api.vaendora.com

API Endpoints

Initialize Payment

Create a new payment request:

POST /api/woocommerce/init-payment
{
  "merchant_id": "your-merchant-id",
  "amount": 5000,
  "currency": "NGN",
  "customer_email": "customer@example.com",
  "customer_name": "John Doe",
  "order_id": "ORDER-123",
  "callback_url": "https://yoursite.com/payment-complete",
  "test_mode": false
}

Response

{
  "success": true,
  "data": {
    "payment_reference": "VPY-1234567890-ABCDEF",
    "payment_url": "https://app.vaendora.com/wc-pay/VPY-1234567890-ABCDEF",
    "amount": 5000,
    "expires_in": 1800
  }
}

Verify Payment

Check the status of a payment:

GET /api/woocommerce/verify-payment/:reference

Response

{
  "success": true,
  "data": {
    "reference": "VPY-1234567890-ABCDEF",
    "status": "completed",
    "amount": 5000,
    "amount_paid": 5000,
    "fee": 75,
    "net_amount": 4925,
    "customer_name": "John Doe",
    "paid_at": "2024-01-15T10:30:00Z"
  }
}

Payment Status Values

StatusDescription
pendingAwaiting customer payment
completedPayment received and verified
failedPayment failed or was rejected
expiredPayment window expired

Webhooks

Receive real-time notifications when payment events occur:

Setting Up Webhooks

1

Configure Webhook URL

When initializing a payment, include a callback_url parameter.

2

Receive Notifications

Vaendora will POST to your URL when the payment status changes.

3

Verify and Process

Verify the webhook signature and update your order status.

Webhook Payload

{
  "event": "payment.completed",
  "data": {
    "reference": "VPY-1234567890-ABCDEF",
    "order_id": "ORDER-123",
    "status": "completed",
    "amount": 5000,
    "amount_paid": 5000,
    "customer_name": "John Doe",
    "paid_at": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2024-01-15T10:30:05Z"
}

Webhook Events

  • payment.completed - Payment was successful
  • payment.failed - Payment failed
  • payment.expired - Payment window expired

Verifying Webhooks

Always verify webhook authenticity:

  1. Check the X-Vaendora-Signature header
  2. Compare with your calculated HMAC signature
  3. Verify the timestamp to prevent replay attacks
Always Verify
Never process webhooks without verifying the signature. This prevents fraudulent requests from updating your orders.

Error Handling

API errors return appropriate HTTP status codes:

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
404Not Found - Resource doesn't exist
500Server Error - Contact support

Error Response Format

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Rate Limits

API requests are rate limited to ensure fair usage:

  • 100 requests per minute per API key
  • Rate limit headers are included in responses
  • Exceeded limits return HTTP 429

Testing

Use test mode for development:

  • Set test_mode: true in payment requests
  • Use your Test API Key
  • Payments can be simulated without real money
  • Test references start with VPY-TEST

API Support

Need help with integration?