API Reference

Authentication

All API requests must be authenticated using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your merchant dashboard. Keep your API keys secure and never expose them in client-side code.

Base URL

All API requests should be made to:

https://api.avantulopay.com/v1

Rate Limits

API requests are limited to 100 requests per minute per API key. Rate limit information is included in response headers:

• X-RateLimit-Limit: Request limit per minute
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Time when limit resets

Wallets

Get Wallet Balance

GET /wallets/{walletId}/balance

Response:

{
  "walletId": "wal_1234567890",
  "currency": "USD",
  "balances": {
    "green": "1750.00",
    "yellow": "750.00",
    "red": "250.00",
    "total": "2750.00"
  }
}

List Transactions

GET /wallets/{walletId}/transactions?limit=20&offset=0

Payments

Create Payment

POST /payments

{
  "amount": "100.00",
  "currency": "USD",
  "description": "Order #12345",
  "redirectUrl": "https://example.com/success",
  "webhookUrl": "https://example.com/webhook"
}

Get Payment Status

GET /payments/{paymentId}

Transfers

Create Transfer

POST /transfers

{
  "recipient": "user@example.com",
  "amount": "50.00",
  "currency": "USD",
  "note": "Payment for services"
}

Webhooks

Webhooks allow you to receive real-time notifications about events in your account. Configure webhook endpoints in your merchant dashboard.

Webhook Events

• payment.completed - Payment successfully processed
• payment.failed - Payment failed
• transfer.completed - Transfer completed
• wallet.credited - Wallet received funds

Webhook Security

All webhooks are signed using HMAC-SHA256. Verify the signature by comparing the X-Avantulo-Signature header with the computed hash of the request body.

Error Handling

API errors follow a consistent format:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient funds in wallet",
    "details": {
      "available": "50.00",
      "required": "100.00"
    }
  }
}