Glossary of Terms

term	definition
Quote	A temporary, binding price offer provided by Bitnob for a specific payout request, including funding amount, destination currency amount, and expiration time.
Quote ID	A unique identifier tied to a specific quote. Used to lock exchange rates and initiate payouts.
Trip	The milestone-timestamp object returned on a payout, tracking each critical event: quote_at, initialized_at, and finalized_at populate as the payout progresses. It carries timestamps only — there is no trip identifier.
Payout ID	The UUID Bitnob assigns to a payout, returned as id. Use it with Get Payout by ID to read the current status and trip timeline.
Reference	A unique identifier you generate for each payout, used to track transactions in your own systems and for idempotency.
Idempotency Key	The role reference plays on a payout: resending the same reference returns the existing payout instead of creating a second one, so a retried request after a timeout cannot double-pay.
API Key	The CLIENT_ID and CLIENT_SECRET issued per environment, used to authenticate every request. Sandbox and production keys are separate and not interchangeable.
Request Signature	The HMAC-SHA256 signature sent with each request, keyed with your CLIENT_SECRET over a timestamp and nonce. Bitnob authenticates with signed headers rather than a bearer token.
Funding Address	The blockchain address (or Lightning invoice) generated by Bitnob where the customer must send payment to fund a payout.
Payment Asset	The asset used to fund a payout (e.g., Bitcoin BTC, Tether USDT on TRC20 or ERC20, or Lightning Network payment).
Payout	The process of delivering fiat money to a beneficiary's bank account or mobile money wallet after successful funding.
Beneficiary	The final recipient of a payout — the person or business whose bank account or wallet will receive the funds.
Funding Status	The state of the payout’s funding phase (e.g., pending, paid, underpaid, expired).
Payout Status	The state of the payout (e.g., QUOTE, INITIATED, PENDING, PROCESSING, completed, failed). 'completed' is the only success state.
Completion Time	The timestamp at which the payout reaches a terminal state (success, failure, or expiry).
Time to Finish	The total duration (in seconds) between when the payout was submitted and when it completed.
Asset Received At	The timestamp when Bitnob first detects incoming payment at the funding address.
Asset Confirmed At	The timestamp when Bitnob considers the incoming payment fully confirmed and spendable.
Processing Start	The timestamp when Bitnob starts processing the fiat payout after funding is confirmed.
Settlement	Successful delivery of fiat funds to the beneficiary's account.
Settlement Failed	A payout that was funded but failed to be delivered due to reasons like invalid account numbers, bank rejections, or compliance blocks.
Callback URL	An optional URL provided by the customer where Bitnob sends webhook notifications about payout status changes.
Webhook	A real-time event notification sent from Bitnob to the customer’s server, signaling critical updates like funding received, payout started, payout success, or payout failure.
Funding Window	The period between when a quote is issued and when it expires, during which payment must be made.
On-the-Fly Settlement	A settlement model where the customer funds each payout individually in real-time, without maintaining a preloaded wallet balance at Bitnob.
Wallet-Funded Settlement	A settlement model where the customer maintains a prefunded wallet balance at Bitnob, and payouts are deducted from that balance instantly.
Sandbox Environment	A safe, simulated environment where customers can test payout flows without real money movement.
Production Environment	The live environment where real blockchain payments and fiat payouts are processed.
Expiry	The event when a quote or funding window expires before payment is received, canceling the payout attempt.
Underpayment	When the customer sends less than the required amount to fund a payout.
Overpayment	When the customer sends more than the required amount to fund a payout.
Settlement Window	The expected time it takes for a fiat payout to complete once processing has started, depending on corridor and method (e.g., NIP Instant, SEPA, ACH).

How to Use This Glossary

Reference it whenever integrating Bitnob Payouts APIs. The endpoints behind these terms: Create Payouts Quote (quote, quote ID, funding address), Initialize Payout (beneficiary, callback URL), Finalize Payout, Get Payout by ID (trip, payout status, completion time), and Payout Webhooks. API key and request signature are covered under Authentication.

Share it internally with engineering, product, ops, and finance teams building on Bitnob.

Use it to structure your monitoring dashboards and incident response systems.

It makes internal handoffs (PM → Engineering → Compliance → Support) much faster and cleaner.