Receiving (BTC Line of Credit)

receiving payments with bitcoin line of credit this guide explains how to receive lightning, on chain bitcoin, and bip21 unified payments into a btc denominated wallet using the voltage payments api prerequisites a voltage account with an active btc wallet (wallet associated with a bitcoin line of credit) an environment api key (x api key) from your dashboard no quotes needed! unlike usd wallets, btc wallets receive payments directly in btc without currency conversion you do not need to use the quotes api workflow overview receiving a payment is a two step process create a receive payment request (invoice/address/uri) retrieve the payment to get the invoice details and monitor status key data shapes amount object { "amount" 150000, "currency" "btc", "unit" "msats" } btc amounts use millisatoshis (msats) as the smallest unit legacy fields amount msats and amount sats are still accepted but deprecated prefer the amount object payment kinds (receive) bolt11 – lightning invoice onchain – on chain bitcoin address bip21 – unified bip21 uri (on chain + optional lightning) taprootasset – taproot asset invoice (not covered in this guide) receive statuses generating – invoice/address is being created receiving – invoice/address created and waiting for payment completed – fully received and credited expired – invoice expired before being paid failed – could not be generated or completed creating receive payments endpoint post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments headers x api key your api key content type application/json receive a fixed amount lightning (bolt11) payment 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" "{wallet id}", "currency" "btc", "payment kind" "bolt11", "amount" { "amount" 150000, "currency" "btc", "unit" "msats" }, "description" "test payment", "expiration" 3600 }' required fields id – your unique idempotent id (uuid recommended) wallet id – wallet that will receive funds currency – "btc" (must match the wallet's currency) payment kind – "bolt11" amount – amount object for the requested amount optional fields description – memo/description (appears as memo in the response) expiration – invoice expiry in seconds (default 3600, max 86400 for lightning) receive a lightning invoice with any amount btc wallets support "pay any amount" invoices simply omit the amount field 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" "b3e12e2f 5e80 4fb6 9c37 0a2d9af6c1f0", "wallet id" "{wallet id}", "currency" "btc", "payment kind" "bolt11", "description" "donation (any amount)", "expiration" 3600 }' any amount invoices are only supported for btc wallets, not usd wallets (which require a fixed quote) receive an on chain btc payment creates a new on chain address and tracks the payment 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" "{wallet id}", "currency" "btc", "payment kind" "onchain", "amount" { "amount" 150000000, "currency" "btc", "unit" "msats" }, "description" "on chain deposit" }' the response will include a bitcoin address in data address data receipts entries as the transaction confirms for accounting simplicity, please separate lightning and on chain usage between different wallets if you are on a node backed setup receive a bip21 unified payment (on chain + lightning) creates a bip21 uri that can embed both an on chain address and a lightning invoice 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" "{wallet id}", "currency" "btc", "payment kind" "bip21", "amount" { "amount" 150000, "currency" "btc", "unit" "msats" }, "description" "payment for services", "expiration" 3600 }' the resulting data will include payment request (optional bolt11) address (btc address) receipts for completed on chain or lightning parts retrieve payment details 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" "btc", "type" "bolt11", "data" { "payment request" "lntbs1500n1pn66qv ", "amount" { "amount" 150000, "currency" "btc", "unit" "msats" }, "amount msats" 150000, "memo" "test payment", "expiration" 3600, "market quote" null }, "requested amount" { "amount" 150000, "currency" "btc", "unit" "msats" }, "status" "receiving", "error" null, "frozen" \[], "exchanges" \[] } key response fields direction – always "receive" for incoming payments type – bolt11 | onchain | bip21 | taprootasset data payment request / data address / data receipts depending on type requested amount – what you originally requested status – current receive state error – structured error info if something failed frozen – parts of the payment frozen for compliance (e g , ofac) listing incoming payments 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), helpful for debugging or audits monitoring receive status typical state transitions generating → payment being set up (invoice/address generation) receiving → invoice/address generated, waiting for funds completed → funds received and credited expired → invoice expired before payment failed → an error occurred (see error field for details) 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 id – webhook id url – your https endpoint name – webhook name events – array of event types, e g { "receive" \["generated", "refreshed", "expired", "succeeded", "completed", "failed"] } test a webhook post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/webhooks/{webhook id}/test webhook payload 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 (invoice/address generation started) 200 – successful retrieval/list/history 400 – invalid request (bad ids, missing fields, etc ) 403 – authentication/authorization error 404 – payment not found in this organization + environment 500 – server error receive errors within the payment object, the error field may contain receive failed expired rejected