Create deposit account

curl --request POST \
  --url https://api.convexity.tools/v1/payments/subscribe \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purpose": "SUBSCRIPTION",
  "planId": 3,
  "billingCycle": "MONTHLY",
  "description": "Subscribe to Pro plan"
}
'

import requests

url = "https://api.convexity.tools/v1/payments/subscribe"

payload = {
    "purpose": "SUBSCRIPTION",
    "planId": 3,
    "billingCycle": "MONTHLY",
    "description": "Subscribe to Pro plan"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    purpose: 'SUBSCRIPTION',
    planId: 3,
    billingCycle: 'MONTHLY',
    description: 'Subscribe to Pro plan'
  })
};

fetch('https://api.convexity.tools/v1/payments/subscribe', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": true,
  "message": "Virtual account created successfully",
  "data": [
    {
      "kind": "FIAT",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Konga",
      "bankName": "Providus Bank",
      "bankCode": "001",
      "reference": "ref-1",
      "amountExpected": 7500,
      "fxRate": 0.000665,
      "expiryAt": "2026-07-03T12:00:00.000Z"
    }
  ]
}

Payments

Create deposit account

Mints a one-time deposit account to fund a wallet top-up or a subscription, depending on purpose. The request body is a discriminated union on purpose. By default an account is minted for every active settlement rail (you may get one FIAT bank account and one STABLECOIN deposit wallet back); pass providerType to pin a single rail. A free ($0) plan is activated immediately and returns an empty data array (no account needed).

data is always an array of account objects, each a discriminated union on kind: a FIAT account carries bank keys only, a STABLECOIN account carries on-chain keys only. Branch on kind; do not assume a field exists across both rails.

FX rate lock: every amount in the response is priced at a single NGN/USD rate, returned as fxRate (USD per 1 NGN). The rate is locked until expiryAt: the deposit settles at the quoted rate even if the market moves inside the deposit window.

Stablecoin peg: a stablecoin quote is denominated in the token’s peg currency (pegCurrency). USD-pegged tokens (USDC) quote the USD equivalent; cNGN is 1:1 with the naira, so its amountExpected is the naira amount and amountExpectedNgn carries the naira value to display to the payer.

Upgrades are prorated: if the project already holds an active paid subscription to a different plan of the same product, the unused value of that subscription (current plan price × fraction of the period remaining) is credited against the new plan’s price and only the difference is charged. All response amounts already reflect the credit. On settlement the old subscription is cancelled and its product access is replaced by the new plan’s. Moving from a free plan works the same way with no credit (full price, free subscription and grant replaced). If the credit would cover the entire new price (a downgrade), the request is rejected. Renewals need no special field: send the same planId again and the existing subscription is renewed.

POST

payments

Create deposit account

curl --request POST \
  --url https://api.convexity.tools/v1/payments/subscribe \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purpose": "SUBSCRIPTION",
  "planId": 3,
  "billingCycle": "MONTHLY",
  "description": "Subscribe to Pro plan"
}
'

import requests

url = "https://api.convexity.tools/v1/payments/subscribe"

payload = {
    "purpose": "SUBSCRIPTION",
    "planId": 3,
    "billingCycle": "MONTHLY",
    "description": "Subscribe to Pro plan"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    purpose: 'SUBSCRIPTION',
    planId: 3,
    billingCycle: 'MONTHLY',
    description: 'Subscribe to Pro plan'
  })
};

fetch('https://api.convexity.tools/v1/payments/subscribe', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": true,
  "message": "Virtual account created successfully",
  "data": [
    {
      "kind": "FIAT",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Konga",
      "bankName": "Providus Bank",
      "bankCode": "001",
      "reference": "ref-1",
      "amountExpected": 7500,
      "fxRate": 0.000665,
      "expiryAt": "2026-07-03T12:00:00.000Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

OAuth 2.0 access token from Auth-Edge.

Query Parameters

providerType

enum<string>

Restrict settlement to one rail. Omit to mint an account for every active provider.

Available options:

FIAT,

STABLECOIN

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 USD major units (e.g. 15 = $15). The account is bound to this exact amount.

planId

integer

Subscription: positive plan id to subscribe to. Renewals and upgrades are resolved server-side from this; no subscription id is sent.

billingCycle

enum<string>

Subscription: required. Sizes the paid period.

Available options:

MONTHLY,

YEARLY

description

string

Free-text note (max 500 chars).

Response

OK: one account per active provider (empty for a free plan).

status

boolean

message

string

data

(FiatAccount · object | StablecoinAccount · object)[]

One account per active provider. Empty ([]) for a free ($0) plan.

Bank-transfer deposit account. Carries bank keys only.

FiatAccount
StablecoinAccount

Show child attributes

Get subscription payments Overview

Auth-Edge

Projects

Payments

Products

Subscriptions

Wallet

Tokenization

Blockchain Events

Create deposit account

Authorizations

Query Parameters

Body

Response