Get started in minutes

This guide walks you through initiating your first payment collection from start to finish.

1. 1
   Get your API key

   Log in to your Aurax Pay dashboard, go to API Keys, and generate a new key. Choose TEST for development. Your key will look like axp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
2. 2
   Initiate a payment

   Send a POST /v1/payments request with the customer's details.

   cURLNode.jsPython

   Copy

   curl -X POST https://api.auraxpay.net/v1/payments \
     -H "Content-Type: application/json" \
     -H "x-api-key: axp_test_YOUR_KEY_HERE" \
     -d '{
       "amount": 5000,
       "channel": "MPESA",
       "buyerPhone": "+255712345678",
       "buyerName": "John Doe",
       "description": "Order #1042"
     }'

3. 3
   Read the response

   A successful request returns 201 Created with the transaction at PENDING status.

   Response 201Copy

   {
     "success": true,
     "transaction": {
       "id": "txn_01j2k3m4n5p6q7r8s9t0",
       "reference": "AXP-XXXXXX",
       "amount": 5000,
       "fee": 0,
       "netAmount": 5000,
       "channel": "MPESA",
       "status": "PENDING",
       "buyerPhone": "+255712345678",
       "buyerName": "John Doe",
       "description": "Order #1042",
       "createdAt": "2025-06-09T14: 30: 00.000Z"
     }
   }

4. 4
   Register your webhook & handle completion

   Payment processing is asynchronous. Register your endpoint via the API — the APIs & Secrets page in your dashboard also lets you do this with one click.

   Register webhook endpointCopy

   curl -X POST https://api.auraxpay.net/merchant/webhooks \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -d '{
       "url": "https://yourserver.com/webhooks/aurax",
       "events": ["payment.completed", "payment.failed"]
     }'

   ⚠️The response returns a secret (whsec_...) shown only once. Copy it immediately and store as AURAXPAY_WEBHOOK_SECRET. Use it to verify every incoming request.

   Also implement polling as a fallback — call GET /v1/payments/{reference} every 3 seconds until status is COMPLETED or FAILED. Webhooks typically arrive within 30 seconds but polling ensures you never miss a completion.

   Webhook payload (COMPLETED)Copy

   {
     "event": "payment.completed",
     "transaction": {
       "id": "txn_01j2k3m4n5p6q7r8s9t0",
       "reference": "AXP-XXXXXX",
       "status": "COMPLETED",
       "amount": 5000,
       "netAmount": 5000,
       "channel": "MPESA",
       "completedAt": "2025-06-09T14: 30: 45.000Z"
     }
   }

5. 5
   Go live

   When you're ready to accept real payments:

   • Generate a LIVE API key from your dashboard
   • Replace axp_test_ with your axp_live_ key in your environment config
   • Confirm your webhook URL is publicly reachable
   • Process a small real transaction to verify end-to-end