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).

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:

Checkout Link (APIs/Speed web application)
Payment Link (APIs/Speed web application)
Checkout session (APIs/Speed.js)
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.

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. To cancel payment through payments APIs, check this out.