Sending

sending payments this guide explains how to send lightning network and onchain bitcoin payments using the voltage api related guides for detailed guides specific to your wallet type sending (usd line of credit) docid 1qzxwddcqh5wuzv6qf 0a – for usd wallets (requires quotes) sending (btc line of credit) docid\ vfp1sk87foititazykggo – for btc wallets (no quotes needed) dashboard cross check for the btc workflow on this page, choose mutinynet bitcoin if you are testing the usd line of credit workflow, use mutinynet usd and follow sending (usd line of credit) docid 1qzxwddcqh5wuzv6qf 0a voltage cash is the experimental stablecoin test wallet and is not used for either btc or usd line of credit testing in the selected development wallet, select send , enter a test lightning invoice, and select review the review drawer shows the amount, maximum fee, method, route, and a truncated destination before submission after sending, confirm the terminal result in all payments use this dashboard flow to verify an integration manually automated systems should continue to read current payment state through the payments api and webhooks test lightning payment review drawer review the amount, maximum fee, method, route, and destination before sending completed test lightning payment confirmation wait for a terminal status before treating the payment as complete outgoing test payment in the sending wallet history use all payments to cross check the final outgoing state 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, "unit" "msats" // 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, "unit" "msats" // 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, "unit" "msats" // 15,000,000 msats = 15,000 sats }, "max fee" { "currency" "btc", "amount" 1000000, "unit" "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?lightning=lntbs1500n1p ", "payment request" "lntbs1500n1p ", // optional but recommended if you already have it "amount" { "currency" "btc", "amount" 150000, "unit" "msats" // optional if you rely purely on the bip21 uri amount }, "max fee" { "currency" "btc", "amount" 1000, "unit" "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 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) processing fees your organization can charge an optional percentage processing fee on payments processing fees are off by default and are configured per wallet see processing fees docid\ zcfo4a2q ihus83tx3m7d for how to view and set your rates when a rate is configured, send payment responses include a processing fee object and a payment breakdown { "processing fee" { "basis points" 100, "amount" { "currency" "btc", "amount" 1500, "unit" "msats" } }, "payment breakdown" { "principal" { "currency" "btc", "amount" 150000, "unit" "msats" }, "network fee" { "currency" "btc", "amount" 1000, "unit" "msats" }, "processing fee" { "currency" "btc", "amount" 1500, "unit" "msats" } } } processing fee basis points – the configured rate applied to this payment 100 is 1%, 250 is 2 5% processing fee amount – the fee calculated for this payment, in the principal's assessment currency it is available before settlement and stays stable across quote refreshes on a send, the processing fee is part of the amount debited from your wallet , alongside the network fee payment breakdown processing fee – the authoritative settled fee use this for reconciliation both fields are omitted when no processing fee applies, so this does not affect integrations that have no rate configured 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, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000, "unit" "msats" } } }' 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, "unit" "msats" }, "max fee" { "currency" "btc", "amount" 1000000, "unit" "msats" }, "description" "test payment" } }' check payment status curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ header 'x api key your api key' curl 'https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ header 'x api key your api key'