Balance Transfer

​

Overview

​

How Balance Transfer Works

• Your Master Balance - debited by the transfer amount (e.g. -₹500.00).
• Customer Wallet - credited by the same amount (e.g. +₹500.00).

​

Transfer Balance

​

Request Body

curl -X POST \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transfer-balance" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "currency": "INR",
    "description": "April recharge - Credresolve"
  }'

import requests

BASE = "https://api.vobiz.ai/api/v1/partner"
HEADERS = {
    "X-Auth-ID": "{your_partner_id}",
    "X-Auth-Token": "{your_auth_token}",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

# Check your own balance first - `balance` is a STRING, cast before comparing
profile = requests.get(f"{BASE}/me", headers=HEADERS).json()
if float(profile["balance"]) >= 500.00:
    response = requests.post(
        f"{BASE}/accounts/MA_48149cf4/transfer-balance",
        headers=HEADERS,
        json={
            "amount": 500.00,
            "currency": "INR",
            "description": "April recharge - Credresolve",
        },
    )
    print(response.json())

​

Response (200)

{
  "transaction_id": "txn_aabbccdd1234",
  "from_account": "PA_XXXXXXXX",
  "to_account": "MA_XXXXXXXX",
  "amount": 500.00,
  "currency": "INR",
  "description": "April recharge - Credresolve",
  "status": "completed",
  "partner_balance_after": 47750.00,
  "customer_balance_after": 2950.00,
  "timestamp": "2026-03-25T11:00:00Z"
}

​

Errors

{
  "error": "insufficient_balance",
  "message": "Your partner balance (₹200.00) is insufficient for this transfer (₹500.00).",
  "current_balance": 200.00,
  "requested_amount": 500.00,
  "currency": "INR"
}

​

Notes

• Transfers are permanent and cannot be reversed - Once a transfer completes, there is no API endpoint to reverse it. If you transfer the wrong amount or to the wrong customer, contact Vobiz support. Always verify the customer_auth_id and amount before calling this endpoint.
• Transfers are atomic - your balance is checked at submission time - The API checks your master balance at the moment the request is received. Both legs (your debit, the customer’s credit) commit together or not at all. If concurrent transfers cause your balance to drop below the required amount between your own check and the actual transfer, the request fails with a 400 and neither ledger is touched.
• Currency must match your partner account - The currency you send must equal your partner account currency (GET /me → currency). A mismatched currency is rejected; the API does not convert between currencies.
• No built-in idempotency key - Retrying a transfer after a network timeout can double-credit the customer, because each call is a fresh transfer. Before retrying a request whose response you never saw, poll the customer’s transactions (match on amount + recent created_at) to confirm whether the first attempt landed.
• Description appears in both ledgers - The description field is recorded in your partner transaction ledger as a debit and in the customer’s transaction ledger as a credit (prefixed Transfer from partner …). Use clear notes for easier reconciliation during billing cycles.

​

Before Transferring - Checklist

• Verify the target customer_auth_id is correct.
• Confirm the transfer amount and currency.
• Confirm your master balance is sufficient.
• Add a clear description for ledger reconciliation.
• Remember that transfers are permanent and cannot be reversed via API.