Migrating to Credit Backed Payments

28 min

Drop your LND node entirely. Send and receive payments through the Voltage Payments API backed by a Line of Credit.

Prerequisites

You've read Migration Guide (auth changes, concept mapping, status mapping, amount handling)

Your business is eligible for a Voltage Line of Credit (US-based, approved states)

Migration Steps

Apply for a Line of Credit

Post collateral

Create Payments environment and wallet

Set up webhooks

Migrate sending

Migrate receiving

Implement reconciliation loop

Parallel run

Cut over and decommission node

Step 1: Apply for a Line of Credit

Follow the Credit-backed Setup guide to submit your application. You'll need:

Organization structure and TIN

Beneficial owner information (25%+ ownership)

Officer/director details

Estimated monthly send and receive volumes

After submitting, Voltage reviews your application. If approved, you'll receive an email with your approved credit amount, billing cycle, and collateral requirements.

Step 2: Post Collateral

If collateral is required:

Navigate to your Billing Dashboard in the Voltage UI

Send BTC to the provided multi-sig address (secured by distributed keys)

Once the required amount confirms, your account is enabled for mainnet payments

Step 3: Create Payments Environment and Wallet

Go to the Payments product in the Voltage dashboard

Create a new environment

Create a new wallet — do not check "I want to use a team infrastructure node"

Choose your wallet currency:

BTC — payments denominated in Bitcoin, no quotes needed

USD — payments denominated in US dollars, requires the Quotes API for every payment

Generate an API key for the environment

After this step you'll have:

organization_id, environment_id, wallet_id

Your x-api-key

(If USD) Your line_of_credit_id for the Quotes API

USD wallets require a quote before every send and receive. See Sending (USD Line of Credit) and Receiving (USD Line of Credit) for the full workflow.

Step 4: Set Up Webhooks

This step is identical to the node-backed path. Register a webhook to receive real-time payment events.

curl "https://voltageapi.com/v1/organizations/{organization_id}/environments/{environment_id}/webhooks" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "x-api-key: your-api-key" \
  --data '{
    "id": "b0fc9829-f139-4035-bb14-4a4b6cd58f0e",
    "organization_id": "{organization_id}",
    "environment_id": "{environment_id}",
    "url": "https://your-domain.com/webhook",
    "name": "Migration Webhook",
    "events": [
      { "send": "succeeded" },
      { "send": "failed" },
      { "receive": "generated" },
      { "receive": "completed" },
      { "receive": "expired" },
      { "receive": "failed" }
    ]
  }'

Save the shared_secret from the response. Implement signature verification using the x-voltage-signature and x-voltage-timestamp headers. See the Webhooks guide for full details.

Step 5: Migrate Sending

The Payments API send endpoint is the same regardless of whether your wallet is node-backed or credit-backed.

Lightning Payment (BTC wallet)

Before (LND REST):

curl --cacert tls.cert \
  --header "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 admin.macaroon)" \
  https://your-node.voltage.cloud:8080/v2/router/send \
  --request POST \
  --data '{
    "payment_request": "lntbs1500n1p...",
    "timeout_seconds": 60,
    "fee_limit_msat": 1000,
    "no_inflight_updates": true
  }'

After (Payments API):

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": "{wallet_id}",
    "currency": "btc",
    "type": "bolt11",
    "data": {
      "payment_request": "lntbs1500n1p...",
      "amount": {
        "currency": "btc",
        "amount": 150000,
        "unit": "msats"
      },
      "max_fee": {
        "currency": "btc",
        "amount": 1000,
        "unit": "msats"
      }
    }
  }'

USD wallets: You must first obtain a quote via POST /quotes, then include the quote_id and set currency: "usd" in the payment request. See Sending (USD Line of Credit) for the full two-step flow.

On-chain Payment

Before (LND REST):

curl --cacert tls.cert \
  --header "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 admin.macaroon)" \
  https://your-node.voltage.cloud:8080/v1/transactions \
  --request POST \
  --data '{
    "addr": "tb1pzkhtj4ld86g9c49du5yagnncfrm0s489t76vmrwmt2ecxfnf7spsvjte49",
    "amount": 15000,
    "sat_per_vbyte": 10
  }'

After (Payments API):

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": "{wallet_id}",
    "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"
    }
  }'

Step 6: Migrate Receiving

Lightning Invoice (BTC wallet)

Before (LND REST):

curl --cacert tls.cert \
  --header "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 admin.macaroon)" \
  https://your-node.voltage.cloud:8080/v1/invoices \
  --request POST \
  --data '{
    "value_msat": 150000,
    "memo": "test payment",
    "expiry": 3600
  }'

