External API Documentation

Core Services

Quick Links:

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

• 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

All API requests must include these headers:

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

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": {
    // Response data specific to the endpoint
  },
  "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://docs.gopiaxis.com/errors/validation"
  }
}

Common Error Codes

Sandbox Environment

Use the sandbox environment for testing and development:

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

• Dashboard: https://sandbox-dashboard.gopiaxis.com

• Test Data: Predefined test phone numbers, cards, and scenarios

Test Credentials: - API Key: pk_test_1234567890abcdef - Client ID: test_096b723a-45c5-4957-94d7-747835136265 - Webhook Secret: whsec_test_abcdef1234567890

Test Data

Test Phone Numbers: - Success: +256700000000 to +256700000050 - Failure: +256700000051 to +256700000099 - Insufficient Funds: +256700001000 - Timeout: +256700002000

Test Card Numbers: - Visa Success: 4111111111111111 - Visa Decline: 4000000000000002 - Mastercard Success: 5555555555554444 - Mastercard Insufficient: 5105105105105100

API Integration

Since official SDKs are currently under development, you can integrate with Piaxis using 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

• 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",
    "reference": "ORDER-2024-001",
    "description": "Product purchase",
    "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"
    }
)

if response.status_code == 200:
    payment = response.json()
    print(f"Payment created: {payment['data']['payment_id']}")
    print(f"Status: {payment['data']['status']}")
    print(f"Payment URL: {payment['data']['payment_url']}")
else:
    print(f"Error: {response.text}")

Documentation & Guides

• API Reference: https://docs.gopiaxis.com/api/

• Integration Guides: https://docs.gopiaxis.com/guides/

• Best Practices: https://docs.gopiaxis.com/best-practices/

• FAQ: https://docs.gopiaxis.com/faq/

Developer Support

• Email: api-support@piaxis.com

• Developer Forum: https://forum.gopiaxis.com/

• GitHub: https://github.com/piaxis/

• Status Page: https://status.gopiaxis.com/

Community & Learning

• Developer Newsletter: https://gopiaxis.com/newsletter/

• Blog: https://blog.gopiaxis.com/

• Webinars: https://gopiaxis.com/webinars/

• Case Studies: https://gopiaxis.com/case-studies/

Emergency Support

For critical production issues:

• Email: emergency@piaxis.com

• Phone: +256-XXX-XXXX (24/7 for enterprise customers)

• Slack: Available for enterprise customers

Include the following information in emergency requests: - Merchant ID - Transaction/Payment ID (if applicable) - Error messages and timestamps - Impact description