P2P Transfer - OLIVE Payment Platform

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"
}

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

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%

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

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"

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.

Transaction History

Internal Transfer

​Request

​Body Parameters

​Response

​Examples

​Transfer Flow

​Fee Calculation

​Errors

​Related

Get Balance

Lookup Subscriber

Authorizations

Body

Response

Request

Body Parameters

Response

Examples

Transfer Flow

Fee Calculation

Errors

Related