Internal Transfer

POST/wallet/transferOpen in the API playground →

Info

Internal transfers move funds between subscriber accounts using account IDs. For transfers by card serial, use P2P Transfer.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Body Parameters

from_account_idstringbodyrequired

Source account UUID

to_account_idstringbodyrequired

Destination account UUID

amountstringbodyrequired

Amount to transfer

pinstringbodyrequired

Source account PIN

descriptionstringbody

Transfer description

---

Response

successboolean

Whether transfer succeeded

transaction_idstring

Unique transaction ID

messagestring

Result message

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/wallet/transfer" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account_id": "acc_abc123",
    "to_account_id": "acc_xyz789",
    "amount": "1000.00",
    "pin": "1234",
    "description": "Settlement payment"
  }'

Response

200 Success

{
  "success": true,
  "message": "Transfer completed successfully",
  "transaction_id": "txn_abc123",
  "amount": "1,000.00 SLE",
  "from_balance": "49,000.00 SLE",
  "to_balance": "11,000.00 SLE"
}

400 Insufficient Balance

{
  "success": false,
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_FUNDS"
}

---

Use Cases

Scenario	Description
Agent Settlement	Transfer from agent to SmartPay
Corporate Payroll	Bulk employee payments
Refunds	Return funds to subscriber
Account Adjustment	Administrative corrections

---

Errors

Status	Code	Description
400	INVALID_AMOUNT	Amount format invalid
400	INSUFFICIENT_FUNDS	Balance too low
400	INVALID_PIN	PIN verification failed
401	UNAUTHORIZED	Invalid API key
404	ACCOUNT_NOT_FOUND	Account not found
500	INTERNAL_ERROR	Server error