Skip to main content
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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt

Use this file to discover all available pages before exploring further.

Person-to-person transfer using the recipient’s card serial number. Requires sender PIN verification.

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)

​
Body Parameters

​
sender_id
string
required
Sender subscriber UUID
​
recipient_card_serial
string
required
Recipient’s card serial (e.g., OLIV0002)
​
amount
string
required
Amount to transfer (e.g., 500.00 or 500)
​
pin
string
required
Sender’s 4-digit PIN
​
memo
string
Optional note/description

​
Response

​
success
boolean
Whether transfer succeeded
​
transaction_id
string
Unique transaction ID
​
sender_new_balance
string
Sender’s balance after transfer
​
fee_amount
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"
  }
}

​
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 RangeFee
0 - 50,000 SLE1.5%
50,001 - 500,000 SLE1.0%
500,001+ SLE0.5%
Fees are configured in Fee Settings and may vary.

​
Errors

StatusCodeDescription
400INVALID_AMOUNTAmount format invalid
400INSUFFICIENT_FUNDSBalance too low
400INVALID_PINPIN verification failed
400SELF_TRANSFERCannot transfer to self
403SENDER_BLOCKEDSender account blocked
403RECIPIENT_BLOCKEDRecipient account blocked
403COMPLIANCE_REJECTEDTransaction exceeds limits
404SENDER_NOT_FOUNDSender not found
404CARD_NOT_FOUNDRecipient card not found
500INTERNAL_ERRORServer error

Get Balance

Check balance before transfer

Lookup Subscriber

Find subscriber by phone

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Body

application/json

P2P transfer details

​
amount
string
required

Accepts decimal format like "100.00" or "100"

Example:

"100.00"

​
pin
string
required
Example:

"1234"

​
recipient_card_serial
string
required

Supports any alphanumeric: CARD0001, 48290173K, etc.

Example:

"CARD0002"

​
sender_id
string
required
Example:

"subscriber-uuid"

​
memo
string
Example:

"Payment for lunch"

Response

Transfer successful

The response is of type object.