POST
/
v1
/
payments
/
virtual-account
curl --request POST \
  --url https://api.withconvexity.com/v1/payments/virtual-account \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purpose": "WALLET_TOPUP",
  "amount": 1500,
  "description": "Wallet balance top-up"
}
'
{
  "status": true,
  "message": "Virtual account created successfully",
  "data": [
    {
      "accountNumber": "7382910546",
      "accountName": "Acme Logistics Ltd / KoraPay",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "reference": "9a1c4e7b-2d56-4f83-b0e9-7c1a2b3d4e5f",
      "amountExpected": 25000,
      "expiryAt": "2026-06-17T13:30:00.000Z"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

OAuth 2.0 access token from Auth-Edge.

Body

application/json
​
purpose
enum<string>
required

Settlement target for the funded account.

Available options:
WALLET_TOPUP,
SUBSCRIPTION
​
amount
number

Wallet top-up: positive amount in fiat major units. The account is bound to this exact amount.

​
planId
integer

Subscription: positive plan id to subscribe to.

​
billingCycle
enum<string>

Subscription: defaults to MONTHLY.

Available options:
MONTHLY,
YEARLY
​
subscriptionId
string

Subscription: existing subscription to renew/charge.

​
description
string

Free-text note (max 500 chars).

Response

OK

The response is of type object.