Processing Fees

processing fees a processing fee is an optional percentage fee your organization charges on payments moving through a voltage wallet it is configured per wallet as a wallet policy , is set independently for sends and receives, and is currency agnostic — the same configuration applies to btc and usd wallets processing fees are off by default until a rate is set, processing fee is omitted from payment responses, so existing integrations are unaffected how rates are expressed rates use basis points applied to the payment principal basis points rate 0 disabled for that direction 100 1% 250 2 5% 10000 100% (maximum accepted value) your organization may have a lower ceiling than 10000 if you exceed it, the rate is rejected and the error reports the applicable max basis points contact your voltage support team to discuss your ceiling or to set defaults at the line of credit level, which is not configurable through the api who pays the fee direction determines where the fee lands send — the processing fee is part of the amount debited from your wallet, alongside the network fee receive — the processing fee is included in the payer facing amount on the generated invoice, address, or bip21 uri the payer funds it, and it sits outside the amount credited to your wallet viewing current rates endpoint get https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}/policies wallet policies are addressed by organization and wallet unlike the payments endpoints, this route is not environment scoped headers x api key your api key response returns every policy on the wallet the processing fee policy has type processing fee { "id" "9f0f8e5c 8a7b 4a3f 9f1e 2b6d4c7a1e55", "organization id" "4b2f1a63 0f9d 4a2e 9d3b 5c8e2a1f7b04", "policies" \[ { "type" "processing fee", "data" { "id" "c1d2e3f4 5a6b 4c7d 8e9f 0a1b2c3d4e5f", "rates" { "send basis points" 100, "receive basis points" 250 }, "created at" "2026 08 01t12 00 00 000z", "updated at" "2026 08 20t09 31 44 117z" } } ], "updated at" "2026 08 20t09 31 44 117z" } a wallet with no processing fee configured simply has no processing fee entry in policies setting rates endpoint patch https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}/policies requires organization write access a successful request returns 202 accepted headers x api key your api key content type application/json request body { "processing fee" { "send basis points" 100, "receive basis points" 250 } } both fields are required when you supply a processing fee object the field supports three distinct actions set an override — supply exact rates, as above restore inheritance — send "processing fee" null to drop the wallet override and fall back to the line of credit configuration leave unchanged — omit the field entirely to charge on one direction only, set the other to 0 { "processing fee" { "send basis points" 0, "receive basis points" 250 } } example curl 'https //voltageapi com/v1/organizations/{organization id}/wallets/{wallet id}/policies' \\ \ request patch \\ \ header 'x api key your api key' \\ \ header 'content type application/json' \\ \ data '{ "processing fee" { "send basis points" 100, "receive basis points" 250 } }' the same request body updates other wallet policies alongside the fee, such as max payment size sats , transactions per minute , send volume limit sats , and ofac compliant any field you omit is left unchanged reading the fee on a payment once a rate is set, send and receive 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 exact configured rate applied to this payment processing fee amount — the server calculated fee, in the principal's assessment currency it is available before settlement and stays stable across quote refreshes, and for receives across partial or excess payments payment breakdown processing fee — the authoritative settled fee use this for reconciliation and accounting both fields are omitted when no processing fee applies to the payment errors responses from the wallet policies endpoints 400 – badly formatted request, or no updates provided ( no updates provided ) 401 – authentication failed 403 – organization access required (read to view, write to update) 404 – no wallet found for that id in the organization, or no policies found for the wallet 422 – request json is invalid 500 – server error policy validation problems are reported in the error field of the wallet policies response, with type set to one of invalid processing fee rates – a rate is outside the accepted range the context reports the offending direction , the submitted basis points , and the applicable max basis points multiple processing fee policies – more than one processing fee policy resolved for the wallet policy not found – the referenced policy does not exist related guides sending docid\ ijeswowxjhpgyt6fv1kk1receiving docid uq9knquoc9sgq0kuogmy