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.

Required for all money-moving POST requests:

X-Idempotency-Key: unique_request_id

Recommended for server-to-server integrity, and required when your merchant profile is configured for signed requests:

X-piaxis-Timestamp: unix_timestamp_seconds
X-piaxis-Signature: sha256=<hmac_sha256>

The request signature is computed over METHOD, request path, timestamp, and the SHA256 hash of the raw JSON body, using your merchant API secret. Signed requests protect against replay and body tampering between your server and Piaxis.

Recommended for tracing:

X-Request-ID: custom_tracking_id

Supported Payment Methods

Supported Currencies

Standard Limits

Handling Rate Limits:

When you exceed rate limits, the API returns HTTP 429 with retry information. Do not build clients around fixed thresholds; use the response guidance and retry conservatively:

{
  "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: available from protected API documentation for approved integrators

• 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",
         "X-piaxis-Client-ID": "YOUR_MERCHANT_CLIENT_ID",
         "X-Idempotency-Key": "payment-0001",
         "Content-Type": "application/json"
     }
 )

For merchant-secured payment, 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