Now that we've created a product and price, and pointed that price to our product, we have almost everything that we need to get started selling to customers. The final step will be to connect our product (and its price) with a payment method — a paymentLink.

A payment link is a way to sell goods and services, either one-time or recurring.

Payment links are typically in the form of a checkout page, but Sphere gives you the flexibility to embed the backend logic of a payment link inside of anything: like a button on your website. The payment link object will respond with a URL if you would like to leverage our prebuilt checkout. However, you always have the option to build your own frontend experience by using our React SDK, or by directly making a request to the API to obtain the necessary transaction details to build the transaction yourself and present to your users.

The last thing worth noting before we dive into the object itself: like Stripe, the way that you connect your product with a paymentLink is to pass it in its price as a lineItem in the lineItems field.

What is a line item?

A lineItem is a simple object with three fields to connect your product and price to a payment method.

price: string The id of the price (and the product it points to) to connect.
quantity: number Indicates how many of each product is being sold in the payment link.
quantityMutable: boolean Defines whether your users are allowed to select the quantity. If set to true, the quantity you define will be the default — but ultimately your users can adjust and select.

The payment link object

Let's take a look at a full paymentLink object:

{
  "id": "paymentLink_7750cfca68b54b498178ab5726c24ba4",
  "active": "true",
  "created": "2021-01-01T00:00:00.000Z",
  "description": "An example Payment Link for receiving payments.",
  "end": "2021-01-01T00:00:00.000Z",
  "failUrl": "https://spherepay.co",
  "features": {
    "requiresName": true,
    "requiresEmail": true,
    "requiresShippingDetails": true,
    "requiresTwitter": false,
    "requiresDiscord": false,
    "requiresTelegram": false
  },
  "lineItems": [
    {
      "price": "lineItem_2319f07318fb411dbd661dbb048d37b3",
      "quantity": 3
    },
    {
      "price": "lineItem_bda65fa8e59147ddb3b7c80c5d38bcff",
      "quantity": 5,
      "quantityMutable": true
    }
  ],
  "meta": {
    "uuid": "<your_uuid>"
  },
  "name": "Example Payment Link",
  "start": "2021-01-01T00:00:00.000Z",
  "successUrl": "https://spherepay.co",
  "updated": "2021-01-01T00:00:00.000Z",
  "url": "https://spherepay.co/pay/paymentLink/paymentLink_5adff9ed297d45e7bf6438f9527b77f4"
}

id: string Unique identifier for the object. Auto-generated by Sphere upon creation.

active: boolean Denotes whether your payment link can process payments.

If set to inactive, then attempts to pay through the payment link will fail.

created string datetime for when the payment link was created.

description: Describes your payment link. Hidden from customers. Max length (500).

end: string datetime that defines when the payment link becomes inactive and unpayable.

failURL: string The URL that your customers will be redirected to upon failed payment.

features: object Defines which personalInfo elements you'd like to collect about your customer.

lineItems: lineItem[] A critical list of objects that define which products (and their chosen prices) are being sold in the payment link, including their default quantities. lineItems is the field which provides the fundamental connection between your product, price, and selected payment method.

lineItem: object Describes the items being sold in a payment method. Has three elements:
- (1) price: string The id of the price (and implicitly, the product that it points to).
- (2) quantity: number Defines the default amount of a given product being bought.
- (3) quantityMutable: boolean Determines if customers can adjust the default quantity.
  - If the customer changes the default quantity during checkout, and you are using Sphere's pre-built checkout page, then our backend automatically recognizes the change and will update the payment object that is created when processing the customer's payment.
  - If you are building your own frontend, you will need to pass the updated quantity to Sphere. This can be sent via the setLineItemQuantity() hook in the React SDK or directly via API.

meta: object Set of key-value pairs (JSON) for arbitrary usage. Used to save structured information about the object to reference elsewhere. Think of it as general purpose storage space.

name: string Name of your payment link. Hidden from users. Max length (500).

start: string datetime for when your payment link becomes payable.

successURL string The URL that your users will be redirected to upon successful payment.

updated: string datetime for when the payment link was last updated.

url: string The URL for a Sphere-hosted prebuilt checkout page for your payment link.

Can be passed to your customers for them to pay for your products.
If you would prefer to build your own frontend, use the React SDK or API directly.