Receive Payment

Availability

👍

To enable in the production environment, please contact the partner success team.

Overview

The Cybrid Platform supports receiving payment in either USD or BTC.

For this guide, we'll use the following terminology:

• The Cybrid partner's customer will be referred to as the "payee".
• The payee's end-consumer will be referred to as the "payer".

To receive a Bitcoin Lightning Network payment in either USD or BTC, there are three steps on the Cybrid Platform:

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

1. Creating an invoice

For a customer (i.e. payee) that is "state":"verified", and for whom a USD fiat account has been created on the Cybrid Platform, you may create an invoice via the POST /api/invoices endpoint.

An example POST /api/invoices request body is below:

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

By specifying "asset":"USD" this will automatically associate the invoice to the payee's fiat account on the Cybrid Platform, and this associated fiat account GUID will be returned in the response. When the invoice is eventually paid, the USD will be deposited to this associated payee fiat account.

Alternatively, by specifying "asset":"BTC"the customer's associated BTC trading account will receive a deposit when the invoice is paid.

When executed, the following response body will be returned:

{
  "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
}

The invoice will begin in "state":"storing", and automatically progress to "state":"unpaid".

The invoice does not expire, and will remain in "state":"unpaid" indefinitely until either paid or cancelled.

Invoice fees

Similar to trade fees, partners may choose to configure invoice fees that will be calculated at the time of invoice creation, and also included in payment instructions. These optional invoice fees are configured by the Cybrid team at the bank-level and would be applied to all invoices for all payees.

2. Creating payment instructions

Once the invoice has been created, you may then create payment instructions via the POST /api/payment_instructions endpoint.

An example POST /api/payment_instructions request body is below:

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

When executed, the following response body will be returned:

{
  "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 instructions will begin in "state":"storing", and automatically progress next to "state":"created".

Using the GET /api/payment_instructions/{payment_instruction_guid} endpoint, the following response will be returned:

{
  "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
}

The Bitcoin Lightning Network invoice address (i.e. "network_address") will be returned in the GET response.

👍

Note: In sandbox banks, the returned "network_address" will be "sandbox_network_address".

The payment instructions for invoices with "asset":"USD" will expire in 1 minute, and the payment instructions will progress to "state":"expired" based on expired_at. BTC invoices will expire in 1 hour.

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

3. Wait for the invoice to progress to state paid

While the payee will receive either USD or BTC, depending on the asset the invoice was created with, the payer will always pay in BTC via the Bitcoin Lightning Network.

The Cybrid Platform automatically converts the BTC to USD when invoices are created in USD.

When the payer sends a Bitcoin Lightning Network transfer to the network_address in the payment instructions:

• The Cybrid Platform will be notified that the transfer has been received.
• The invoice will progress to "state":"settling".
• The customer (i.e. payee) platform_balance will reflect the invoice amount; however, the platform_available will not reflect this amount until settlement is complete.
• The payment instructions will progress to "state":"expired".

When the settlement of the invoice is complete:

• The invoice will progress to "state":"paid".
• The customer (i.e. payee) platform_available will reflect the invoice amount.
• More information about Bitcoin Lightning Network settlement process and schedules here.

👍

When testing payment instruction, use the "expected_behaviour":"invoice_paid_immediately" to simulate invoice "state":"paid".