Receiving (USD Line of Credit)

receiving payments with usd line of credit this guide explains how to receive bitcoin (btc) payments into a usd denominated wallet using the voltage payments api with a usd wallet (backed by a line of credit), incoming btc is automatically converted to usd you present lightning invoices or on chain addresses for payment in btc, while your wallet balance is credited in usd for development testing, choose mutinynet usd payments arrive over bitcoin or lightning while the wallet and line of credit are denominated in usd mutinynet bitcoin and voltage cash are not the correct wallets for this workflow prerequisites a voltage account with an active usd wallet (credit backed wallet with an associated usd line of credit) an environment api key with access to the wallet's environment line of credit enabled with access to the quotes api the uuids for your organization, environment, wallet, and line of credit id workflow overview receiving funds into a usd wallet is a multi step process get a quote – use post /quotes to lock in the btc→usd conversion rate for the amount you expect to receive create a receive payment request – use post /payments to generate a lightning invoice, on chain address, or bip21 uri, including the quote id retrieve payment details – fetch the payment to get the actual invoice/address to present to the payer monitor status – wait for the payment to be received and credited usd wallets do not support "any amount" invoices because a specific quote (fixed amount) is required key data shapes amount object { "amount" 1000, "currency" "usd", "unit" "cents" } usd smallest unit is cents (1000 cents = $10 00) btc smallest unit is millisatoshis (150000 msats = 1500 sats) receive statuses generating – invoice/address is being created receiving – invoice/address generated and waiting for payment completed – fully received and credited expired – invoice expired before being paid failed – could not be generated or completed step 1 get a quote for btc→usd conversion before creating the receive payment, obtain a quote to lock in the conversion rate endpoint post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/quotes headers x api key your api key content type application/json example request curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/quotes' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "87654321 4321 8765 cba9 fed987654321", "line of credit id" "{line of credit id}", "network" "mainnet", "amount" { "amount" 100000, "currency" "btc", "unit" "msats" }, "to" "usd" }' request fields id – a client generated uuid for the quote line of credit id – your usd line of credit id network – the bitcoin network amount – the btc amount you expect to receive (in msats) to – target currency for conversion ("usd") save the quote id from the response for step 2 quotes are short lived (typically 2 minutes) to account for btc price volatility use a fresh quote when creating the payment step 2 create a receive payment with a quote ready, create the receive payment request endpoint post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments headers x api key your api key content type application/json 2 1 receive a lightning (bolt11) payment create a lightning invoice that, when paid in btc, credits your usd wallet curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "11ca843c bdaa 44b6 965a 39ac550fcef7", "wallet id" "{usd wallet id}", "currency" "usd", "payment kind" "bolt11", "quote id" "87654321 4321 8765 cba9 fed987654321", "amount" { "amount" 1000, "currency" "usd", "unit" "cents" }, "description" "receive btc, convert to $10 00", "expiration" 3600 }' request fields id – a client generated uuid for the payment wallet id – your usd wallet id currency – "usd" (must match the wallet's currency) payment kind – "bolt11" to create a lightning invoice quote id – the quote id from step 1 ( required for usd wallets ) amount – the usd amount you wish to receive (e g , 1000 cents = $10 00) description – optional memo to attach to the invoice (appears as memo in the response) expiration – optional expiration in seconds (default 3600, max 86400) the api will calculate the corresponding btc amount using the quote's rate and generate a lightning invoice for that btc amount 2 2 receive an on chain bitcoin payment generate a bitcoin address tied to your usd wallet curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "11ca843c bdaa 44b6 965a 39ac550fcef8", "wallet id" "{usd wallet id}", "payment kind" "onchain", "quote id" "87654321 4321 8765 cba9 fed987654321", "amount" { "amount" 1000, "currency" "usd", "unit" "cents" }, "currency" "usd", "description" "receive btc on chain, convert to $10 00" }' request fields payment kind – "onchain" to generate an on chain btc address quote id – the quote id ( required for usd wallets ) amount – the usd amount you aim to receive currency – "usd" description – optional description for your records the response will include a bitcoin address in data address data receipts entries as the transaction confirms generate a new receive payment (with a new quote) for each separate on chain payment you expect the quote locks the rate for that specific amount and timeframe if an on chain payment arrives after the quote expires, the payment may fail or be rejected always ensure the payer sends funds promptly within the quote validity window (typically 2 minutes) 2 3 receive a unified bip21 payment create a bip21 uri that includes both a lightning invoice and an on chain address, giving the payer flexibility curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments' \\ \ request post \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "id" "11ca843c bdaa 44b6 965a 39ac550fcef9", "wallet id" "{usd wallet id}", "payment kind" "bip21", "quote id" "87654321 4321 8765 cba9 fed987654321", "amount" { "amount" 1000, "currency" "usd", "unit" "cents" }, "currency" "usd", "description" "receive btc via bip21, convert to $10 00", "expiration" 3600 }' request fields payment kind – "bip21" for a unified payment request quote id – the quote id ( required ) amount – usd amount to receive expiration – optional expiration for the lightning invoice portion (the on chain address doesn't expire, but the quote's rate may not hold if significantly delayed) description – optional note the generated data address will be a bip21 uri the payer can scan whether they pay via lightning or on chain, your wallet will be credited in usd at the locked rate step 3 retrieve payment details after creating a receive payment, fetch it to get the actual invoice or address endpoint get https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id} example curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ header 'x api key your api key' example response { "direction" "receive", "id" "11ca843c bdaa 44b6 965a 39ac550fcef7", "wallet id" "{wallet id}", "organization id" "{organization id}", "environment id" "{environment id}", "created at" "2025 02 12t20 16 14 095785z", "updated at" "2025 02 12t20 16 14 807961z", "currency" "usd", "type" "bolt11", "data" { "payment request" "lntbs1500n1pn66qv ", "amount" { "amount" 1000, "currency" "usd", "unit" "cents" }, "memo" "receive btc, convert to $10 00", "expiration" 3600, "market quote" { "from" "btc", "to" "usd", "rate" "25000 00", "quoted at" "2025 02 12t20 16 14z" } }, "requested amount" { "amount" 1000, "currency" "usd", "unit" "cents" }, "status" "receiving", "error" null, "frozen" \[], "exchanges" \[] } key response fields direction – "receive" for incoming payments type – bolt11 | onchain | bip21 data payment request – the lightning invoice string (for bolt11/bip21) data address – the bitcoin address (for onchain/bip21) data market quote – the exchange rate used for conversion requested amount – the usd amount you originally requested status – current receive state error – structured error info if something failed frozen – parts of the payment frozen for compliance exchanges – currency exchange details listing incoming payments list and filter payments, including only receive direction ones endpoint get https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments query parameters direction=receive – only incoming payments wallet id={wallet id} – specific wallet statuses\[]=receiving\&statuses\[]=completed – filter by status offset , limit – pagination example curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments?direction=receive\&wallet id={wallet id}\&limit=50' \\ \ header 'x api key your api key' viewing payment history see the lifecycle of a receive payment get https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}/history the response contains ordered events with timestamps and errors (if any), useful for debugging and audits monitoring receive status typical state transitions generating → payment being set up receiving → invoice/address generated, waiting for funds completed → funds received and credited expired → invoice expired before payment failed → an error occurred you can monitor by polling get /payments/{payment id} until status is terminal ( completed , expired , or failed ) webhooks (recommended) webhooks for receive events create a webhook to get real time notifications when receive payments are generated, completed, expired, etc create a webhook post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/webhooks include in the request id – a client generated uuid for the webhook registration; the create response returns this same value url – your https endpoint name – webhook name events – array of event types, e g \[ { "receive" "generated" }, { "receive" "completed" }, { "receive" "expired" }, { "receive" "failed" } ] the create response also returns a one time shared secret store it for signature verification; it is not included in callbacks in a receive callback, detail data id is the payment id supplied when the payment was created, not the webhook id or organization id see webhooks /webhooks for the complete payload and identifier map test a webhook post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/webhooks/{webhook id}/test webhook payload receive webhook payloads include type – "receive" detail data – full payment object detail event – event type ( generated , refreshed , expired , succeeded , completed , failed ) error handling http status codes 202 – receive payment creation accepted 200 – successful retrieval/list/history 400 – invalid request (bad ids, missing fields, invalid quote, etc ) 403 – authentication/authorization error 404 – payment not found 500 – server error receive errors within the payment object, the error field may contain receive failed expired rejected for usd conversions, data market quote and exchanges help you understand which rate was used