XXawaala Partner API

Lacag diris API oo ammaan ah.

Ku xiro nidaamkaaga Xawaala USSD Agent, xaqiiji magaca EVC, hel oggolaansho, kadib la soco natiijada.

REST API · v1

Bilow

API-ga waa server-to-server. Ku dir API key-ga header-ka X-API-Key. Furaha ha gelin browser, mobile app ama Git repository.

Soo dejiso Postman Collection ↓

Base URL: https://xawala.redsom.so/api/v1
X-API-Key: xw_live_YOUR_KEY
Content-Type: application/json
1. AbuurWareejin iyo lookup bilow.
2. HubiSug magaca EVC.
3. XaqiijiMagaca kadib oggolow.
4. NatiijoWebhook ama status hel.

Abuur wareejin

POST/api/v1/transfers

Idempotency-Key waa qasab; isla key-ga mar labaad wuxuu soo celinayaa wareejintii hore.

curl -X POST https://xawala.redsom.so/api/v1/transfers \
  -H "X-API-Key: xw_live_YOUR_KEY" \
  -H "Idempotency-Key: unique-reference-001" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReference": "REM-2026-0001",
    "sender": {
      "name": "Ahmed Ali",
      "phone": "25261xxxxxxx",
      "country": "United Kingdom",
      "city": "London"
    },
    "receiver": { "phone": "615xxxxxx" },
    "amount": 25.50,
    "currency": "USD",
    "riskOverride": false
  }'
{
  "data": {
    "id": "XWL-...",
    "externalReference": "REM-2026-0001",
    "status": "verifying_recipient",
    "receiver": { "phone": "615xxxxxx", "verifiedName": null },
    "amount": 25.5,
    "currency": "USD"
  }
}

La soco xaaladda

GET/api/v1/transfers/{id}
curl https://xawala.redsom.so/api/v1/transfers/XWL-... \
  -H "X-API-Key: xw_live_YOUR_KEY"

Xaaladaha: verifying_recipient, awaiting_confirmation, processing, completed, failed, cancelled.

Xaqiiji magaca oo dir

POST/api/v1/transfers/{id}/confirm

Wac marka status-ku yahay awaiting_confirmation oo aad hubisay receiver.verifiedName. Xaqiijintu waxay dhacaysaa qiyaastii 60 ilbiriqsi.

curl -X POST https://xawala.redsom.so/api/v1/transfers/XWL-.../confirm \
  -H "X-API-Key: xw_live_YOUR_KEY"

Jooji kahor PIN-ka

POST/api/v1/transfers/{id}/cancel

Haddii magaca khaldan yahay, jooji. PIN lama gelinayo, lacaguna ma baxayso.

Webhooks

Dhacdooyinka: transfer.created, recipient.verified, transfer.completed, transfer.failed, transfer.cancelled.

X-Xawaala-Event: transfer.completed
X-Xawaala-Signature: sha256=HEX_DIGEST

Hubi saxeexa adigoo isticmaalaya HMAC-SHA256 ee raw request body iyo webhook secret-ka.

// Node.js
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.XAWAALA_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
Webhook-ga ku jawaab HTTP 2xx. Mar walba GET status isticmaal haddii webhook kaa maqnaado.

Khaladaadka

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Faahfaahinta qaladka"
  }
}

401 API key khaldan · 409 state/reference conflict · 429 rate limit · 503 Agent offline.