Sending (USD Line of Credit)

sending payments with usd line of credit this guide explains how to send lightning network and on chain bitcoin payments from a usd denominated wallet using the voltage payments api usd wallets leverage a line of credit to convert usd to btc at the time of payment prerequisites a voltage account with an active usd wallet (credit backed wallet with an associated usd line of credit) an api key with access to the environment (from the "api keys" page in your dashboard) the quotes api enabled, and a valid line of credit id for your usd wallet's line of credit the target lightning invoice or bitcoin address you intend to pay workflow overview sending from a usd wallet involves two steps obtain a conversion quote – use the post /quotes endpoint to get a quote for converting usd to btc this locks in an exchange rate and returns a quote id create the payment – call the post /payments endpoint with your usd wallet, including the quote id and payment details step 1 get a quote for usd→btc conversion before creating a payment from a usd wallet, you must get a quote to convert the payment amount into btc 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" 150000, "currency" "btc", "unit" "msats" }, "to" "usd" }' request fields id – a client generated uuid for the quote (for idempotency) line of credit id – your usd line of credit id network – the bitcoin network ("mainnet", "testnet", "signet", or "mutinynet") amount – the btc amount you need to send (in msats) to – target currency for conversion ("usd") the api will respond with a quote object containing an exchange rate and a quote id use that quote id in step 2 quotes are time limited use the quote promptly before it expires step 2 create a payment from the usd wallet with a valid quote in hand, create the payment using the post /payments endpoint 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 send a lightning (bolt11) payment to pay a lightning invoice from a usd wallet, provide the invoice in the payment request 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" "68d00852 8dd8 4c71 94d2 91c84695da78", "wallet id" "{usd wallet id}", "currency" "usd", "quote id" "12345678 1234 5678 9abc def012345678", "type" "bolt11", "data" { "payment request" "lnbc1500n1p ", "amount" { "currency" "btc", "amount" 150000, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000, "unit" "msats" } } }' request fields id – a client generated uuid for the payment (for idempotency) wallet id – the uuid of your usd wallet currency – "usd" (the wallet's currency) quote id – the uuid of the quote obtained in step 1 ( required for usd wallets ) type – "bolt11" for a lightning payment data payment request – the bolt 11 lightning invoice string (cannot be empty) data amount – optional btc amount object required if the invoice has no amount encoded; must match if the invoice has a fixed amount data max fee – optional maximum routing fee in btc (defaults to 1% of payment or 1,000 msats, whichever is greater) 2 2 send an on chain bitcoin payment to send btc on chain from a usd wallet, provide the bitcoin address and amount 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" "2ec1e783 19b4 4c10 8181 66336a6232bd", "wallet id" "{usd wallet id}", "currency" "usd", "quote id" "12345678 1234 5678 9abc def012345678", "type" "onchain", "data" { "address" "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "amount" { "currency" "btc", "amount" 15000000, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000000, "unit" "msats" }, "description" "payment for services" } }' request fields type – "onchain" for an on chain btc payment data address – the recipient's bitcoin address data amount – the amount to send in btc (msats) example 15,000,000 msats = 15,000 sats data max fee – optional maximum miner fee in msats data description – optional memo for your records 2 3 send a unified bip21 payment a bip21 uri can include both an on chain address and an embedded lightning invoice the api will parse the uri and execute the payment via lightning or on chain as appropriate 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" "3e84b6c5 5bbe 4e0f 9fb3 f1198330f6fa", "wallet id" "{usd wallet id}", "currency" "usd", "quote id" "12345678 1234 5678 9abc def012345678", "type" "bip21", "data" { "address" "bitcoin\ bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh?label=example%20store\&message=payment%20for%20services\&lightning=lnbc1500 qpz", "payment request" "lnbc1500n1p ", "amount" { "currency" "btc", "amount" 150000, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000, "unit" "msats" }, "description" "payment for services" } }' request fields type – "bip21" for a unified bitcoin payment data address – the bip21 uri string (required) data payment request – optional lightning invoice if you have it separately data amount – optional btc amount object (can be omitted if uri contains amount) data max fee – optional max lightning fee in msats data description – optional memo (independent of any invoice memo) monitoring payment status after initiating a payment, monitor its status using 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' payment states sending – payment is in progress completed – payment was successful and funds have been delivered failed – payment failed (check the error field for details) response fields for usd payments for completed usd payments, the response includes data market quote – the exchange rate used for usd/btc conversion data amount – the amount in usd that was debited from your wallet error handling http status codes 200 – success 400 – invalid request (missing fields, expired/invalid quote, etc ) 403 – authentication or permissions error 404 – resource not found 500 – server error common errors missing quote id – usd wallet payments require a valid quote id expired quote – quotes are time limited; obtain a new one invalid invoice – the lightning invoice is malformed or expired insufficient balance – your usd wallet doesn't have enough funds when a payment fails, the status will be "failed" and the error object will contain details about the failure reason