Payment records and virtual bank accounts for wallet top-ups and subscription billing.
The Payments API lets you list the payments collected for your project and mint
one-time deposit accounts that settle into a wallet top-up or a subscription. Depending
on the settlement rail, a deposit account is either a fiat bank account (bank
transfer in NGN) or a stablecoin deposit wallet (USDC or cNGN, on-chain).
How funding works
Mint a deposit account with Create deposit account,
stating the purpose: a subscription (planId + billingCycle) or a wallet
top-up (USD amount).
The payer sends the exact amountExpected to the account before expiryAt:
a bank transfer for FIAT, an on-chain token transfer for STABLECOIN.
Settlement is automatic: the deposit is verified, an idempotent payment
record is written, and the purpose is applied: the subscription activates (with
product access granted) or the wallet balance is credited.
The step-by-step version, including per-rail payer instructions, lives in the
Fund and subscribe guide.
The payment object
Attribute
Type
Description
id
string
Unique payment id.
purpose
string
WALLET_TOPUP or SUBSCRIPTION.
status
string
PENDING, SUCCESS, FAILED, or REFUNDED.
amount
number
Amount in major units, denominated in currency (e.g. 1500 + NGN = ₦1,500).
currency
string
ISO currency code the payment was collected in (NGN for bank transfers and cNGN, USD for USD-pegged stablecoins).
paymentRef
string
Provider payment reference.
subscriptionId
string | null
Linked subscription, for SUBSCRIPTION payments.
projectId
string
Project the payment belongs to.
planId
integer | null
Plan billed, for subscription payments.
billingCycle
string | null
MONTHLY or YEARLY, for subscription payments.
businessId
string
Owning business.
providerId
string
Upstream provider id.
reference
string
Idempotent reference for the payment.
amountUsd
string
USD value as a decimal string.
description
string
Free-text note.
createdBy
string
Actor that created the record.
createdAt
string
ISO 8601 UTC timestamp.
updatedAt
string
ISO 8601 UTC timestamp.
The deposit account object
Returned by Create deposit account in the
data array, one entry per active provider. Each account is bound to a single expected
amount and expires.The object is a discriminated union on kind: the keys present depend on the rail, and
you only ever receive the keys for that rail. Always branch on kind; do not assume a field
exists across both.
A FIAT account carries no on-chain keys (walletAddress, token, chainId, …) and a
STABLECOIN account carries no bank keys (accountNumber, bankName, …). The
irrelevant keys are absent, not null.
FIAT: bank transfer
Attribute
Type
Description
kind
string
Always FIAT.
accountNumber
string
Virtual bank account number to pay into.
accountName
string
Account holder name.
bankName
string
Bank the account is held with.
bankCode
string
Bank code.
reference
string
Reference that ties the funding to this account.
amountExpected
number
Exact amount to pay, in NGN.
fxRate
number
NGN/USD rate (USD per 1 NGN) the quote was priced at, locked until expiryAt.
expiryAt
string
ISO 8601 UTC expiry. Pay before this time (~1h).
STABLECOIN: on-chain deposit
Attribute
Type
Description
kind
string
Always STABLECOIN.
walletAddress
string
Temporary on-chain deposit address to send tokens to.
token
string
Token symbol (e.g. USDC, cNGN).
pegCurrency
string
Fiat peg of the token: USD (USDC) or NGN (cNGN, 1:1 naira).
contractAddress
string
Token contract address.
network
string
Chain family (e.g. EVM).
blockchainNetwork
string
Human-readable network name (e.g. Base).
chainId
integer
EVM chain id (e.g. 8453).
reference
string
Reference that ties the funding to this wallet.
amountExpected
number
Exact amount to send, in token major units, denominated in the token’s peg currency (e.g. 15 = 15 USDC).
amountExpectedNgn
number
Naira value to display to the payer. Present only for naira-pegged tokens (cNGN), where it equals amountExpected.
fxRate
number
NGN/USD rate (USD per 1 NGN) the quote was priced at, locked until expiryAt.
expiryAt
string
ISO 8601 UTC expiry. Send before this time (~30m).
For a cNGN deposit, show the payer the naira value, e.g.
Send ₦22,556.39 (22,556.39 cNGN). For USD-pegged tokens, show the token
amount, e.g. Send 15 USDC.
FX rate lock
Every amount in a deposit-account response is priced at a single NGN/USD rate,
returned as fxRate (USD per 1 NGN). The rate is locked for the life of the
account: when the deposit lands, settlement converts at the quoted rate, not
the live market rate, so what the payer owes and what gets credited can’t
drift inside the deposit window. After expiryAt the lock (and the account)
expires; request a new account to get a fresh rate.
Subscription upgrades are prorated
If the project already holds an active paid subscription to a different plan
of the same product, a subscription request is treated as an upgrade:
The unused value of the current subscription (current plan price × fraction of the billing period remaining) is credited against the new plan’s price.
Only the difference is charged. All amounts in the response already reflect
the credit, priced at the locked fxRate.
When the payment settles, the new subscription starts a full fresh period,
the old subscription is cancelled, and its product access is replaced by the
new plan’s.
Moving from a free plan to a paid plan of the same product works the same
way, just with no credit: full price is charged, and the free subscription
and its access grant are replaced on settlement.
If the credit would cover the entire new price (a downgrade or near-equal
switch), the request is rejected: no-charge plan switches are not supported.
No special request field is needed: upgrades are detected server-side, and a
renewal is just a new request with the same planId.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Convexity Infra API","description":"REST API reference for Convexity Infra: the backend that powers your on-chain products. Its core services are wallets, tokenization, and blockchain events, supported by authentication, payments, products, and subscriptions.","colors":{"primary":"#2755BB","light":"#5B83E8","dark":"#1F4496"},"logo":{"light":"https://mintcdn.com/infra-docs-api/9VolpVBxlj0nTDjr/assets/convexity_main_logo.png?fit=max\u0026auto=format\u0026n=9VolpVBxlj0nTDjr\u0026q=85\u0026s=dec660a801dfa5f9023e943a1865adee","dark":"https://mintcdn.com/infra-docs-api/9VolpVBxlj0nTDjr/assets/convexity_main_logo.png?fit=max\u0026auto=format\u0026n=9VolpVBxlj0nTDjr\u0026q=85\u0026s=dec660a801dfa5f9023e943a1865adee"},"favicon":"https://mintcdn.com/infra-docs-api/ovzHtUYxTTobyxo_/assets/convexity_icon.png?fit=max\u0026auto=format\u0026n=ovzHtUYxTTobyxo_\u0026q=85\u0026s=d51a715f20fdef4958598630b192183d","api":{"examples":{"languages":["curl","python","javascript"]}},"navbar":{"primary":{"type":"button","label":"Request access","href":"mailto:infra@withconvexity.com"}},"footer":{"socials":{"website":"https://withconvexity.com"}},"fonts":{"heading":{"family":"Space Grotesk"},"body":{"family":"Inter"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"infra-docs-api","hasAudioNarration":false,"actualSubdomain":"infra-docs-api","customDomains":["docs.withconvexity.com"],"gitSource":{"type":"github","owner":"convexityteam","repo":"convexity-infra-api-documentation","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6ae95ad4a79c9948d24e7aed:success","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"API Reference","count":57},{"language":"default","tag":"Tokenization","count":16},{"language":"default","tag":"Wallet","count":14},{"language":"default","tag":"Blockchain Events","count":8},{"language":"default","tag":"Documentation","count":8},{"language":"default","tag":"Projects","count":5},{"language":"default","tag":"Subscriptions","count":5},{"language":"default","tag":"Payments","count":4},{"language":"default","tag":"Getting Started","count":4},{"language":"default","tag":"Products","count":3}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[{"filePath":"style.css","content":"/* cyrillic-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: italic;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDba2o-flEEny0FZhsfKu5WU4xD-IQ-PuZJJXxfpAO-LfmOamaKjhw.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: italic;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDba2o-flEEny0FZhsfKu5WU4xD-IQ-PuZJJXxfpAO-LfmOTmaKjhw.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* greek */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: italic;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDba2o-flEEny0FZhsfKu5WU4xD-IQ-PuZJJXxfpAO-LfmOUmaKjhw.woff2) format('woff2');\n unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;\n}\n/* vietnamese */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: italic;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDba2o-flEEny0FZhsfKu5WU4xD-IQ-PuZJJXxfpAO-LfmOYmaKjhw.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: italic;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDba2o-flEEny0FZhsfKu5WU4xD-IQ-PuZJJXxfpAO-LfmOZmaKjhw.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: italic;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDba2o-flEEny0FZhsfKu5WU4xD-IQ-PuZJJXxfpAO-LfmOXmaI.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx3cwhsk.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxTcwhsk.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* greek */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxPcwhsk.woff2) format('woff2');\n unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;\n}\n/* vietnamese */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx_cwhsk.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx7cwhsk.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 400;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxDcwg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx3cwhsk.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxTcwhsk.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* greek */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxPcwhsk.woff2) format('woff2');\n unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;\n}\n/* vietnamese */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx_cwhsk.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx7cwhsk.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 500;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxDcwg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\n/* cyrillic-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx3cwhsk.woff2) format('woff2');\n unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;\n}\n/* cyrillic */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxTcwhsk.woff2) format('woff2');\n unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;\n}\n/* greek */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxPcwhsk.woff2) format('woff2');\n unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;\n}\n/* vietnamese */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx_cwhsk.woff2) format('woff2');\n unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;\n}\n/* latin-ext */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPx7cwhsk.woff2) format('woff2');\n unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C4, U+2113, U+2C60-2C7F, U+A720-A7FF;\n}\n/* latin */\n@font-face {\n font-family: 'JetBrains Mono';\n font-style: normal;\n font-weight: 700;\n font-display: swap;\n src: url(/_mintlify/assets/fonts/google/s/jetbrainsmono/v24/tDbv2o-flEEny0FZhsfKu5WU4zr3E_BX0PnT8RD8yKwBNntkaToggR7BYRbKPxDcwg.woff2) format('woff2');\n unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;\n}\ncode,pre,kbd,samp,tt,.font-mono,[class*=\"language-\"]{font-family:'JetBrains Mono', ui-monospace, SFMono-Regular, 'SF Mono',\n Menlo, Consolas, 'Liberation Mono', monospace!important}"}]}
{"page":{"pagePath":"api-reference/payments/overview","slug":"/api-reference/payments/overview","pageMetadata":{"title":"Overview","description":"Payment records and virtual bank accounts for wallet top-ups and subscription billing.","href":"/api-reference/payments/overview"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Payment records and virtual bank accounts for wallet top-ups and subscription billing.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{Heading,Table,Tip,Warning}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`The `,_jsx(_components.strong,{children:`Payments`}),` API lets you list the payments collected for your project and mint\none-time deposit accounts that settle into a wallet top-up or a subscription. Depending\non the settlement rail, a deposit account is either a `,_jsx(_components.strong,{children:`fiat bank account`}),` (bank\ntransfer in NGN) or a `,_jsx(_components.strong,{children:`stablecoin deposit wallet`}),` (USDC or cNGN, on-chain).`]}),`\n`,_jsx(Heading,{level:`2`,id:`how-funding-works`,children:`How funding works`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Mint a deposit account`}),` with `,_jsx(_components.a,{href:`/api-reference/payments/create-deposit-account`,children:`Create deposit account`}),`,\nstating the purpose: a subscription (`,_jsx(_components.code,{children:`planId`}),` + `,_jsx(_components.code,{children:`billingCycle`}),`) or a wallet\ntop-up (USD `,_jsx(_components.code,{children:`amount`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsxs(_components.strong,{children:[`The payer sends the exact `,_jsx(_components.code,{children:`amountExpected`})]}),` to the account before `,_jsx(_components.code,{children:`expiryAt`}),`:\na bank transfer for `,_jsx(_components.code,{children:`FIAT`}),`, an on-chain token transfer for `,_jsx(_components.code,{children:`STABLECOIN`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Settlement is automatic`}),`: the deposit is verified, an idempotent payment\nrecord is written, and the purpose is applied: the subscription activates (with\nproduct access granted) or the wallet balance is credited.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The step-by-step version, including per-rail payer instructions, lives in the\n`,_jsx(_components.a,{href:`/guides/fund-and-subscribe`,children:`Fund and subscribe`}),` guide.`]}),`\n`,_jsx(Heading,{level:`2`,id:`the-payment-object`,children:`The payment object`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Attribute`}),_jsx(_components.th,{children:`Type`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`id`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Unique payment id.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`purpose`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`WALLET_TOPUP`}),` or `,_jsx(_components.code,{children:`SUBSCRIPTION`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`status`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`PENDING`}),`, `,_jsx(_components.code,{children:`SUCCESS`}),`, `,_jsx(_components.code,{children:`FAILED`}),`, or `,_jsx(_components.code,{children:`REFUNDED`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`amount`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`number`})}),_jsxs(_components.td,{children:[`Amount in major units, denominated in `,_jsx(_components.code,{children:`currency`}),` (e.g. `,_jsx(_components.code,{children:`1500`}),` + `,_jsx(_components.code,{children:`NGN`}),` = ₦1,500).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`currency`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`ISO currency code the payment was collected in (`,_jsx(_components.code,{children:`NGN`}),` for bank transfers and cNGN, `,_jsx(_components.code,{children:`USD`}),` for USD-pegged stablecoins).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentRef`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Provider payment reference.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`subscriptionId`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string | null`})}),_jsxs(_components.td,{children:[`Linked subscription, for `,_jsx(_components.code,{children:`SUBSCRIPTION`}),` payments.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`projectId`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Project the payment belongs to.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`planId`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`integer | null`})}),_jsx(_components.td,{children:`Plan billed, for subscription payments.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`billingCycle`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string | null`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`MONTHLY`}),` or `,_jsx(_components.code,{children:`YEARLY`}),`, for subscription payments.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`businessId`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Owning business.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`providerId`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Upstream provider id.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`reference`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Idempotent reference for the payment.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`amountUsd`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`USD value as a decimal string.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`description`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Free-text note.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`createdBy`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Actor that created the record.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`createdAt`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`ISO 8601 UTC timestamp.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`updatedAt`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`ISO 8601 UTC timestamp.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`the-deposit-account-object`,children:`The deposit account object`}),`\n`,_jsxs(_components.p,{children:[`Returned by `,_jsx(_components.a,{href:`/api-reference/payments/create-deposit-account`,children:`Create deposit account`}),` in the\n`,_jsx(_components.code,{children:`data`}),` array, one entry per active provider. Each account is bound to a single expected\namount and expires.`]}),`\n`,_jsxs(_components.p,{children:[`The object is a `,_jsxs(_components.strong,{children:[`discriminated union on `,_jsx(_components.code,{children:`kind`})]}),`: the keys present depend on the rail, and\nyou only ever receive the keys for that rail. Always branch on `,_jsx(_components.code,{children:`kind`}),`; do not assume a field\nexists across both.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`A `,_jsx(_components.code,{children:`FIAT`}),` account carries `,_jsx(_components.strong,{children:`no`}),` on-chain keys (`,_jsx(_components.code,{children:`walletAddress`}),`, `,_jsx(_components.code,{children:`token`}),`, `,_jsx(_components.code,{children:`chainId`}),`, …) and a\n`,_jsx(_components.code,{children:`STABLECOIN`}),` account carries `,_jsx(_components.strong,{children:`no`}),` bank keys (`,_jsx(_components.code,{children:`accountNumber`}),`, `,_jsx(_components.code,{children:`bankName`}),`, …). The\nirrelevant keys are `,_jsx(_components.strong,{children:`absent`}),`, not `,_jsx(_components.code,{children:`null`}),`.`]})}),`\n`,_jsxs(Heading,{level:`3`,id:`fiat-bank-transfer`,children:[_jsx(_components.code,{children:`FIAT`}),`: bank transfer`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Attribute`}),_jsx(_components.th,{children:`Type`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`kind`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`Always `,_jsx(_components.code,{children:`FIAT`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`accountNumber`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Virtual bank account number to pay into.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`accountName`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Account holder name.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`bankName`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Bank the account is held with.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`bankCode`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Bank code.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`reference`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Reference that ties the funding to this account.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`amountExpected`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`number`})}),_jsxs(_components.td,{children:[`Exact amount to pay, in `,_jsx(_components.strong,{children:`NGN`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`fxRate`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`number`})}),_jsxs(_components.td,{children:[`NGN/USD rate (USD per 1 NGN) the quote was priced at, locked until `,_jsx(_components.code,{children:`expiryAt`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`expiryAt`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`ISO 8601 UTC expiry. Pay before this time (~1h).`})]})]})]}),`\n`,_jsxs(Heading,{level:`3`,id:`stablecoin-on-chain-deposit`,children:[_jsx(_components.code,{children:`STABLECOIN`}),`: on-chain deposit`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Attribute`}),_jsx(_components.th,{children:`Type`}),_jsx(_components.th,{children:`Description`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`kind`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`Always `,_jsx(_components.code,{children:`STABLECOIN`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`walletAddress`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Temporary on-chain deposit address to send tokens to.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`token`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`Token symbol (e.g. `,_jsx(_components.code,{children:`USDC`}),`, `,_jsx(_components.code,{children:`cNGN`}),`).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`pegCurrency`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`Fiat peg of the token: `,_jsx(_components.code,{children:`USD`}),` (USDC) or `,_jsx(_components.code,{children:`NGN`}),` (cNGN, 1:1 naira).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`contractAddress`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Token contract address.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`network`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`Chain family (e.g. `,_jsx(_components.code,{children:`EVM`}),`).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`blockchainNetwork`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsxs(_components.td,{children:[`Human-readable network name (e.g. `,_jsx(_components.code,{children:`Base`}),`).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`chainId`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`integer`})}),_jsxs(_components.td,{children:[`EVM chain id (e.g. `,_jsx(_components.code,{children:`8453`}),`).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`reference`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`Reference that ties the funding to this wallet.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`amountExpected`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`number`})}),_jsxs(_components.td,{children:[`Exact amount to send, in `,_jsx(_components.strong,{children:`token major units`}),`, denominated in the token’s peg currency (e.g. `,_jsx(_components.code,{children:`15`}),` = 15 USDC).`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`amountExpectedNgn`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`number`})}),_jsxs(_components.td,{children:[`Naira value to display to the payer. Present `,_jsx(_components.strong,{children:`only`}),` for naira-pegged tokens (cNGN), where it equals `,_jsx(_components.code,{children:`amountExpected`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`fxRate`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`number`})}),_jsxs(_components.td,{children:[`NGN/USD rate (USD per 1 NGN) the quote was priced at, locked until `,_jsx(_components.code,{children:`expiryAt`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`expiryAt`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`string`})}),_jsx(_components.td,{children:`ISO 8601 UTC expiry. Send before this time (~30m).`})]})]})]}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`For a cNGN deposit, show the payer the naira value, e.g.\n`,_jsx(_components.code,{children:`Send ₦22,556.39 (22,556.39 cNGN)`}),`. For USD-pegged tokens, show the token\namount, e.g. `,_jsx(_components.code,{children:`Send 15 USDC`}),`.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`fx-rate-lock`,children:`FX rate lock`}),`\n`,_jsxs(_components.p,{children:[`Every amount in a deposit-account response is priced at a single NGN/USD rate,\nreturned as `,_jsx(_components.code,{children:`fxRate`}),` (USD per 1 NGN). The rate is `,_jsx(_components.strong,{children:`locked for the life of the\naccount`}),`: when the deposit lands, settlement converts at the quoted rate, not\nthe live market rate, so what the payer owes and what gets credited can’t\ndrift inside the deposit window. After `,_jsx(_components.code,{children:`expiryAt`}),` the lock (and the account)\nexpires; request a new account to get a fresh rate.`]}),`\n`,_jsx(Heading,{level:`2`,id:`subscription-upgrades-are-prorated`,children:`Subscription upgrades are prorated`}),`\n`,_jsxs(_components.p,{children:[`If the project already holds an `,_jsx(_components.strong,{children:`active paid subscription to a different plan\nof the same product`}),`, a subscription request is treated as an upgrade:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`The unused value of the current subscription (`,_jsx(_components.code,{children:`current plan price × fraction of the billing period remaining`}),`) is credited against the new plan’s price.`]}),`\n`,_jsxs(_components.li,{children:[`Only the difference is charged. All amounts in the response already reflect\nthe credit, priced at the locked `,_jsx(_components.code,{children:`fxRate`}),`.`]}),`\n`,_jsx(_components.li,{children:`When the payment settles, the new subscription starts a full fresh period,\nthe old subscription is cancelled, and its product access is replaced by the\nnew plan’s.`}),`\n`,_jsxs(_components.li,{children:[`Moving from a `,_jsx(_components.strong,{children:`free`}),` plan to a paid plan of the same product works the same\nway, just with no credit: full price is charged, and the free subscription\nand its access grant are replaced on settlement.`]}),`\n`,_jsx(_components.li,{children:`If the credit would cover the entire new price (a downgrade or near-equal\nswitch), the request is rejected: no-charge plan switches are not supported.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`No special request field is needed: upgrades are detected server-side, and a\nrenewal is just a new request with the same `,_jsx(_components.code,{children:`planId`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Overview","description":"Payment records and virtual bank accounts for wallet top-ups and subscription billing.","href":"/api-reference/payments/overview"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"How funding works","slug":"how-funding-works","depth":2,"children":[]},{"title":"The payment object","slug":"the-payment-object","depth":2,"children":[]},{"title":"The deposit account object","slug":"the-deposit-account-object","depth":2,"children":[{"title":"FIAT: bank transfer","slug":"fiat-bank-transfer","depth":3,"children":[]},{"title":"STABLECOIN: on-chain deposit","slug":"stablecoin-on-chain-deposit","depth":3,"children":[]}]},{"title":"FX rate lock","slug":"fx-rate-lock","depth":2,"children":[]},{"title":"Subscription upgrades are prorated","slug":"subscription-upgrades-are-prorated","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"infra-docs-api","siteName":"Convexity Infra API","title":"Overview - Convexity Infra API","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-07-15T15:30:37.334Z","originalFileLocation":"api-reference/payments/overview.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Payment records and virtual bank accounts for wallet top-ups and subscription billing.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Convexity Infra API\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Overview - Convexity Infra API\">\u003cmeta data-mint-head property=\"og:description\" content=\"Payment records and virtual bank accounts for wallet top-ups and subscription billing.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Convexity Infra API\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.withconvexity.com/api-reference/payments/overview\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://infra-docs-api.mintlify.site/_mintlify/api/og/v2?division=Payments\u0026amp;title=Overview\u0026amp;description=Payment+records+and+virtual+bank+accounts+for+wallet+top-ups+and+subscription+billing.\u0026amp;theme=c36605d033072029a63dd44c\u0026amp;signature=476ad936351c7ae85fb61349279513eebfb12f832854fd16469b94baa9773fab\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Overview - Convexity Infra API\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Payment records and virtual bank accounts for wallet top-ups and subscription billing.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://infra-docs-api.mintlify.site/_mintlify/api/og/v2?division=Payments\u0026amp;title=Overview\u0026amp;description=Payment+records+and+virtual+bank+accounts+for+wallet+top-ups+and+subscription+billing.\u0026amp;theme=c36605d033072029a63dd44c\u0026amp;signature=476ad936351c7ae85fb61349279513eebfb12f832854fd16469b94baa9773fab\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/infra-docs-api/5vJ7DyhwL8d-5jlj/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Convexity Infra API\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2755BB\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.withconvexity.com/api-reference/payments/overview\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/payments/overview.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.withconvexity.com/#organization\",\"name\":\"Convexity Infra API\",\"url\":\"https://docs.withconvexity.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/infra-docs-api/9VolpVBxlj0nTDjr/assets/convexity_main_logo.png?fit=max\u0026auto=format\u0026n=9VolpVBxlj0nTDjr\u0026q=85\u0026s=dec660a801dfa5f9023e943a1865adee\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.withconvexity.com#website\",\"name\":\"Convexity Infra API\",\"url\":\"https://docs.withconvexity.com\",\"publisher\":{\"@id\":\"https://docs.withconvexity.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.withconvexity.com/api-reference/payments/overview#webpage\",\"url\":\"https://docs.withconvexity.com/api-reference/payments/overview\",\"name\":\"Overview\",\"description\":\"Payment records and virtual bank accounts for wallet top-ups and subscription billing.\",\"dateModified\":\"2026-07-15T15:30:37.334Z\",\"isPartOf\":{\"@id\":\"https://docs.withconvexity.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.withconvexity.com/api-reference/payments/overview#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.withconvexity.com/api-reference/payments/overview#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Convexity Infra API\",\"item\":\"https://docs.withconvexity.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Overview\",\"item\":\"https://docs.withconvexity.com/api-reference/payments/overview\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.withconvexity.com/api-reference/payments/overview#article\",\"headline\":\"Overview\",\"name\":\"Overview\",\"description\":\"Payment records and virtual bank accounts for wallet top-ups and subscription billing.\",\"url\":\"https://docs.withconvexity.com/api-reference/payments/overview\",\"mainEntityOfPage\":{\"@id\":\"https://docs.withconvexity.com/api-reference/payments/overview#webpage\"},\"dateModified\":\"2026-07-15T15:30:37.334Z\",\"publisher\":{\"@id\":\"https://docs.withconvexity.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.withconvexity.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Convexity Infra API\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Convexity Infra API\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/payments/overview.md","siteName":"Convexity Infra API","nav":{"global":null,"tabs":[{"tab":"Documentation","icon":"book-open","pages":[{"title":"Documentation","href":""}]},{"tab":"SDK","icon":"cube","pages":[{"title":"SDK","href":"/sdk"}]},{"tab":"API Reference","icon":"code","groups":[{"group":"Auth-Edge","pages":[{"title":"Overview","href":"/api-reference/auth-edge/overview"},{"title":"Generate token","openapi":"POST /v1/oauth/token","href":"/api-reference/auth-edge/generate-token"}]},{"group":"Projects","pages":[{"title":"Overview","href":"/api-reference/projects/overview"},{"title":"Regenerate API keys","openapi":"POST /v1/projects/api-keys/regenerate","href":"/api-reference/projects/regenerate-api-keys"},{"title":"List IP whitelist","openapi":"GET /v1/projects/ip-whitelist","href":"/api-reference/projects/list-ip-whitelist"},{"title":"Add IP to whitelist","openapi":"POST /v1/projects/ip-whitelist","href":"/api-reference/projects/add-ip-to-whitelist"},{"title":"Remove IP from whitelist","openapi":"DELETE /v1/projects/ip-whitelist/{id}","description":"Removes an IP address from the project allowlist by its entry id. Returns `404` if the entry does not exist.","href":"/api-reference/projects/remove-ip-from-whitelist"}]},{"group":"Payments","pages":[{"title":"Overview","href":"/api-reference/payments/overview"},{"title":"List project payments","openapi":"GET /v1/payments","description":"Returns a paginated list of payments for the calling project, newest first.","href":"/api-reference/payments/list-project-payments"},{"title":"Get subscription payments","openapi":"GET /v1/payments/subscription/{subscriptionId}","href":"/api-reference/payments/get-subscription-payments"},{"title":"Create deposit account","openapi":"POST /v1/payments/subscribe","href":"/api-reference/payments/create-deposit-account"}]},{"group":"Products","pages":[{"title":"Overview","href":"/api-reference/products/overview"},{"title":"List products","openapi":"GET /v1/products","href":"/api-reference/products/list-products"},{"title":"Get product by id","openapi":"GET /v1/products/{productId}","href":"/api-reference/products/get-product-by-id"}]},{"group":"Subscriptions","pages":[{"title":"Overview","href":"/api-reference/subscriptions/overview"},{"title":"List plans","openapi":"GET /v1/subscriptions/plans","href":"/api-reference/subscriptions/list-plans"},{"title":"List plans by product","openapi":"GET /v1/subscriptions/plans/product/{productId}","href":"/api-reference/subscriptions/list-plans-by-product"},{"title":"List my subscriptions","openapi":"GET /v1/subscriptions","href":"/api-reference/subscriptions/list-my-subscriptions"},{"title":"Get my subscription","openapi":"GET /v1/subscriptions/{id}","href":"/api-reference/subscriptions/get-my-subscription"}]},{"group":"Wallet","pages":[{"title":"Overview","href":"/api-reference/wallet/overview"},{"title":"Generate wallets","openapi":"POST /v1/wallet/hd/generate","href":"/api-reference/wallet/generate-wallets"},{"title":"List wallets","openapi":"GET /v1/wallet/hd","href":"/api-reference/wallet/list-wallets"},{"title":"Get wallet count","openapi":"GET /v1/wallet/hd/count","href":"/api-reference/wallet/get-wallet-count"},{"title":"Check HD enabled","openapi":"GET /v1/wallet/hd/enabled","href":"/api-reference/wallet/check-hd-enabled"},{"title":"Get wallet by address","openapi":"GET /v1/wallet/hd/address/{address}","href":"/api-reference/wallet/get-wallet-by-address"},{"title":"Get wallet by address index","openapi":"GET /v1/wallet/hd/address-index/{addressIndex}","href":"/api-reference/wallet/get-wallet-by-address-index"},{"title":"Sign transaction","openapi":"POST /v1/wallet/hd/sign","href":"/api-reference/wallet/sign-transaction"},{"title":"Deactivate wallet","openapi":"POST /v1/wallet/hd/deactivate/{walletId}","href":"/api-reference/wallet/deactivate-wallet"},{"title":"Initiate transfer","openapi":"POST /v1/wallet/transaction","href":"/api-reference/wallet/initiate-transfer"},{"title":"Get transaction history","openapi":"GET /v1/wallet/transaction/history","href":"/api-reference/wallet/get-transaction-history"},{"title":"Get transaction by id","openapi":"GET /v1/wallet/transaction/{id}","href":"/api-reference/wallet/get-transaction-by-id"},{"title":"Get balance","openapi":"GET /v1/wallet/balance","href":"/api-reference/wallet/get-balance"},{"title":"Get supported chains","openapi":"GET /v1/wallet/rpc/chains","href":"/api-reference/wallet/get-supported-chains"}]},{"group":"Tokenization","pages":[{"title":"Overview","href":"/api-reference/tokenization/overview"},{"title":"Create Token","openapi":"POST /v1/tokens","href":"/api-reference/tokenization/create-token"},{"title":"Get Token","openapi":"GET /v1/tokens/{id}","href":"/api-reference/tokenization/get-token"},{"title":"List Tokens","openapi":"GET /v1/tokens","href":"/api-reference/tokenization/list-tokens"},{"title":"Token Holders","openapi":"GET /v1/tokens/holders","href":"/api-reference/tokenization/token-holders"},{"title":"Mint Token","openapi":"POST /v1/tokens/mint","href":"/api-reference/tokenization/mint-token"},{"title":"Burn Token","openapi":"POST /v1/tokens/burn","href":"/api-reference/tokenization/burn-token"},{"title":"Transfer Token","openapi":"POST /v1/tokens/transfer","href":"/api-reference/tokenization/transfer-token"},{"title":"Register Wallet","openapi":"POST /v1/tokens/register-wallet","href":"/api-reference/tokenization/register-wallet"},{"title":"Get Transaction","openapi":"GET /v1/tokens/transactions/{ref}","href":"/api-reference/tokenization/get-transaction"},{"title":"List Transactions","openapi":"GET /v1/tokens/transactions","href":"/api-reference/tokenization/list-transactions"},{"title":"Update Yield","openapi":"PATCH /v1/tokens/yield","href":"/api-reference/tokenization/update-yield"},{"title":"Distribute Yield","openapi":"POST /v1/tokens/yield/distribute","href":"/api-reference/tokenization/distribute-yield"},{"title":"Pay Coupon","openapi":"POST /v1/tokens/yield/pay-coupon","href":"/api-reference/tokenization/pay-coupon"},{"title":"Claim Yield","openapi":"POST /v1/tokens/yield/claim","href":"/api-reference/tokenization/claim-yield"},{"title":"Redeem Principal","openapi":"POST /v1/tokens/yield/redeem","href":"/api-reference/tokenization/redeem-principal"}]},{"group":"Blockchain Events","pages":[{"title":"Overview","href":"/api-reference/indexer/overview"},{"title":"List event catalog","openapi":"GET /v1/indexer/events","href":"/api-reference/indexer/list-event-catalog"},{"title":"Create subscription","openapi":"POST /v1/indexer/subscriptions","href":"/api-reference/indexer/create-subscription"},{"title":"List subscriptions","openapi":"GET /v1/indexer/subscriptions","href":"/api-reference/indexer/list-subscriptions"},{"title":"Get subscription","openapi":"GET /v1/indexer/subscriptions/{id}","href":"/api-reference/indexer/get-subscription"},{"title":"Update subscription","openapi":"PATCH /v1/indexer/subscriptions/{id}","href":"/api-reference/indexer/update-subscription"},{"title":"Rotate signing secret","openapi":"POST /v1/indexer/subscriptions/{id}/rotate-secret","href":"/api-reference/indexer/rotate-signing-secret"},{"title":"Delete subscription","openapi":"DELETE /v1/indexer/subscriptions/{id}","href":"/api-reference/indexer/delete-subscription"}]}]}]},"basePath":"","title":"Overview - Convexity Infra API","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}