Payment Collections

A collection (or “deposit”) is money coming into your Tradevu wallet. You create a collection, show the returned account instructions to your customer, and then either poll for status or wait for a webhook once they’ve paid.

The flow

(Optional) Get a quote

If fromCurrency and toCurrency differ, fetch a quote first to show your customer the converted amount and lock in a rate. See Quotes & FX.

Initiate the collection

Call POST /api/deposit with an amount, currency pair, and a paymentReference you generate and control — it must be unique per attempt.

curl -X POST https://api.tradevu.co/v1/api/deposit \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": "500",
        "fromCurrency": "NGN",
        "toCurrency": "NGN",
        "paymentReference": "invoice-4471",
        "narration": "Invoice #4471"
      }'

Response

{
  "message": "Payment collection initiated successfully",
  "data": {
    "transactionId": "66f1c2...",
    "payRefrence": "8f21c93a1b",
    "amount": "500",
    "toAmount": 500,
    "fromCurrency": "NGN",
    "toCurrency": "NGN",
    "paymentReference": "invoice-4471",
    "rate": 0,
    "fee": 0,
    "totalAmount": 500,
    "paymentInstruction": [
      {
        "narration": "Kindly use 8f21c93a1b as transfer narration or memo",
        "accountNumber": "0123456789",
        "accountName": "Tradevu/Acme Inc",
        "bankName": "Providus Bank"
      }
    ]
  },
  "error": false
}

Display the payment instructions

Show the paymentInstruction array to your customer — typically a virtual account number, account name, and bank name. Ask them to include the payRefrence (not your paymentReference) as the transfer narration/memo so the inbound payment matches automatically.

paymentReference is your idempotency key; payRefrence (note the spelling) is the memo Tradevu generates for matching the bank transfer. Don’t confuse the two in your UI.

Convert your currencies? Pass a rateKey

If fromCurrency and toCurrency differ, this is a currency conversion — pass the rateKey from a prior quote so the conversion uses the rate you showed the customer, and a conversion fee is applied. Without a rateKey, toAmount defaults to the same numeric amount as amount.

Track status

Poll GET /api/transaction/:paymentReference using the reference you supplied in step 2, or register a webhook to be notified the moment it settles instead.

curl https://api.tradevu.co/v1/api/transaction/invoice-4471 \
  -H "x-api-key: <your-api-key>"

Response

{
  "message": "Transaction fetched Successfully",
  "data": {
    "transactionId": "66f1c2...",
    "payRefrence": "8f21c93a1b",
    "paymentReference": "invoice-4471",
    "amount": 500,
    "toAmount": 500,
    "totalAmount": 500,
    "rate": 0,
    "status": "Pending",
    "fee": 0,
    "rateKey": null,
    "fromCurrency": "NGN",
    "toCurrency": "NGN",
    "address": null,
    "network": null,
    "paymentInstruction": [
      {
        "narration": "Kindly use 8f21c93a1b as transfer narration or memo",
        "accountNumber": "0123456789",
        "accountName": "Tradevu/Acme Inc",
        "bankName": "Providus Bank"
      }
    ]
  },
  "error": false
}

Statuses

status reflects the underlying transaction/payment status. Treat any value other than a completed/settled state as “still pending” — don’t hard-code an exhaustive list, since it can include provider-specific intermediate states. At minimum, expect to see a Pending state immediately after creation.

Finding your virtual account details directly

If you just need the standing account details for a currency — independent of any specific collection — use GET /api/account/:currency instead of creating a deposit:

curl https://api.tradevu.co/v1/api/account/NGN \
  -H "x-api-key: <your-api-key>"

This is useful for displaying a permanent “fund your wallet” account to customers, rather than a one-off collection.

Checking your balance

curl https://api.tradevu.co/v1/api/balance/NGN \
  -H "x-api-key: <your-api-key>"

Response

{
  "message": "Account balance fetched Successfully",
  "data": { "balance": 128450.32 },
  "error": false
}

Full endpoint reference

See exact request/response schemas for every field above.

Get Started

Guides

Payment Collections

The flow

Statuses

Finding your virtual account details directly

Checking your balance

Full endpoint reference

​The flow

​Statuses

​Finding your virtual account details directly

​Checking your balance

Full endpoint reference

The flow

Statuses

Finding your virtual account details directly

Checking your balance