Payments

A payment guides you through the process of collecting funds from your customer. To receive funds, you must first create a payment object with details such as the amount, currency, payment_methods, and target currency. The payment object essentially consists of a payment payload that can be converted into a QR code. You can see this implemented on the Speed payment page. Your customers transfer funds, on-chain or on the lightning network by scanning this payment payload (QR code). To ensure that you can receive both on-chain and lightning payments, remember to keep the “BTC On-chain” payment method enabled from the payment methods in Speed web application.

You can retrieve individual payments as well as list them all. See more about this here. Payments are identified by a unique ID prefixed with the letters pi. An example of a payment ID is pi_l7sygu3xYQukjvzS.

Let's look at the payment status and life cycle.

Throughout its lifetime, payment transitions through multiple statuses; initially, the status is unpaid. When any amount of funds are received (i.e. it can also be a partial payment), it changes to paid. The payment object is marked "expired” if the time frame (TTL) expires. You may cancel a payment at any point before it is either paid or expired.

status string
A payment object can have four statuses, as mentioned below.

    unpaid
It has unpaid status after its generation until it is paid or expired.
paid
It is marked paid once any amount of funds are received within the time frame (TTL).
expired
When the stipulated time frame (TTL), then the payment is marked as expired.
cancelled
When you don’t require any payment and it’s unpaid, you can cancel it before the stipulated time frame (TTL).

How payment objects work

Creating a payment object

With every customer’s checkout session, a payment object is created. As a result, a payment object is always created automatically from a checkout link/checkout session/payment link. Additionally, you can create a payment object directly through the payments APIs.

In conclusion, payment objects are created in the following ways:

1. Checkout Link (APIs/Speed web application)
2. Payment Link (APIs/Speed web application)
3. Checkout session (APIs/Speed.js)
4. Payment APIs

Retrieve a payment object

Through the payments APIs or the Speed web application, you can view a list of all payment objects associated with checkouts/payment links/checkout sessions. To obtain all the data associated with a payment object, you must use the payment APIs.

Updating a payment object

You can also update a payment at any point. The payment's metadata and description can be updated.

Cancelling a payment object

You can cancel a payment in multiple ways, just like you can create a payment in various ways. If you want to cancel a payment, you must do so before it is paid or expires.

As of now, you can cancel a payment object associated with the checkout link or payment link by deactivating the link through APIs or Speed web application. You can also cancel a payment associated with a checkout session through the checkout session APIs.