Receive Lightning Payment

Availability

ℹ️

Production access

To enable Lightning Network in production, contact the partner success team.

Overview

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

Terminology:

• Payee — the Cybrid partner's customer receiving payment.
• Payer — the payee's end-consumer sending payment.

Receiving a payment requires three steps:

1. Create an invoice.
2. Create a payment instruction.
3. Wait for the invoice to reach state: "paid".

1. Create an invoice

For a customer (payee) with state: "verified" and a USD fiat account, create an invoice via POST /api/invoices:

{
  "asset": "USD",
  "customer_guid": "<insert customer_guid>",
  "receive_amount": 100
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created invoice_guid>",
  "customer_guid": "<inserted customer_guid>",
  "account_guid": "<associated account_guid>",
  "type": "lightning",
  "asset": "USD",
  "receive_amount": 100,
  "deliver_amount": 100,
  "fee": 0,
  "state": "storing",
  "labels": null
}

Setting "asset": "USD" associates the invoice with the payee's fiat account. When paid, USD deposits to that account. Alternatively, set "asset": "BTC" to deposit to the customer's BTC trading account.

The invoice begins in state: "storing" and progresses to state: "unpaid". Invoices do not expire and remain state: "unpaid" until paid or cancelled.

Invoice fees

Partners can configure invoice fees at the bank level. Fees are calculated at invoice creation and included in payment instructions. Contact the Cybrid team to configure invoice fees.

2. Create payment instructions

Once the invoice exists, create payment instructions via POST /api/payment_instructions:

{
  "invoice_guid": "<insert invoice_guid>"
}

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created payment instruction GUID>",
  "customer_guid": "<inserted customer_guid>",
  "invoice_guid": "<inserted invoice_guid>",
  "network_address": null,
  "expected_payment_asset": null,
  "expected_payment_amount": 0,
  "state": "storing",
  "expired_at": null,
  "failed_at": null,
  "failure_code": null
}

The payment instruction begins in state: "storing" and progresses to state: "created".

Poll GET /api/payment_instructions/{payment_instruction_guid} to retrieve the network_address:

{
  "created_at": "<created_at timestamp>",
  "updated_at": "<updated_at timestamp>",
  "guid": "<created payment_instruction_guid>",
  "customer_guid": "<inserted customer_guid>",
  "invoice_guid": "<inserted invoice_guid>",
  "network_address": "<created Lightning Network invoice address>",
  "expected_payment_asset": "USD",
  "expected_payment_amount": 100,
  "state": "created",
  "expired_at": "<updated_at timestamp>",
  "failed_at": null,
  "failure_code": null
}

ℹ️

Sandbox behavior

In sandbox banks, the returned network_address is sandbox_network_address.

Payment instructions for USD invoices expire in 1 minute. BTC invoices expire in 1 hour. After expiry, the payment instruction progresses to state: "expired".

Partners can display payment instructions to the payer in QR code format.

3. Wait for the invoice to reach paid

The payer always pays in BTC via the Lightning Network. For USD invoices, the platform automatically converts BTC to USD.

When the payer sends payment to the network_address:

• The platform receives the transfer notification.
• The invoice progresses to state: "settling".
• The payee's platform_balance reflects the invoice amount, but platform_available does not update until settlement completes.
• The payment instruction progresses to state: "expired".

When settlement completes:

• The invoice progresses to state: "paid".
• The payee's platform_available reflects the invoice amount.
• See Settlement Process for schedules.

ℹ️

Testing tip

When testing, use expected_behaviour: "invoice_paid_immediately" to simulate state: "paid".