Payment Links | ArcBlock

A Payment Link is a shareable, reusable page to sell a product or service. You can create a link for a specific set of products and prices and share it with multiple customers through various channels. This allows for quick and easy payment collection without building a full checkout flow.

The Payment Link Object

A Payment Link object contains all the information necessary to present a payment page to a customer. Here are some of its key attributes:

Attribute	Type	Description
`id`	string	Unique identifier for the payment link object.
`url`	string	The URL for the payment page. Customers can be redirected to this URL to make a payment.
`active`	boolean	Whether the payment link is currently active and can be used for payments.
`line_items`	array	The list of products and prices that will be purchased.
`after_completion`	object	Behavior after the purchase is complete, such as redirecting to a URL or showing a confirmation message.
`allow_promotion_codes`	boolean	Enables the use of promotion codes on the payment page.
`currency_id`	string	The three-letter ISO currency code.
`metadata`	object	A set of key-value pairs that you can attach to the object. Useful for storing additional information.
`created_at`	string	Timestamp of when the object was created.

Create a Payment Link

Creates a new payment link.

Create a Payment Link

const paymentLink = await payment.paymentLinks.create({
  line_items: [
    {
      price_id: 'price_xxxxxxxxxxxxxx',
      quantity: 1,
      adjustable_quantity: {
        enabled: true,
        minimum: 1,
        maximum: 10,
      },
    },
  ],
  after_completion: {
    type: 'hosted_confirmation',
    hosted_confirmation: {
      custom_message: 'Thanks for your purchase!',
    },
  },
  metadata: {
    order_id: '6735',
  },
});

Parameters

Name	Type	Description
`line_items`	array	Required. A list of line item objects, each representing a product to be purchased. See details below.
`name`	string	An optional internal name for the payment link.
`lookup_key`	string	An optional, unique string that can be used to retrieve the payment link.
`currency_id`	string	The ID of the currency for this payment link. If not provided, the default currency is used.
`after_completion`	object	Specifies the behavior after a successful payment. See details below.
`allow_promotion_codes`	boolean	Set to `true` to allow promotion codes to be redeemed. Defaults to `false`.
`consent_collection`	object	Configures consent collection for promotions and terms of service. See details below.
`nft_mint_settings`	object	Settings for minting an NFT after the payment is complete. See details below.
`metadata`	object	A set of key-value pairs to store additional information.

line_items Object Properties

Name	Type	Description
`price_id`	string	Required. The ID of the price object.
`quantity`	number	Required. The quantity of the product being purchased. Must be at least 1.
`adjustable_quantity`	object	Configuration that allows the customer to adjust the quantity of this line item on the payment page. See details below.

line_items.adjustable_quantity Object Properties

Name	Type	Description
`enabled`	boolean	Required. Set to `true` to allow quantity adjustments.
`minimum`	number	The minimum quantity the customer can select. Must be 0 or greater.
`maximum`	number	The maximum quantity the customer can select. Must be greater than `minimum`.

after_completion Object Properties

Name	Type	Description
`type`	string	Required. The type of completion behavior. Can be `hosted_confirmation` or `redirect`.
`hosted_confirmation`	object	Displays a hosted confirmation message to the customer. Used when `type` is `hosted_confirmation`.
`redirect`	object	Redirects the customer to a specific URL. Used when `type` is `redirect`.

after_completion.hosted_confirmation Object Properties

Name	Type	Description
`custom_message`	string	An optional custom message to display to the customer. Max 200 characters.

after_completion.redirect Object Properties

Name	Type	Description
`url`	string	The URL to redirect the customer to. Max 2048 characters.

consent_collection Object Properties

Name	Type	Description
`promotions`	string	Determines how to handle consent for promotional communications. Can be `none`, `opt_in`, or `opt_out`.
`terms_of_service`	string	Determines how to handle consent for terms of service. Can be `none`, `opt_in`, or `opt_out`.

nft_mint_settings Object Properties

Name	Type	Description
`enabled`	boolean	Required. Set to `true` to enable NFT minting after payment.
`factory`	string	The factory address for minting the NFT. Required if `enabled` is `true`.

Returns

Returns a TPaymentLinkExpanded object if the creation is successful.

Response

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "adjustable_quantity": {
        "enabled": true,
        "minimum": 1,
        "maximum": 10
      }
    }
  ],
  "after_completion": {
    "type": "hosted_confirmation",
    "hosted_confirmation": {
      "custom_message": "Thanks for your purchase!"
    }
  },
  "metadata": {
    "order_id": "6735"
  }
}

Retrieve a Payment Link

Retrieves the details of an existing payment link.

Retrieve a Payment Link

const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const paymentLink = await payment.paymentLinks.retrieve(paymentLinkId);

Parameters

Name	Type	Description
`id`	string	Required. The unique identifier or `lookup_key` of the payment link to retrieve.

Returns

Returns a TPaymentLinkExpanded object, which includes expanded details about the line items and their associated prices and products.

Response

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": true,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1,
      "price": {
        "id": "price_xxxxxxxxxxxxxx",
        "product_id": "prod_yyyyyyyyyyyyyy",
        "unit_amount": "10.00",
        "product": {
          "id": "prod_yyyyyyyyyyyyyy",
          "name": "My Awesome Product"
        }
      }
    }
  ]
}

Update a Payment Link

Updates a payment link by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that you cannot update an archived payment link.

Update a Payment Link

const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const updatedPaymentLink = await payment.paymentLinks.update(paymentLinkId, {
  active: false,
  metadata: {
    order_id: '6735-updated'
  }
});

Parameters

Name	Type	Description
`id`	string	Required. The ID of the payment link to update.
`...`		The second argument is an object containing the fields to update. It supports many of the same parameters as the create method, such as `active`, `line_items`, `metadata`, and `after_completion`. All fields are optional.

Returns

Returns the updated TPaymentLink object.

Response

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "metadata": {
    "order_id": "6735-updated"
  }
}

List all Payment Links

Returns a list of your payment links.

List Payment Links

const paymentLinks = await payment.paymentLinks.list({
  active: true,
  limit: 5
});

Parameters

Name	Type	Description
`active`	boolean	Filters the list to only include active or inactive payment links.
`donation`	string	Set to `'hide'` to exclude payment links where `submit_type` is `donate`.
`page`	number	The page number for pagination. Defaults to `1`.
`pageSize`	number	The number of objects to return per page. Defaults to `20`.
`order`	string	The order to sort the results by. For example, `'created_at:DESC'`.

Returns

Returns a paginated object containing a list of TPaymentLinkExpanded objects.

Response

{
  "count": 15,
  "list": [
    {
      "id": "plink_xxxxxxxxxxxxxx",
      "active": true
    },
    {
      "id": "plink_yyyyyyyyyyyyyy",
      "active": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

Archive a Payment Link

Deactivates a payment link, making it unusable for payments. This action is reversible by updating the active attribute to true.

Archive a Payment Link

const paymentLinkId = 'plink_xxxxxxxxxxxxxx';
const archivedPaymentLink = await payment.paymentLinks.archive(paymentLinkId);

Parameters

Name	Type	Description
`id`	string	Required. The ID of the payment link to archive.

Returns

Returns the archived TPaymentLink object with its active property set to false.

Response

{
  "id": "plink_xxxxxxxxxxxxxx",
  "active": false,
  "url": "https://payment.arcblock.io/pl/plink_xxxxxxxxxxxxxx"
}