Cash In

POST/partner/cashinOpen in the API playground →

Credit a subscriber's wallet. Partner routes use HMAC headers, so this page provides a copyable request instead of the interactive playground.

Authentication

X-API-Key-IDstringheaderrequired

API key ID issued for the partner integration

X-Partner-IDstringheaderrequired

Partner identifier such as VULT

X-Timestampstringheaderrequired

RFC3339 timestamp used when generating the signature

X-Signaturestringheaderrequired

Hex-encoded HMAC-SHA256 of METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY

Request Body

phone_numberstringbody

Subscriber phone number

card_serialstringbody

Subscriber card serial

amountintegerbodyrequired

Amount in cents (for example 50000 = 500.00)

referencestringbodyrequired

Partner's unique transaction reference

Provide either phone_number or card_serial

Example

Request

cURL

BODY='{"phone_number":"0771234567","amount":50000,"reference":"PARTNER-TXN-123"}'
TIMESTAMP='2026-03-10T12:00:00Z'
SIGNATURE=$(printf 'POST\n/api/v1/partner/cashin\n%s\n%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SMARTPAY_HMAC_SECRET" -hex | sed 's/^.* //')

curl -X POST "https://demo.api.vultlocal.com/api/v1/partner/cashin" \
  -H "X-API-Key-ID: $SMARTPAY_API_KEY_ID" \
  -H "X-Partner-ID: $SMARTPAY_PARTNER_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Response

{
  "success": true,
  "transaction_id": "txn_abc123",
  "message": "Cash-in successful",
  "data": {
    "subscriber_id": "sub_xyz789",
    "name": "John Doe",
    "amount": 50000,
    "new_balance": 75000,
    "currency": "SLE",
    "reference": "TXN-123456"
  }
}

Transaction Flow

1. Partner account is debited (may go negative - clearing account)
2. Subscriber account is credited
3. Transaction and ledger entries are created
4. Generates unique transaction ID

Errors

Status	Description
400	Invalid request body
401	Missing or invalid HMAC headers/signature
404	Subscriber not found
500	Transaction failed