Wallet Transfer

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

string

required

Bearer token. Requires MANAGE_TRANSFER permission.

string

required

UUID of the source customer whose wallet will be debited.

string

required

UUID of the destination customer whose wallet will be credited. Must be different from fromCustomerId.

number

required

Transfer amount in kobo.

Response

boolean

true on success.

string

"Transaction successfully completed." or "Transaction successfully submitted for approval." for web-dashboard requests.

object

Present on API-initiated transfers.

Show data properties

number

Transfer amount in kobo.

string

Auto-generated transaction reference.

number

Total amount deducted from the source wallet (amount + fees).

number

Transfer fee charged in kobo.

object

Detailed fee breakdown.

Show fee_breakdown properties

number

Base platform fee in kobo.

number

Additional merchant markup fee in kobo.

number

Combined total fee in kobo.

string

UUID of the source customer.

string

UUID of the destination customer.

string

UUID of the source wallet.

string

UUID of the destination wallet.

string

Human-readable description.

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

const response = await fetch("https://api.tagpay.ng/v1/transfer/wallet", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fromCustomerId: "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    toCustomerId: "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
    amount: 1500000,
  }),
});

const data = await response.json();

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

string

required

Bearer token. Requires MANAGE_TRANSFER permission.

string

required

10-digit virtual account number of the source wallet.

string

required

10-digit virtual account number of the destination wallet. Must be different from fromWalletId.

number

required

Transfer amount in kobo.

Response

boolean

true on success.

string

"Transaction successfully completed."

object

Show data properties

number

Transfer amount in kobo.

string

Auto-generated transaction reference.

number

Total amount deducted from source wallet (amount + fees).

number

Transfer fee in kobo.

string

UUID of the source customer.

string

UUID of the destination customer.

string

UUID of the source wallet.

string

UUID of the destination wallet.

string

Human-readable description.

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

const response = await fetch("https://api.tagpay.ng/v1/transfer/wallet-to-wallet", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fromWalletId: "0123456789",
    toWalletId: "0987654321",
    amount: 750000,
  }),
});

const data = await response.json();

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 Status	Description
`400`	Source and destination customer/wallet IDs are the same
`400`	One or both customer wallets not found
`400`	Source or destination wallet is inactive
`400`	Insufficient balance on source wallet
`400`	Post-no-credit is enabled on destination wallet
`400`	Destination wallet maximum balance would be exceeded
`400`	Customer daily tier limit exceeded
`400`	Customer minimum balance condition not met
`401`	Missing or invalid authentication token
`403`	Internal 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."
}

Wallets

Transfers

Transactions

Webhooks

Transfer from merchant wallet to customer wallet

Request

Response

Examples

Transfer between wallets by account number

Request

Response

Examples

Error responses

​Transfer from merchant wallet to customer wallet

​Request

​Response

​Examples

​Transfer between wallets by account number

​Request

​Response

​Examples

​Error responses

Transfer from merchant wallet to customer wallet

Request

Response

Examples

Transfer between wallets by account number

Request

Response

Examples

Error responses