curl -X POST "https://demo.api.vultlocal.com/api/v1/wallet/transfer-p2p" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"sender_id": "sub_abc123",
"recipient_card_serial": "OLIV0002",
"amount": "500.00",
"pin": "1234",
"memo": "Payment for lunch"
}'
{
"success": true,
"message": "Transfer successful",
"transaction_id": "txn_abc123",
"amount": "500.00 SLE",
"fee_amount": "7.50 SLE",
"sender_new_balance": "49,492.50 SLE",
"recipient": {
"name": "Jane Smith",
"card_serial": "OLIV0002"
}
}
{
"success": false,
"error": "Insufficient balance",
"code": "INSUFFICIENT_FUNDS",
"available": 30000,
"required": 50750
}
{
"error": "Recipient card not found",
"code": "CARD_NOT_FOUND"
}
Wallet
P2P Transfer
Transfer funds between subscribers by card serial
POST
/
wallet
/
transfer-p2p
curl -X POST "https://demo.api.vultlocal.com/api/v1/wallet/transfer-p2p" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"sender_id": "sub_abc123",
"recipient_card_serial": "OLIV0002",
"amount": "500.00",
"pin": "1234",
"memo": "Payment for lunch"
}'
{
"success": true,
"message": "Transfer successful",
"transaction_id": "txn_abc123",
"amount": "500.00 SLE",
"fee_amount": "7.50 SLE",
"sender_new_balance": "49,492.50 SLE",
"recipient": {
"name": "Jane Smith",
"card_serial": "OLIV0002"
}
}
{
"success": false,
"error": "Insufficient balance",
"code": "INSUFFICIENT_FUNDS",
"available": 30000,
"required": 50750
}
{
"error": "Recipient card not found",
"code": "CARD_NOT_FOUND"
}
Person-to-person transfer using the recipient’s card serial number. Requires sender PIN verification.
Request
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)Body Parameters
string
required
Sender subscriber UUID
string
required
Recipient’s card serial (e.g.,
OLIV0002)string
required
Amount to transfer (e.g.,
500.00 or 500)string
required
Sender’s 4-digit PIN
string
Optional note/description
Response
boolean
Whether transfer succeeded
string
Unique transaction ID
string
Sender’s balance after transfer
string
Fee charged to sender
Examples
curl -X POST "https://demo.api.vultlocal.com/api/v1/wallet/transfer-p2p" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"sender_id": "sub_abc123",
"recipient_card_serial": "OLIV0002",
"amount": "500.00",
"pin": "1234",
"memo": "Payment for lunch"
}'
{
"success": true,
"message": "Transfer successful",
"transaction_id": "txn_abc123",
"amount": "500.00 SLE",
"fee_amount": "7.50 SLE",
"sender_new_balance": "49,492.50 SLE",
"recipient": {
"name": "Jane Smith",
"card_serial": "OLIV0002"
}
}
{
"success": false,
"error": "Insufficient balance",
"code": "INSUFFICIENT_FUNDS",
"available": 30000,
"required": 50750
}
{
"error": "Recipient card not found",
"code": "CARD_NOT_FOUND"
}
Transfer Flow
1
Validate Request
- Verify sender PIN
- Check sender balance >= amount + fee
- Validate recipient card exists and is active
2
Compliance Check
Run transaction against fraud detection rules
3
Execute Transfer
Atomic operation - debit sender, credit recipient
4
Notify
WhatsApp notifications to both parties
Fee Calculation
| Amount Range | Fee |
|---|---|
| 0 - 50,000 SLE | 1.5% |
| 50,001 - 500,000 SLE | 1.0% |
| 500,001+ SLE | 0.5% |
Fees are configured in Fee Settings and may vary.
Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_AMOUNT | Amount format invalid |
| 400 | INSUFFICIENT_FUNDS | Balance too low |
| 400 | INVALID_PIN | PIN verification failed |
| 400 | SELF_TRANSFER | Cannot transfer to self |
| 403 | SENDER_BLOCKED | Sender account blocked |
| 403 | RECIPIENT_BLOCKED | Recipient account blocked |
| 403 | COMPLIANCE_REJECTED | Transaction exceeds limits |
| 404 | SENDER_NOT_FOUND | Sender not found |
| 404 | CARD_NOT_FOUND | Recipient card not found |
| 500 | INTERNAL_ERROR | Server error |
Related
Get Balance
Check balance before transfer
Lookup Subscriber
Find subscriber by phone
Authorizations
ApiKeyAuthBearerAuth
API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'
Body
application/json
P2P transfer details
Accepts decimal format like "100.00" or "100"
Example:
"100.00"
Example:
"1234"
Supports any alphanumeric: CARD0001, 48290173K, etc.
Example:
"CARD0002"
Example:
"subscriber-uuid"
Example:
"Payment for lunch"
Response
Transfer successful
The response is of type object.
⌘I