Trigger Top-Up
Initiates an e-wallet fund transfer to a beneficiary. This endpoint performs comprehensive validation, deducts funds from merchant balance atomically, creates a transaction record, and queues processing through the job system. The response indicates transaction has been queued with status typically Pending until background processing completes. CRITICAL: This is a money-out operation requiring X-Signature and X-Timestamp authentication per internal signing protocol. Middleware validation includes kill-switch check, request signature verification, rate limiting, and anomaly detection. Duplicate reference numbers within 24 hours are rejected with error code SP004.
Authorizations
Headers
HMAC-SHA512 hex signature, computed as HMAC_SHA512(clientSecret, "{HTTP_METHOD}:{REQUEST_URI}:{ACCESS_TOKEN}:{SHA256_HEX(MINIFIED_BODY)}:{X_TIMESTAMP}"). MINIFIED_BODY is the request body with object keys recursively sorted alphabetically and re-serialised with no whitespace (an empty/missing body hashes the empty string). ACCESS_TOKEN is the bearer token without the Bearer prefix. Missing header returns 400 (response_code=4019900); signature mismatch returns 401 (response_code=4019900).
Body
Request payload to initiate an e-wallet transfer. Includes validation, balance deduction, and asynchronous processing through the job queue.
Response
Queued — data matches EwalletTriggerTopUpSuccessData (usually 03 Pending)
Success response data after balance lock and transaction creation (HTTP 200). Transaction status is typically Pending until processed by job or confirmed via webhook. Funds have been deducted from merchant account.
