Managing your wallet

Get your virtual account

Retrieve your dedicated virtual bank account details to fund your wallet.

curl --request GET \
  --url https://api.relay.chowdeck.com/relay/wallet/virtual-account \
  --header 'Authorization: Bearer YOUR_API_KEY'

A successful response returns your account details:

{
  "status": "success",
  "message": "Account found",
  "data": {
    "account_name": "YOUR BUSINESS NAME",
    "account_number": "0123456789",
    "bank_name": "Paystack-Titan",
    "bank_code": "629"
  }
}

Transfers to this account are reflected in your wallet balance automatically. Use this account for all wallet top-ups.

Check your balance

curl --request GET \
  --url https://api.relay.chowdeck.com/relay/wallet/balance \
  --header 'Authorization: Bearer YOUR_API_KEY'

A successful response returns your current balance:

{
  "status": "success",
  "message": "Balance fetched successfully",
  "data": {
    "balance": 150000
  }
}

balance is in the smallest currency unit. Divide by 100 for the display value (e.g. 150000 = ₦1,500).

We recommend checking your balance before creating a delivery or requesting a redelivery to avoid failed requests due to insufficient funds.

View transaction history

Retrieve a history of all wallet transactions, with optional date range filtering.

curl --request GET \
  --url 'https://api.relay.chowdeck.com/relay/wallet/history?start_date=2025-01-01&end_date=2025-12-31' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Supported query parameters:

Parameter	Type	Required	Description
`start_date`	string (ISO 8601)	No	Filter from this date
`end_date`	string (ISO 8601)	No	Filter up to this date

A successful response returns a list of transactions:

{
  "status": "success",
  "message": "History fetched successfully",
  "data": {
    "history": [
      {
        "id": 1001,
        "reference": "my-delivery-ref-001",
        "category": "relay_redelivery_fee",
        "reason": "Redelivery charge for relay delivery my-delivery-ref-001",
        "difference": -80000,
        "balance": 70000,
        "currency": "NGN",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

difference is the transaction amount -- negative for deductions, positive for top-ups. balance is your running wallet balance after the transaction.

Error responses

All failed requests return this shape:

{
  "status": "failed",
  "message": "..."
}