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/initiate-payment 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/initiate-payment \
  -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.

Collecting crypto↔fiat? Pass receipent instead of a rateKey

When fromCurrency and toCurrency are on opposite sides of the fiat/crypto line (e.g. NGN → CNGN, or CNGN → NGN) and Paycrest is the active provider for that pair, the collection settles through Paycrest instead of a standard virtual account. No rateKey is needed — Paycrest quotes the rate at order time — but receipent becomes required, with different fields depending on direction:

Fiat → crypto (onramp)
Crypto → fiat (offramp)

Your customer pays fiat in; you deliver crypto to their wallet. receipent.address and receipent.network are required — the wallet address and network to deliver to.

curl -X POST https://api.tradevu.co/v1/api/initiate-payment \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": "5000",
        "fromCurrency": "NGN",
        "toCurrency": "CNGN",
        "paymentReference": "onramp-4471",
        "receipent": {
          "address": "0xcaC89058E802db543fc09994893547A03191bb7f",
          "network": "base"
        }
      }'

Response

{
  "message": "Payment collection initiated successfully",
  "data": {
    "transactionId": "66f1c2...",
    "payRefrence": "8f21c93a1b",
    "amount": "5000",
    "toAmount": 5000,
    "fromCurrency": "NGN",
    "toCurrency": "CNGN",
    "paymentReference": "onramp-4471",
    "rate": 1.02,
    "paymentInstruction": [
      {
        "narration": "Kindly use 8f21c93a1b as transfer narration or memo",
        "accountNumber": "1961721434",
        "accountName": "5ran6/Tradevu Technology Limited",
        "bankName": "Nombank MFB",
        "amountToTransfer": "5100",
        "validUntil": "2026-09-17T09:34:36.291Z"
      }
    ]
  },
  "error": false
}

Show the customer paymentInstruction[0] — this is a one-off Paycrest-issued bank account. Ask them to pay amountToTransfer (already inclusive of fees, may differ from amount) before validUntil, or the collection expires and a new one must be created.

Your customer pays crypto in; you deliver fiat to their bank account. receipent.accountNumber, receipent.bankCode, and receipent.accountName are required, plus a top-level network on the request itself (not on receipent) for the network the customer will pay from.

curl -X POST https://api.tradevu.co/v1/api/initiate-payment \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": "5000",
        "fromCurrency": "CNGN",
        "toCurrency": "NGN",
        "paymentReference": "offramp-4471",
        "narration": "testing",
        "network": "base",
        "receipent": {
          "accountNumber": "8100000000",
          "bankCode": "OPAYNGPC",
          "accountName": "Shola Bayo"
        }
      }'

Response

{
  "message": "Payment collection initiated successfully",
  "data": {
    "transactionId": "66f1c2...",
    "payRefrence": "8f21c93a1b",
    "amount": "5000",
    "toAmount": 4999.9996,
    "fromCurrency": "CNGN",
    "toCurrency": "NGN",
    "paymentReference": "offramp-4471",
    "rate": 0.980392,
    "paymentInstruction": [
      {
        "narration": "Send crypto to 0x3761d8...861aE64 to complete this payment",
        "address": "0x3761d8488eEF97D194Fc649A1aA90CceC861aE64",
        "network": "base",
        "amountToTransfer": "5099.9592",
        "validUntil": "2026-09-17T10:08:35.948Z"
      }
    ]
  },
  "error": false
}

Show the customer paymentInstruction[0] — this time it’s a crypto deposit address, not a bank account. Ask them to send amountToTransfer on network before validUntil.

GET /api/transaction/:paymentReference currently always returns the fiat-style PaymentInstruction shape, even for an offramp collection — for the deposit address, rely on the response from step 2 (or your webhook payload) rather than re-fetching it from the transaction endpoint.

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