Partner API

Info

The Partner API enables external systems like VULT to interact with SmartPay wallets. All requests require HMAC-SHA256 signature authentication.

Warning

The interactive Mintlify playground is disabled for partner endpoints because these routes require custom HMAC headers and a signature over the exact raw JSON body. Use the copyable bash examples on each endpoint page.

Integration Partners

VULT

Mobile money integration for wallet funding

Banks

Bank transfer integrations

Custom

Custom partner integrations

---

Endpoints

Account Status

POST /api/v1/partner/account-status

Check if subscriber account exists

Transaction History

POST /api/v1/partner/transaction-history

Get partner's transaction history

Cash In

POST /api/v1/partner/cashin

Credit subscriber wallet

---

Authentication

Partner API uses HMAC-SHA256 signature authentication instead of Bearer tokens.

Header	Description
X-API-Key-ID	Partner API key ID
X-Partner-ID	Your partner identifier (for example VULT)
X-Timestamp	RFC3339 timestamp
X-Signature	HMAC-SHA256 signature

Warning

Signatures are only valid for 5 minutes from the timestamp. Ensure your server clock is synchronized.

---

Cash-In Flow

Lookup Subscriber

Partner calls account-status to verify subscriber exists

Initiate Cash-In

Partner sends cashin request with amount and reference

Account Credited

Subscriber wallet is immediately credited

Partner Debited

Partner clearing account is debited (can go negative)

Confirmation

Transaction ID returned for reconciliation

---

Response Examples

{
  "success": true,
  "exists": true,
  "status": "active"
}

---

Error Handling

Status	Code	Description
400	INVALID_REQUEST	Missing or invalid parameters
401	INVALID_SIGNATURE	HMAC signature verification failed
401	EXPIRED_TIMESTAMP	Timestamp older than 5 minutes
404	USER_NOT_FOUND	Subscriber not found
500	TRANSACTION_FAILED	Internal processing error

---

Integration Checklist

Development

• Obtain X-API-Key-ID, partner ID, and HMAC secret
• Implement signature generation
• Test with sandbox environment
• Handle all error responses

Production

• Request production credentials
• Set up webhook receivers
• Configure reconciliation process
• Enable monitoring/alerting