Piaxis API Documentation

Core Services

Quick Links:

• Authentication & Security - Authentication methods, OAuth2 flow, security best practices

• SDKs - Official SDK packages, import names, and coverage notes

• Payment Processing API - Direct payment processing with comprehensive examples

• Escrow API - Escrow transactions, term fulfillment, release and reverse operations

• Direct Disbursements API - Direct bulk payments with immediate processing and comprehensive examples

• Escrow Disbursements API - Conditional bulk payments with term fulfillment requirements

• Webhook Events & Integration - Event handling, security, monitoring, and integration examples

Base URLs

Authentication Methods

The piaxis API supports multiple authentication methods depending on your use case:

Required Headers

Baseline headers for API-key authenticated requests:

Content-Type: application/json
api-key: YOUR_MERCHANT_API_KEY
User-Agent: YourApp/1.0

Merchant-secured escrow and disbursement routes also require:

X-piaxis-Client-ID: YOUR_MERCHANT_CLIENT_ID

Store that value in your server environment as PIAXIS_CLIENT_ID. It is required on the merchant-secured route families documented under Escrows, Direct Disbursements, Escrow Disbursements, and GET /api/merchant-payments.

Optional but Recommended:

X-Idempotency-Key: unique_request_id
X-Request-ID: custom_tracking_id

Supported Payment Methods

Supported Currencies

Standard Limits

Rate Limit Headers

All API responses include rate limiting information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642694400
X-RateLimit-Retry-After: 3600

Handling Rate Limits:

When you exceed rate limits, the API returns HTTP 429 with retry information:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "retry_after": 3600
  }
}

Standard Response Structure

All successful API responses follow this structure:

{
  "status": "success",
  "data": {},
  "meta": {
    "request_id": "req_1234567890abcdef",
    "timestamp": "2024-01-15T10:30:00Z",
    "api_version": "2024-01-01"
  }
}

Error Response Structure

Error responses provide detailed information for debugging:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more fields are invalid",
    "details": {
      "field": "amount",
      "reason": "Amount must be greater than 0"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_1234567890abcdef",
    "documentation_url": "https://api.gopiaxis.com/api/docs/"
  }
}

Common Error Codes

Sandbox Environment

Use the sandbox environment for testing and development:

• Base URL: https://sandbox.api.gopiaxis.com/api

• Public docs: https://api.gopiaxis.com/api/docs/

• Access: Request sandbox credentials from Piaxis before running live-flow tests

Test Credentials:

• API Key: YOUR_SANDBOX_API_KEY

• Client ID: YOUR_SANDBOX_CLIENT_ID

• Webhook Secret: YOUR_SANDBOX_WEBHOOK_SECRET

Test Data

Use the sandbox numbers, cards, and webhook secrets issued for your merchant account. If a scenario requires special fixtures, prefer the examples in this documentation or the SDK sandbox guides.

API Integration

Official SDKs are available for the public Payment API surface:

• SDK reference

• Python SDK: https://github.com/piaxepay/python-sdk

• TypeScript SDK: https://github.com/piaxepay/typescript-sdk

For raw HTTP integrations or for fields not yet wrapped by the SDKs, you can also use standard HTTP clients in your preferred language:

• Python: Use requests or httpx library

• Node.js: Use axios or fetch

• PHP: Use Guzzle or cURL

• Ruby: Use HTTParty or Net::HTTP

Development Tools

• API Reference: Available in this documentation

• AI-friendly Markdown: /api/docs/piaxis-api-integration-guide.md

• AI discovery file: /api/docs/llms.txt

• Postman Collection: Contact support for access

• OpenAPI Spec: /openapi.json endpoint on API server

• Testing Environment: Sandbox environment available

Quick Start Example

Here’s a complete example of processing a payment:

 import requests

 # 1. Create a payment
 payment_data = {
     "amount": 50000,
     "currency": "UGX",
     "payment_method": "mtn",
     "user_info": {
         "email": "[email protected]",
         "phone_number": "+256700000000",
         "name": "John Doe"
     }
 }

 response = requests.post(
     "https://api.gopiaxis.com/api/payments/create",
     json=payment_data,
     headers={
         "api-key": "YOUR_API_KEY",
         "Content-Type": "application/json"
     }
 )

For merchant-secured escrow and disbursement requests, add:

.. sourcecode:: http

   X-piaxis-Client-ID: YOUR_MERCHANT_CLIENT_ID

 response.raise_for_status()

 payment = response.json()
 print(f"Payment created: {payment['payment_id']}")
 print(f"Status: {payment['status']}")
 print(f"Amount: {payment['amount']} {payment['currency']}")

Documentation & Guides

• Public docs: https://api.gopiaxis.com/api/docs/

• Endpoint catalog: External API Endpoints

• Authentication guide: Authentication & Security

• SDK reference: SDKs

Developer Support

• Email: api-support@gopiaxis.com

Community & Learning

Emergency Support

For critical production issues:

• Email: emergency@gopiaxis.com

Include the following information in emergency requests:

• Merchant ID

• Transaction/Payment ID (if applicable)

• Error messages and timestamps

• Impact description