Receiving

receiving payments this guide explains how to receive lightning network 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) creating and retrieving a payment request receiving a payment is a two step process create a payment request retrieve the payment details step 1 create payment request 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 { "amount msats" 10000, "currency" "btc", "description" "test payment", "id" "11ca843c bdaa 44b6 965a 39ac550fcdf3", "payment kind" "bolt11", "wallet id" "{wallet id}" } required fields id a unique identifier for the payment wallet id the id of the wallet receiving the payment amount msats amount to receive in millisatoshis currency currently only "btc" is supported payment kind currently only "bolt11" is supported description description that will be included in the invoice step 2 retrieve payment details endpoint get https //voltageapi com/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id} headers x api key your api key response { "direction" "receive", "id" "{payment id}", "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" "lntbs1404n1pn66qv ", "amount msats" 10000, "memo" "test payment" }, "status" "receiving", "error" null } the payment request in the response contains the bolt11 invoice that should be provided to the payer complete example implementation \# step 1 create payment request 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 '{ "amount msats" 10000, "currency" "btc", "description" "test payment", "id" "11ca843c bdaa 44b6 965a 39ac550fcdf3", "payment kind" "bolt11", "wallet id" "{wallet id}" }' \# step 2 retrieve payment details to get bolt11 invoice curl 'https //voltageapi com/api/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ header 'x api key your api key' \# step 3 monitor payment status curl 'https //voltageapi com/api/v1/organizations/{organization id}/environments/{environment id}/payments/{payment id}' \\ \ header 'x api key your api key' monitoring payment status after creating a payment request, monitor its status using the same get endpoint the payment will transition through these states receiving waiting for payment completed payment received successfully failed payment failed (check error field for details) error handling common http status codes 200 success 201 payment request created 400 invalid request (check error message) 403 authentication error 404 payment not found 500 server error best practices generate unique payment ids for each request always retrieve the payment details after creation to get the bolt11 invoice store the payment id to track the payment status provide clear descriptions for better record keeping monitor payment status changes to update your application accordingly consider implementing webhook notifications for real time updates