Sending

sending payments this guide explains how to send lightning network and onchain bitcoin payments using the voltage api prerequisites a voltage account with an active wallet an api key (get this from the "api keys" page in your dashboard) sending a payment endpoint post https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments headers x api key your api key content type application/json request body lightning payment (bolt11) { "id" "68d00852 8dd8 4c71 94d2 91c84695da78", // uuid created by you "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "btc", "type" "bolt11", "data" { "payment request" "lntbs1500n1p ", // required lightning invoice to pay (cannot be empty) "amount" { "currency" "btc", "amount" 150000 // optional when payment request already contains an amount // required when payment request has no amount // if provided with an amount containing payment request, values must match // must be greater than 0 (msats) }, "max fee" { "currency" "btc", "amount" 1000 // optional defaults to 1% of payment value or 1,000 msats (whichever is greater) // must be greater than 0 (msats) // legacy alias max fee msats is also accepted } } } onchain payment { "id" "2ec1e783 19b4 4c10 8181 66336a6232bd", "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "btc", "type" "onchain", "data" { "address" "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49", "amount" { "currency" "btc", "amount" 15000000 // msats; 15,000,000 msats = 15,000 sats }, "max fee" { "currency" "btc", "amount" 1000000 // msats }, "description" "test payment" } } unified payment (bip21) { "id" "3e84b6c5 5bbe 4e0f 9fb3 f1198330f6fa", "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "btc", "type" "bip21", "data" { "address" "bitcoin\ tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49?amount=0 0015\&lightning=lntbs1500n1p ", "payment request" "lntbs1500n1p ", // optional but recommended if you already have it "amount" { "currency" "btc", "amount" 150000 // msats (optional if you rely purely on the bip21 uri amount) }, "max fee" { "currency" "btc", "amount" 1000 // msats }, "description" "payment for services" } } required fields id – unique identifier for the payment (uuid you create) wallet id – id of the btc wallet sending the payment currency – must be "btc" type – must be "bip21" data address – bip21 uri to pay (cannot be empty) optional but common data payment request – optional lightning invoice (if you want to pass it separately) data amount – btc amount object in msats data max fee – btc amount object in msats (max lightning fee) data description – optional description/memo usd wallet sending bip21 (with quote) { "id" "3e84b6c5 5bbe 4e0f 9fb3 f1198330f6fa", "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "usd", "quote id" "12345678 1234 5678 9abc def012345678", // required for usd wallets "type" "bip21", "data" { "address" "bitcoin\ bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh?amount=0 0015\&label=example%20store\&message=payment%20for%20services\&lightning=lntbs1500n1p ", "payment request" "lntbs1500n1p ", "amount" { "currency" "btc", "amount" 150000 // msats of btc to send }, "max fee" { "currency" "btc", "amount" 1000 // msats max lightning fee }, "description" "payment for services" } } required fields id – unique identifier for the payment (uuid you create) wallet id – id of the usd wallet sending the payment currency – must be "usd" quote id – quote id from post /quotes (required for usd wallets to convert usd → btc) type – must be "bip21" data address – bip21 uri to pay (cannot be empty) optional but common data payment request – optional lightning invoice data amount – btc amount object (msats of btc to send) data max fee – btc amount object (msats max lightning fee) data description – optional description/memo monitoring payment status after sending a payment, monitor its status using get https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id} the payment will transition through these states sending payment is in progress completed payment was successful failed payment failed (check error field for details) error handling common http status codes 200 success 400 invalid request (check error message) 403 authentication error 404 payment not found 500 server error example implementation lightning payment (btc) \# send lightning payment (btc 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" "68d00852 8dd8 4c71 94d2 91c84695da78", "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "btc", "type" "bolt11", "data" { "payment request" "lntbs1500n1p ", "amount" { "currency" "btc", "amount" 150000 }, "max fee" { "currency" "btc", "amount" 1000 } } }' lightning payment (usd) \# send lightning payment (usd wallet requires quote id) 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" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "usd", "quote id" "12345678 1234 5678 9abc def012345678", "type" "bolt11", "data" { "payment request" "lntbs1500n1p ", "amount" { "currency" "btc", "amount" 150000 }, "max fee" { "currency" "btc", "amount" 1000 } } }' onchain payment (btc) \# send onchain payment (btc 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" "2ec1e783 19b4 4c10 8181 66336a6232bd", "wallet id" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "btc", "type" "onchain", "data" { "address" "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49", "amount" { "currency" "btc", "amount" 15000000 // msats; 15,000,000 msats = 15,000 sats }, "max fee" { "currency" "btc", "amount" 1000000 // msats }, "description" "test payment" } }' onchain payment (usd) \# send onchain payment (usd wallet requires quote id) 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" "7a68a525 9d11 4c1e a3dd 1c2bf1378ba2", "currency" "usd", "quote id" "12345678 1234 5678 9abc def012345678", "type" "onchain", "data" { "address" "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "amount" { "currency" "btc", "amount" 15000000 }, "max fee" { "currency" "btc", "amount" 1000000 }, "description" "payment for services" } }' check payment status curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ header 'x api key your api key'