API Reference
PayAxis API
Instant USDC cross-border payments across Gulf corridors. Settle in under 2 minutes at a fraction of traditional wire costs.
Base URL
https://payaxis-api-production.up.railway.app
Authentication
All requests require a Bearer token. Keys are scoped to sandbox or production environments.
API Key Format
Keys follow the format pk_{env}_{id}_{secret}. Never share your secret key.
Sandbox
pk_test_...
Production
pk_live_...
# Include in every request
curl https://payaxis-api-production.up.railway.app/v1/wallets \
-H "Authorization: Bearer pk_test_39b0ea21_..." \
-H "Content-Type: application/json"
Error Handling
Standard HTTP status codes. All errors return JSON with a machine-readable code.
{
"error": {
"code": "WALLET_NOT_FOUND",
"message": "Source wallet not found",
"request_id": "req_abc123"
}
}
MISSING_FIELD
400
Required parameter missing
unauthorized
401
Missing or invalid API key
rate_limit_exceeded
429
Too many requests
PAYMENT_FAILED
500
Circle transfer failed
WALLET_CREATION_FAILED
500
Could not provision wallet
KYB_PENDING
409
KYB already submitted
Rate Limits
Rate limits per API key per minute. Sandbox keys are exempt.
| Plan | Req/min | Monthly Volume |
|---|---|---|
| Starter | 100 | $10,000 |
| Growth | 1,000 | $100,000 |
| Scale | 10,000 | $1,000,000 |
| Enterprise | 50,000 | Unlimited |
Wallets
USDC wallets on Base Sepolia. Each wallet has a unique blockchain address for receiving deposits.
POST/v1/walletsCreate a wallet
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| contact_name | string | required | Name of the contact or supplier |
| contact_email | string | optional | Email address of the contact |
Example Request
curl -X POST https://payaxis-api-production.up.railway.app/v1/wallets \
-H "Authorization: Bearer pk_test_..." \
-H "Content-Type: application/json" \
-d '{"contact_name":"Ahmed Al Farsi","contact_email":"ahmed@supplier.ae"}'
Example Response
{
"wallet": {
"id": "de862fc3-4c8f-4e6e-8ccb-893566f3df53",
"contact_name": "Ahmed Al Farsi",
"balance": "0.00",
"deposit_address": {
"address": "0x8a8d534083d48f32deb2c7f3100d756d687350f2",
"chain": "BASE-SEPOLIA"
},
"status": "active"
}
}
GET/v1/walletsList all wallets
Returns all wallets with live USDC balances fetched from Circle.
Payments
Initiate USDC transfers. Payments settle on-chain in under 2 minutes. Status syncs automatically every 30 seconds.
POST/v1/paymentsInitiate a USDC payment
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| source_wallet_id | uuid | required | Source wallet to debit |
| destination_wallet_id | uuid | optional* | PayAxis destination wallet |
| destination_address | string | optional* | External blockchain address (0x...) |
| amount | string | required | Amount in USDC (e.g. "100.00") |
| corridor | string | optional | e.g. "UAE-India" for FX routing |
| reference | string | optional | Your internal reference ID |
* Either destination_wallet_id or destination_address is required.
Example Request
curl -X POST https://payaxis-api-production.up.railway.app/v1/payments \
-H "Authorization: Bearer pk_test_..." \
-H "Content-Type: application/json" \
-d '{
"source_wallet_id": "de862fc3-4c8f-4e6e-8ccb-893566f3df53",
"destination_wallet_id": "0f6f8568-c7e9-4135-a4e1-e49f9ddaa134",
"amount": "100",
"corridor": "UAE-India",
"reference": "INV-2026-001"
}'
Payment Status Lifecycle
pending
→
processing
→
delivered
Auto-synced from Circle every 30s. Poll GET /v1/payments/:id for real-time status.
GET/v1/paymentsList payments (last 50)
Returns the 50 most recent payments in descending order.
GET/v1/payments/:idGet payment with live status
Fetches payment and syncs status from Circle. Status updates to
delivered once confirmed on-chain.Corridors & FX
Supported payment routes with live FX rates and tier-based pricing.
GET/v1/corridorsList corridors with pricing
Example Response
{
"corridors": [{
"corridor": "UAE-India",
"fee_bps": 30,
"fee_percent": "0.30%",
"from_currency": "AED",
"to_currency": "INR",
"partner": "nium",
"estimated_arrival": "< 2 minutes"
}]
}
GET/v1/corridors/quote?corridor=UAE-India&amount=1000Get a live quote
Example Response
{
"quote": {
"send_amount": 1000,
"fee": 3.00,
"fee_percent": "0.300%",
"effective_rate": 92.997,
"recipient_gets": 92717.91,
"recipient_currency": "INR",
"estimated_arrival": "< 2 minutes"
}
}
GET/v1/corridors/fx?from=USD&to=INRGet live FX rate
Query params:
from (required), to (required), amount (optional, default 1).KYB / Compliance
Business verification to increase volume limits. Default limit is $10,000/month. Approved customers get up to $500,000/month.
POST/v1/kybSubmit KYB application
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| company_name | string | required | Legal company name |
| company_type | string | required | LLC, Corporation, Partnership |
| registration_number | string | required | Company registration number |
| country | string | required | ISO 2-letter code (e.g. AE) |
| director_name | string | required | Full name of director |
| director_email | string | required | Director email address |
| expected_monthly_volume | number | optional | Expected monthly USD volume |
GET/v1/kybGet KYB status and volume
{
"kyb_status": "pending_review",
"volume_limit_usd": 10000,
"volume_used_usd": 1250.00,
"volume_remaining_usd": 8750.00
}
Webhooks
Register HTTPS endpoints for real-time event notifications. All payloads are signed with HMAC-SHA256.
Webhook secrets are shown only once. Store them securely.
POST/v1/webhooksRegister a webhook
Request Body
| url | string | required | HTTPS endpoint URL |
| events | array | optional | Event types. Default: all. |
Event Types
| payment.completed | Payment delivered on-chain |
| payment.failed | Payment failed |
| wallet.funded | USDC deposit received |
Verifying Signatures
// Node.js
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
return 'sha256=' + expected === signature;
}
app.post('/webhooks/payaxis', (req, res) => {
if (!verifyWebhook(req.rawBody, req.headers['x-payaxis-signature'], process.env.WEBHOOK_SECRET))
return res.status(401).send('Invalid signature');
res.sendStatus(200);
});
API Keys
Manage API keys. Keys can be rotated without downtime.
POST/v1/api-keysCreate API key
Creates a new key. Raw key shown only once — save immediately.
POST/v1/api-keys/:id/rotateRotate a key
Atomically revokes old key and issues new one.
Corridors Reference
| Corridor | From | To | Fee Starter | Fee Growth | Partner |
|---|---|---|---|---|---|
| UAE-India | AED | INR | 0.30% | 0.25% | Nium |
| UAE-Pakistan | AED | PKR | 0.30% | 0.25% | Nium |
| UAE-Philippines | AED | PHP | 0.40% | 0.35% | Nium |
| UAE-China | USD | CNY | 0.40% | 0.35% | Airwallex |
| UAE-Bangladesh | AED | BDT | 0.40% | 0.35% | Nium |
Min fee $0.50/transaction. Max fee $50 (Starter), $40 (Growth).