Processing Fees

a processing fee is an optional percentage fee your organization charges on payments moving through a voltage wallet it 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 see the demo if you want to see processing fees applied to live payments, you can view a working example here https //voltage battleleague netlify app/ battle league runs on mutinynet test sats and charges a 1% (100 basis point) league processing fee on the payments that fund each competitor battle league demo https //voltage battleleague netlify app/ 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 where the rate lives a processing fee can be configured in two places, and only one of them is yours to set on the line of credit , as an organization wide default this is not exposed by the wallet policies endpoint and cannot be set through the api voltage configures it for your account, usually during onboarding on a wallet , as a processing fee wallet policy you set and change this yourself through the api, as described below a rate on the line of credit is what turns processing fees on until voltage has defined a rate on your line of credit, no processing fees are charged, and setting a wallet policy on its own will not change that to start charging processing fees, contact your voltage support team to have a rate configured on your line of credit once that is in place, a wallet policy overrides the line of credit rate for that wallet — the two do not stack a wallet inheriting 250 basis points that is then given a 100 basis point wallet policy is charged 100 basis points on the next payment, not 350 sending "processing fee" null removes the wallet override and restores the line of credit rate because the line of credit rate is not returned by the policies endpoint, a wallet with no policy of its own can still charge a rate it inherits treat the payment response, not the wallet policy, as the authoritative record of what was charged 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