Receiving

receiving payments this guide explains how to receive lightning , on chain bitcoin , and bip21 unified payments using the voltage payments api prerequisites a voltage account with at least one wallet in the target environment an environment api key (x api key) from your dashboard for usd wallets (receiving btc → usd), a line of credit and access to the quotes api high‑level flow receiving a payment is still a two‑step process create a receive payment request (invoice / address / uri) retrieve the payment to get the invoice details and monitor status all of this happens via the payments endpoints post /organizations/{organization id}/environments/{environment id}/payments – create send or receive payments get /organizations/{organization id}/environments/{environment id}/payments/{payment id} – get a single payment get /organizations/{organization id}/environments/{environment id}/payments – list payments (filter for direction=receive) get /organizations/{organization id}/environments/{environment id}/payments/{payment id}/history – timeline of status changes key data shapes amount { "amount" 150000, "currency" "btc", "unit" "msats" } supported patterns btc smallest unit is millisatoshis { "amount" 150000, "currency" "btc", "unit" "msats" } usd smallest unit is cents { "amount" 1000, "currency" "usd", "unit" "cents" } assets smallest unit is base units { "amount" 1000000, "currency" "asset 034d8 fd62e", "unit" "base units" } legacy fields amount msats and amount sats are still accepted but deprecated prefer the amount object payment kinds (receive) when creating a receive payment, you set "payment kind" "bolt11" | "onchain" | "bip21" | "taprootasset" bolt11 – lightning invoice onchain – on chain bitcoin address bip21 – unified bip21 uri (on chain + optional ln) taprootasset – taproot asset invoice receive statuses for incoming payments, the status field uses 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 step 1 – create a receive payment endpoint post /organizations/{organization id}/environments/{environment id}/payments headers x api key your api key content type application/json 1 1 receive a fixed‑amount lightning (bolt11) payment – btc wallet use the “receive payment with specific amount” shape 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 (fixed‑amount receive) id – your unique idempotent id (uuid recommended) wallet id – wallet that will receive funds payment kind – "bolt11" | "onchain" | "bip21" | "taprootasset" amount – amount object for the requested amount optional description – memo / description expiration – invoice expiry in seconds (defaults to 3600; max 86400 for ln / bip21) 1 2 receive a lightning invoice with any amount (btc wallet only) for “pay any amount” invoices, use the “receive payment with any amount” shape 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 }' notes currency must be "btc" payment kind can be "bolt11" or "bip21" no amount is included; the payer chooses the amount 1 3 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 1 4 receive a bip21 unified payment (on‑chain + ln) 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 ln parts 1 5 receive via a usd wallet (btc → usd) for usd wallets , you must get a quote (post /quotes) to convert btc ↔ usd use the returned quote id when creating the receive payment 1 5 1 get a quote (btc → usd) 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" }' use the resulting quote id in your receive payment request 1 5 2 receive fixed‑amount lightning into 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}", "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 }' in the payment response data amount will be in usd data market quote will show the exchange rate used to convert btc → usd usd “any‑amount” receives are not supported, because they require a fixed quote 1 5 3 receive on‑chain into 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" }' notes (in text) quote id is required for usd wallets amount is the usd value your wallet should ultimately receive the response data amount and requested amount will be in usd, and data market quote / exchanges explain the conversion used 1 5 4 receive bip21 into 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 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 }' here the generated data address will be a bip21 uri that your payer can scan (on‑chain and/or lightning), but your wallet balance will be settled in usd step 2 retrieve payment details endpoint get /organizations/{organization id}/environments/{environment id}/payments/{payment id} headers x api key your api key example response – btc lightning receive { "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 fields for receives 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 (generating, receiving, expired, failed, completed) error – structured error info if something failed frozen – parts of the payment frozen for compliance (e g , ofac) exchanges – currency exchange details when quotes/markets are involved listing incoming payments you can list and filter payments, including only receive‑direction ones endpoint get /organizations/{organization id}/environments/{environment id}/payments useful query params direction=receive – only incoming payments wallet id={wallet id} – specific wallet statuses\[]=receiving\&statuses\[]=completed – filter by status pagination offset , limit 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 to see the lifecycle of a receive payment get /organizations/{organization id}/environments/{environment id}/payments/{payment id}/history example response contains ordered events with timestamps and errors (if any), which is helpful for debugging or audits monitoring receive status typical state transitions for incoming payments 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 ) and/or by using webhooks (recommended) webhooks for receive events (recommended) create a webhook to get real‑time notifications when receive payments are generated, completed, expired, etc create a webhook post /organizations/{organization id}/environments/{environment id}/webhooks newwebhookrequest includes id – webhook id url – your https endpoint name – webhook name events – an array of event type objects (e g {"receive" \["generated","refreshed","expired","succeeded","completed","failed"]}) you can test webhooks with post /organizations/{organization id}/environments/{environment id}/webhooks/{webhook id}/test receive webhook payloads include type "receive" detail data – full payment object detail event – receive event type ( generated , refreshed , expired , succeeded , completed , failed ) error handling common http responses from payments endpoints 202 – receive payment creation accepted (invoice/address generation started) 200 – successful retrieval / list / history 400 – invalid request (bad ids, missing fields, invalid quote for usd, etc ) 403 – authentication/authorization error 404 – payment not found in this organization + environment 500 – server error within the payment object receive errors (in error) include receive failed expired rejected for usd conversions, data market quote + exchanges help you understand which rate was used