After (Payments API) — Step 1: Create the receive payment:

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": "11ca843c-bdaa-44b6-965a-39ac550fcef7",
    "wallet_id": "{wallet_id}",
    "currency": "btc",
    "payment_kind": "bolt11",
    "amount": {
      "amount": 150000,
      "currency": "btc",
      "unit": "msats"
    },
    "description": "test payment",
    "expiration": 3600
  }'

After — Step 2: Fetch the invoice:

curl 'https://voltageapi.com/v1/organizations/{organization_id}/environments/{environment_id}/payments/11ca843c-bdaa-44b6-965a-39ac550fcef7' \
  --header 'x-api-key: your-api-key'

The data.payment_request field contains the BOLT11 invoice string.

USD wallets: Obtain a quote first, then include quote_id and set currency: "usd" with the amount in cents. See Receiving (USD Line of Credit) for the full workflow.

On-chain Receive

Before (LND REST):

curl --cacert tls.cert \
  --header "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 admin.macaroon)" \
  https://your-node.voltage.cloud:8080/v1/newaddress?type=TAPROOT_PUBKEY

After (Payments API):

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": "11ca843c-bdaa-44b6-965a-39ac550fcef8",
    "wallet_id": "{wallet_id}",
    "currency": "btc",
    "payment_kind": "onchain",
    "amount": {
      "amount": 150000000,
      "currency": "btc",
      "unit": "msats"
    },
    "description": "on-chain deposit"
  }'

Fetch the payment to get data.address.

Step 7: Implement Reconciliation Loop

Same as the node-backed path. Set up a cron job (every 1–5 minutes) that lists recently updated payments and upserts them into your database. See the Webhooks guide under "Reconciliation Loop" for the full implementation.

Step 8: Parallel Run

Run both integrations side by side. Since you're migrating off the node entirely, focus your verification on the Payments API path.

Verification checklist:

Send a Lightning payment via the Payments API → completed

Receive a Lightning payment via the Payments API → invoice generated, completed

Send an on-chain payment via the Payments API → completed

Receive an on-chain payment via the Payments API → address generated, completed

Webhooks fire for all events

Reconciliation loop catches all payments

Step 9: Cut Over and Decommission Node

Decommission only after the Payments API path has passed the parallel-run checks and the operating owner has approved the change.

1. Stop all direct LND API calls

Disable your old integration. All payment traffic should now flow through the Payments API.

2. Confirm recovery readiness

Before changing channels or moving funds:

Recovery material: current approved workflow → current owner → last validation date → storage location

Recovery validation: current approved workflow → current owner → validate current recovery artifact

Do not rely on an unverified dashboard path or an untested backup.

3. Plan channel closure

Inventory open and pending channels, on-chain funds, unsettled payments, and automated liquidity workflows. Use the current supported node tooling and an approved runbook. Prefer cooperative closure when operating conditions allow it.

Runbook checkpoint:

# Verify the current supported closure command before execution.

Use an approved node tool to review Channels → record each approved closure.

Treat force closure as an exception. Review the current timelock, recovery implications, and approval requirements before proceeding.

4. Wait for closures to confirm on-chain

Use the current supported node tooling to monitor pending resolutions. Do not rely on an unverified command syntax. Wait for the confirmation depth required by your policy before proceeding.

5. Withdraw remaining on-chain balance

Move remaining on-chain funds only through the approved treasury workflow:

# Verify the approved destination and current fund-movement command before execution.

Record the destination, amount, operator, and transaction identifier.

6. Verify zero balances

Confirm there are no pending payments, unresolved channels, or balances that still require custody action:

# Use the current approved reconciliation workflow.

Retain final reconciliation evidence.

7. Deprovision through the approved process

Confirm the current Voltage product workflow with your account owner or Voltage Support before changing the Infrastructure product state or deleting the node.

8. Confirm billing impact

Confirm the current billing workflow before changing the Infrastructure plan, and record the completion evidence.

What You No Longer Manage

Responsibility	Before (Direct LND)	After (Credit-backed)
Node uptime	You monitor and restart	Not applicable
Channels	You open, close, rebalance	Not applicable
Liquidity	You manage capacity + treasury	Not applicable
Routing	LND pathfinding or custom	Not applicable
TLS certificates	Load, rotate, distribute	Not applicable
Macaroons	Bake, secure, inject	Not applicable
Backups and recovery	You maintain approved recovery procedures	Not applicable
Node access	You operate credentials and availability	Not applicable

Billing

With a Line of Credit, you're billed on a regular cycle based on your approved terms. Your billing dashboard shows:

Current credit utilization

Billing cycle dates

Payment history

Confirm current utilization, billing-cycle, and payment-record details in the dashboard or with your account owner. Technical documentation does not define pricing or contract terms.