Receive Payment (beta)

Availability

This feature is currently in beta and available to all partners in the sandbox environment.

👍

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

Overview

The Cybrid Platform will eventually support receiving payment in either USD or BTC; however, only USD is currently supported. This guide currently describes receiving payment in USD only.

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 USD, 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.

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": "<provided 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": "<provided customer GUID>",
  "invoice_guid": "<provided 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": "<provided customer GUID>",
  "invoice_guid": "<provided invoice GUID>",
  "network_address": "<created Llightning 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.

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.

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 always receive USD, the payer will always pay in BTC via the Bitcoin Lightning Network. The Cybrid Platform automatically converts the BTC to 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".