Create a payment link using the Checkout API

Overview

Pay by Link is a simple way to accept payments online without the need for a website or app. You can create a payment link using the OnlinePay Dashboard, or the Checkout API and send it to your customer. The customer can then visit the pay by link hosted page to complete the payment. This ensures payments are protected by the same security measures as a standard payment page, including 3D Secure and PCI compliance.

Payment links include the same features as a Hosted Payment Page and can be configured with the same optional parameters to customise the look and feel of the payment page shown to the customer. This includes adding your pre-defined theme, payment confirmation page, and line items. Payment options are based on the payment methods you have configured in your Payment Provider Contract.

Payment links are ideal for:

collecting payments from customers while you are still building your website or app.
sending invoices to customers via email or SMS.
accepting payments over the phone or email, such as hotel or restaurant bookings.

ℹ️
By default, payment links created using the API expire after 15 minutes. You can set the expiry time up to a maximum of 30 days by including the expiry_time parameter in the request. The expiry time is set in UTC format.
UTC time stands for Coordinated Universal Time, which is the time standard used worldwide.

Payment links can be created by users with Merchant Cashier or Merchant Supervisor roles. See User roles and permissions for more information on user roles and permissions.

Create a payment link using the Checkout API

To create a payment link using the Checkout API, use the same /checkout endpoint as you would to create a Hosted Payment Page or iFrame. The difference is in setting the interaction_type parameter to PAYMENT_LINK.

The POST request to /checkout returns a URL that you can send to your customer. The customer can then visit the pay by link hosted page to complete the payment.

The following example shows how to create a basic payment link using the Checkout API:

{
    "entity_id": "{{entityId}}",
    "currency_code": "AUD",
    "amount": 20,
    "customer": "{{customerId}}",
    "merchant_reference": "Shirt sale",
    "interaction_type": "PAYMENT_LINK",
    "configurations": {
        "card": {
          "payment_contract_id": "{{paymentContract}}",
          "threed_secure": {
            "threeds_contract_id": "{{3dsContract}}",
            "enabled": true
          }
        },
        "google_pay": {
            "card": {
                "threed_secure": {
                    "threeds_contract_id": "{{3dsContract}}"
                },
                "sca_compliance_level": "WALLET",
                "payment_contract_id": "{{paymentContract}}"
            }
        },
        "apple_pay": {
            "capture_now": false,
            "card": {
                "sca_compliance_level": "NONE",
                "payment_contract_id": "{{paymentContract}}"
            }
        }
    }
}

This returns a 200 OK response with a JSON object containing the payment link URL. The following example shows the response:

{
    "id": "cb7cxxxx-xxxx-xxxx-xxxx-xxxxxx424641",
    "url": "https://prod-au.checkout.verifone.cloud/v2/checkout/cb7cxxxx-xxxx-xxxx-xxxx-xxxxxx424641/view",
    "details": {}
}

This payment link URL can be sent to your customer via email, SMS, included on an invoice, or any other method and will only be valid for 15 minutes by default. The customer can then visit the payment link hosted page to complete the payment.

The id field in the response is the unique identifier for the payment link. You can use this ID to track the payment link and its status in your dashboard or via the API.

Create a payment link with optional parameters

Optional parameters allow you to provide additional information to your customer or use a theme for your checkout experience that matches your brand. The following example shows how to create a payment link that includes the following optional parameters:

merchant_reference: A unique reference for the payment link. This can be used to track the payment link and its status in your dashboard or via the API.
customer_id: The ID of the customer. This is used to identify the customer in your system if they have been created in your system.
expiry_time: The time at which the payment link expires. This is set in UTC format and can be set to a maximum of 30 days.
theme_id: The ID of the theme to use for the payment link. This allows you to customise the look and feel of the payment page shown to the customer.
line_items: A list of line items to include in the payment link. This allows you to provide additional information about the items being purchased, such as the name, quantity, and price. This can be used to create a more detailed invoice for your customer.
customer_details: Information about the customer, such as their name, email address, and phone number. This can be used where a customer has not been created in your system and you want to collect this information from the customer at the time of payment, or to provide an alternative billing address for the payment link.
Field values are replaced with variables or placeholder data.

{
    "entity_id": "{{entityId}}",
    "currency_code": "AUD",
    "amount": 1400,
    "merchant_reference": "Shirt sale",
    "customer": "{{customerId}}",
    "interaction_type": "PAYMENT_LINK",
    "expiry_time": "2025-05-30T07:00:00.000Z",
    "theme_id": "098ff91c-c346-4e1a-8da8-4624b3ed272a",
    "line_items": [
            {
                "quantity": 1,
                "name": "Red Shirt",
                "unit_price": 200,
                "total_amount": 200
            },
            {
                "quantity": 2,
                "name": "Blue Shirt",
                "total_amount": 1200,
                "unit_price_tax": 600
            }
        ],
    "customer_details": {
        "entity_id": "{{entityId}}",
        "billing": {
            "address_1": "1 Test Street",
            "city": "Sydney",
            "country_code": "AU",
            "first_name": "Jim",
            "last_name": "Smith",
            "phone": "0400000000",
            "postal_code": "2000",
            "state": "NSW"
        },
        "email_address": "[email protected]",
        "phone_number": "0400000000"
        },
    "configurations": {
        "card": {
          "payment_contract_id": "{{paymentContract}}",
          "threed_secure": {
            "threeds_contract_id": "{{3dsContract}}",
            "enabled": true
          }
        },
        "google_pay": {
            "card": {
                "threed_secure": {
                    "threeds_contract_id": "{{3dsContract}}"
                },
                "sca_compliance_level": "WALLET",
                "payment_contract_id": "{{paymentContract}}"
            }
        },
        "apple_pay": {
            "capture_now": false,
            "card": {
                "sca_compliance_level": "NONE",
                "payment_contract_id": "{{paymentContract}}"
            }
        }
    }
}

The response includes the payment link URL, which can be sent to your customer via email, SMS, or any other method. The customer can then visit the payment link hosted page to complete the payment and a customer_id field, which is the unique identifier for the customer. You can use this ID to track the customer and their payment link in your dashboard or via the API.