Send Lightning Payment

Availability

ℹ️
Production access
To enable Lightning Network in production, contact the partner success team.

Overview

The Cybrid platform supports sending Lightning Network payments in USD or BTC.

Sending payments requires an invoice_operations pre-fund account. This bank-level account holds a balance with Cybrid's Lightning Network provider, enabling instant payment of Lightning invoices. Invoice operations accounts can hold USD or BTC.

Customer payments are made from the invoice operations pre-fund account. When a payment occurs, the payment amount is also book-transferred from the customer's fiat account (for USD) or trading account (for BTC) to the bank's corresponding account. Both the invoice operations account and the customer's account must have sufficient balance to cover the payment amount including network fees.

Terminology:

Payer — the Cybrid partner's customer sending payment.
Payee — the payer's end-merchant receiving payment.

Steps to send a Lightning Network payment:

Create bank-level fiat or trading accounts.
Create and fund a customer-level account.
Create an invoice operations pre-fund account.
Fund the invoice operations account via inter-account transfer.
Create a Lightning Network payment transfer.
Top up the invoice operations account as needed.

1. Create bank-level accounts

If not already created, set up a bank-level fiat account (for USD) or trading account (for BTC). This is a one-time operation.

See Platform Accounts.

2. Create and fund the customer-level account

Create a customer-level fiat or trading account (one-time), then fund it (ongoing).

See Creating Platform Accounts and Funding Accounts.

3. Create an invoice operations pre-fund account

Create the invoice operations account at the bank level (one-time) via POST /api/accounts:

{
  "type": "invoice_operations",
  "asset": "USD",
  "name": "<insert account descriptive name>"
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "type": "invoice_operations",
  "guid": "<created account GUID>",
  "asset": "USD",
  "name": "<inserted account descriptive name>",
  "bank_guid": "<associated bank_guid>",
  "platform_balance": 0,
  "platform_available": 0,
  "state": "storing",
  "labels": null
}

The account begins in state: "storing" and progresses to state: "created" (terminal state).

4. Fund the invoice operations account

Fund the invoice operations account so customers can send payments. This is an ongoing operation.

ℹ️
Account for network fees
When funding the invoice operations account, include enough balance to cover potential network fees.

Create a quote via POST /api/quotes:

{
  "product_type": "inter_account",
  "asset": "USD",
  "deliver_amount": 10000
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created quote_guid>",
  "product_type": "inter_account",
  "bank_guid": "<associated bank_guid>",
  "asset": "USD",
  "side": "deposit",
  "receive_amount": 10000,
  "deliver_amount": 10000,
  "fee": 0,
  "issued_at": "<issued_at timestamp>",
  "expires_at": "<expires_at timestamp>"
}

Create the inter-account transfer via POST /api/transfers:

{
  "transfer_type": "inter_account",
  "quote_guid": "<insert quote_guid>",
  "source_account_guid": "<insert bank-level fiat or trading account_guid>",
  "destination_account_guid": "<insert invoice operations account_guid>"
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created transfer_guid>",
  "transfer_type": "inter_account",
  "bank_guid": "<associated bank_guid>",
  "quote_guid": "<inserted quote_guid>",
  "external_bank_account_guid": null,
  "asset": "USD",
  "side": "deposit",
  "state": "storing",
  "failure_code": null,
  "amount": 10000,
  "estimated_amount": 10000,
  "fee": 0,
  "source_account": {
    "type": "fiat",
    "guid": "<inserted bank-level fiat account_guid>",
    "bank_guid": "<associated bank_guid>"
  },
  "source_participants": null,
  "destination_account": {
    "type": "invoice_operations",
    "guid": "<insert invoice operations account_guid>",
    "bank_guid": "<associated bank_guid>"
  },
  "destination_participants": null,
  "labels": null
}

Poll GET /api/transfers/{transfer_guid} until state: "completed". Then verify the platform_available balance on the invoice operations account via GET /api/accounts/{account_guid}.

5. Create a Lightning Network payment transfer

Once the invoice operations account is funded, customers can pay Lightning Network invoices. See the Receive Lightning Payment guide for creating invoices.

For a customer with state: "verified" and a fiat or trading account, create a lightning_transfer quote via POST /api/quotes:

{
  "product_type": "lightning_transfer",
  "customer_guid": "<insert customer_guid>",
  "network_address": "<insert network_address>",
  "asset": "USD"
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created quote_guid>",
  "product_type": "lightning_transfer",
  "customer_guid": "<inserted customer_guid>",
  "asset": "USD",
  "side": "withdrawal",
  "receive_amount": 100,
  "deliver_amount": 100,
  "fee": 0,
  "issued_at": "<issued_at timestamp>",
  "expires_at": "<expires_at timestamp>",
  "network_fee_asset": "USD",
  "network_address": "<inserted network_address>"
}

ℹ️
Sandbox behavior
In sandbox banks, the receive_amount is randomly generated. Since Lightning Network channels are not created in sandbox, the network_address can be any string value.

Create the lightning transfer via POST /api/transfers:

{
  "transfer_type": "lightning",
  "customer_guid": "<inserted customer_guid>",
  "quote_guid": "<inserted quote_guid>",
  "network_fee_account_guid": "<inserted network_fee_account_guid>"
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created transfer_guid>",
  "transfer_type": "lightning",
  "customer_guid": "<inserted customer_guid>",
  "quote_guid": "<inserted quote_guid>",
  "external_bank_account_guid": null,
  "asset": "USD",
  "side": "withdrawal",
  "state": "storing",
  "failure_code": null,
  "amount": 100,
  "estimated_amount": 100,
  "fee": 0,
  "source_account": {
    "type": "fiat",
    "guid": "<inserted account_guid>",
    "customer_guid": "<inserted customer_guid>"
  },
  "source_participants": null,
  "destination_account": null,
  "destination_participants": null,
  "labels": null
}

ℹ️
Network fee assignment
The network_fee_account_guid controls who pays network fees. Use a bank-level account GUID for the partner to cover fees, or a customer-level account GUID for the customer to cover fees.

Poll GET /api/transfers/{transfer_guid} until state: "completed", then verify:

Invoice operations account — platform_available debited by transfer + network fee amounts.
Customer fiat account — platform_available debited by the transfer amount (and network fees if the customer's account was chosen to cover them).
Bank-level fiat account — platform_available credited by the transfer amount.

6. Top up the invoice operations account

Repeat step 4 to top up the invoice operations account as needed.