P2P Transfer
POST
/wallet/transfer-p2pOpen in the API playground →
Info
Person-to-person transfer using the recipient's card serial number. Requires sender PIN verification.
Request
Authorizationstringheaderrequired
Bearer olive_live_xxx or Bearer eyJ... (JWT)
Body Parameters
sender_idstringbodyrequired
Sender subscriber UUID
recipient_card_serialstringbodyrequired
Recipient's card serial (e.g., OLIV0002)
amountstringbodyrequired
Amount to transfer (e.g., 500.00 or 500)
pinstringbodyrequired
Sender's 4-digit PIN
memostringbody
Optional note/description
Response
successboolean
Whether transfer succeeded
transaction_idstring
Unique transaction ID
sender_new_balancestring
Sender's balance after transfer
fee_amountstring
Fee charged to sender
Examples
Request
cURL
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"
}'
Response
200 Success
{
"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"
}
}
400 Insufficient Balance
{
"success": false,
"error": "Insufficient balance",
"code": "INSUFFICIENT_FUNDS",
"available": 30000,
"required": 50750
}
404 Recipient Not Found
{
"error": "Recipient card not found",
"code": "CARD_NOT_FOUND"
}
Transfer Flow
Validate Request
- Verify sender PIN
- Check sender balance >= amount + fee
- Validate recipient card exists and is active
Compliance Check
Run transaction against fraud detection rules
Execute Transfer
Atomic operation - debit sender, credit recipient
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% |
Info
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 |