Receiving

receiving payments this guide explains how to receive lightning , on chain bitcoin , and bip21 unified payments using the voltage payments api related guides for detailed guides specific to your wallet type – for usd wallets (requires quotes) – for btc wallets (no quotes needed) 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 supported patterns btc smallest unit is millisatoshis usd smallest unit is cents assets smallest unit is 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 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 headers 1 1 receive a fixed‑amount lightning (bolt11) payment – btc wallet use the “receive payment with specific amount” shape required fields note the description field in your request appears as memo in the response required fields (fixed‑amount receive) 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" | "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 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 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 the resulting data will include payment request (optional bolt11) address (btc address) receipts for completed on chain or ln parts step 2 retrieve payment details endpoint headers example response – btc lightning receive 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 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 viewing payment history to see the lifecycle of a receive payment 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 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 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