Skip to main content

Manage payment links

Payment links eliminate the need for your consumer to visit your online store by redirecting the consumer to your payment page when they click on the link. You can create and manage your payment links via the Checkout API.

In this guide, you will learn how to:

  • Create a payment link for a product
  • Update a payment link
  • Retrieve a payment link
  • Retrieve all payment links created

Before you begin

To create a payment link that you can share with your consumers, you need an existing product to associate with that payment link. Learn how to create a product.

Create a payment link for a product by performing a POST call to the /product-links endpoint using the following fields in your request payload.

Required and optional fields for creating a payment link
Field Data Type Description Required (R) or Optional (O)
merchantOrderNumber string A unique identifier assigned by you or on behalf of you for the intention to purchase goods and/or services. O
items array object The items for the payment link. R
items.product object The product information used on the linked item. O
items.product.productId string A unique identifier assigned by you for a product or service. O
items.product.name string The label given to a product or service offered for sale. R
items.product.sku string A scannable alphanumeric code generated by you, known as Stock Keeping Unit (SKU). O
items.product.description string The short description of the product or service offered. O
items.quantity number <double> The volume (quantity) of each individual product type included in the transaction. O
items.unitPrice integer <int64> The monetary value of the per-item cost of a good or service. O
expirationTimestamp string <date-time> The hour, minute, and second on a specific day when the payment link will expire. The status will be changed to EXPIRED afterwards O
name string The descriptive name for the payment link. O
description string The short description of the payment link. O
totalTransactionAmount integer <int64> The total amount the consumer will pay for this link. R
currencyCode string Three letter code based on the ISO-4217 Currency Codes standard. R
consumer object Profile information of the consumer. O
checkoutOptions object Checkout option information for the payment link. O

The following is a sample request to create a new payment link for a product.

HTTP method: POST
Endpoint: /payment-links

Json
{
    "merchantOrderNumber": "123456",
    "items": [
        {
            "product": {
                "productId": "GHIJ1234KLMN",
                "name": "Dummy Product",
                "sku": "ABC123DEF",
                "description": "This is a dummy product description"
            },
            "quantity": 2,
            "unitPrice": 2000
        }
    ],
    "expirationDays": "10",
    "name": "New Link Name",
    "description": "This is description for the new link",
    "totalTransactionAmount": 5000,
    "currencyCode": "USD"
}

Response:

Json
{
    "linkId": "OPQR9876STUV",
    "merchantOrderNumber": "123456",
    "items": [
        {
            "product": {
                "productId": "GHIJ1234KLMN",
                "name": "Dummy Product",
                "sku": "ABC123DEF",
                "description": "This is a dummy product description"
            },
            "quantity": 2,
            "unitPrice": 2000
        }
    ],
    "status": "LINK_STATUS_ACTIVE",
    "url": "samplepaybylinkURL.com/paysample",
    "expirationDays": "10",
    "name": "New Link Name",
    "description": "This is description for the new link",
    "totalTransactionAmount": 5000,
    "currencyCode": "USD"
}

If you need to de-activate an existing payment link, you can update the status of the payment link from LINK_STATUS_ACTIVE to LINK_STATUS_INACTIVE.

Perform the following to steps to update a payment link:

  1. Send a PATCH call to the /payment-links endpoint.
  2. Use the linkId of the payment link you want to retrieve as a path parameter.
  3. Send status=LINK_STATUS_INACTIVE as the query parameter.

The following is a sample response to update the status of a payment link from ACTIVE to INACTIVE.

HTTP method: PATCH
Endpoint: /payment-links/OPQR9876STUV?status=LINK_STATUS_INACTIVE

Response:

Perform the following steps to retrieve a single payment link:

  1. Send a GET call to the /payment-links endpoint.
  2. Use the linkId of the payment link you want to retrieve as the path parameter.

The following is a sample request to retrieve a payment link.

HTTP method: GET
Endpoint: /payment-links/OPQR9876STUV

Perform the following steps to retrieve all payment links created:

  1. Send a GET call to the /payment-links endpoint.
  2. Use pageSize as a query parameter to control the number of pages you want.

The following is a sample request to retrieve all created payment links.

HTTP method: GET
Endpoint: /payment-links?pageSize=10