Skip to main content

​
Transfer from merchant wallet to customer wallet

POST /transfer/wallet Transfers funds between two customer wallets belonging to your merchant account, identified by their customer IDs. The source customer’s wallet is debited the transfer amount plus applicable fees, and the destination customer receives the transfer amount net of fees.
Both customers must have active (ACTIVE) wallets. The source customer’s tier daily limit, minimum balance, and single-transaction limits are enforced. The destination wallet’s tier maximum balance is also validated.

​
Request

​
Authorization
string
required
Bearer token. Requires MANAGE_TRANSFER permission.
​
fromCustomerId
string
required
UUID of the source customer whose wallet will be debited.
​
toCustomerId
string
required
UUID of the destination customer whose wallet will be credited. Must be different from fromCustomerId.
​
amount
number
required
Transfer amount in kobo.

​
Response

​
status
boolean
true on success.
​
message
string
"Transaction successfully completed." or "Transaction successfully submitted for approval." for web-dashboard requests.
​
data
object
Present on API-initiated transfers.

​
Examples

curl -X POST https://api.tagpay.ng/v1/transfer/wallet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromCustomerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "toCustomerId": "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
    "amount": 1500000
  }'
Response
{
  "status": true,
  "message": "Transaction successfully completed.",
  "data": {
    "amount": 1500000,
    "reference": "TXN-20240501-W2W-ABC123",
    "total": 1510000,
    "transaction_fee": 10000,
    "fee_breakdown": {
      "base_fee": 10000,
      "merchant_fee": 0,
      "total_fee": 10000
    },
    "source_customer_id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "target_customer_id": "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
    "source_customer_wallet": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target_customer_wallet": "wlt_b2c3d4e5-f6a7-8901-bcde-fa2345678901",
    "description": "Fund transfer between customers"
  }
}

​
Transfer between wallets by account number

POST /transfer/wallet-to-wallet Transfers funds between two customer wallets identified by their 10-digit virtual account numbers instead of customer IDs. Use this when you have account numbers stored directly. The source wallet must be ACTIVE. Post-no-credit and maximum balance rules are applied to the destination wallet.

​
Request

​
Authorization
string
required
Bearer token. Requires MANAGE_TRANSFER permission.
​
fromWalletId
string
required
10-digit virtual account number of the source wallet.
​
toWalletId
string
required
10-digit virtual account number of the destination wallet. Must be different from fromWalletId.
​
amount
number
required
Transfer amount in kobo.

​
Response

​
status
boolean
true on success.
​
message
string
"Transaction successfully completed."
​
data
object

​
Examples

curl -X POST https://api.tagpay.ng/v1/transfer/wallet-to-wallet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fromWalletId": "0123456789",
    "toWalletId": "0987654321",
    "amount": 750000
  }'
Response
{
  "status": true,
  "message": "Transaction successfully completed.",
  "data": {
    "amount": 750000,
    "reference": "TXN-20240501-WTW-DEF456",
    "total": 760000,
    "transaction_fee": 10000,
    "source_customer_id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "target_customer_id": "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
    "source_customer_wallet": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "target_customer_wallet": "wlt_b2c3d4e5-f6a7-8901-bcde-fa2345678901",
    "description": "Fund transfer between customers"
  }
}

​
Error responses

HTTP StatusDescription
400Source and destination customer/wallet IDs are the same
400One or both customer wallets not found
400Source or destination wallet is inactive
400Insufficient balance on source wallet
400Post-no-credit is enabled on destination wallet
400Destination wallet maximum balance would be exceeded
400Customer daily tier limit exceeded
400Customer minimum balance condition not met
401Missing or invalid authentication token
403Internal transfers not enabled on this account
400 Insufficient Balance
{
  "status": false,
  "message": "Insufficient balance on source wallet to complete this transfer."
}
400 Daily Tier Limit
{
  "status": false,
  "message": "Customer daily tier limit exceeded"
}
400 Post-No-Credit
{
  "status": false,
  "message": "Post no credit has been enabled on the beneficiary account. Kindly reachout to support for help."
}