Payment Links

Payment Link is a secure method of receiving payment through a simple payment link URL. It allows you to provide an additional mode of accepting a payment that involves generating a payment link URL and then sharing it with the payer via various communication channels, such as email and QR code. When a payer clicks on the payment link URL, they are redirected to the payment page, where they can select the payment method to complete the transaction.

Key Benefits

The key benefits of the payment link are that it

  • simplifies the payment process
  • enhances the customer experience, and
  • enables faster payment.

Use a Payment Link

When payers receive a unique payment link URL for payment, they can click the link and complete the payment.

This diagram shows the different steps to complete a transaction using a payment link.

  • Enter the payment information, such as invoice number, total amount, and request to generate a payment link URL.
  • The gateway generates a unique link that you can share with payers.
  • When payers click the link, they are redirected to a Hosted Checkout page.
  • Payers enter the payment information on the Hosted Checkout page and complete the transaction.

Request an Initiate checkout operation


Prior to initiate a checkout operation, ensure that you have these attributes set for Payment Links:

  • currency: Currency Type
  • amount: The amount that must be paid using the Payment Link
  • description: A brief description of the Payment Link
  • expiryDateTime: Expiration date and time of Payment Link. Default is 3 months.
  • numberOfAllowedAttempts: The number of allowed attempts after which the payer will no longer be able to access the payment link. Default is 25.

Sample Request

To create a payment link URL, you must request an Initiate Checkout operation with the payment link mode. This is a sample snippet for the Initiate Checkout operation.

Sample Code to Initiate Checkout

      "apiOperation": "INITIATE_CHECKOUT",
      "checkoutMode": "PAYMENT_LINK",
      "interaction": {
          "operation": "AUTHORIZE",
          "merchant": {
              "name": "TESTHPP_TNSPAY",
      "order": {
          "currency": "USD",
          "amount": 1234,
          "id": "toby-test-z",
          "description": "Toby Test Order z"
      "paymentLink": {
          "expiryDateTime": "2021-12-10T02:16:00.993Z",
          "numberOfAllowedAttempts": "3"

A successful response to this operation contains the Payment Link URL and Payment Link ID parameters, which can be shared with the customer for making the payment.

Sample Response

Sample Response
      "checkoutMode": "PAYMENT_LINK",
      "merchant": "TESTHPP_TNSPAY",
      "paymentLink": {
          "expiryDateTime": "2021-12-10T02:16:00.993Z",
          "id": "PAYLINK0001060519617G19059484L2",
          "numberOfAllowedAttempts": 3,
      "result": "SUCCESS",
      "successIndicator": "c89f62baad174e12"

Sharing Payment Links

Merchant share the payment link with the payer through various communication channels, such as email and QR codes. The payer clicks the payment link that redirects them to the Hosted Checkout payment page in a browser and completes the transaction using one of the available payment methods.

Deleting Payment Links

The delete payment link operation allows you to explicitly delete or invalidate the payment link if the payer has already made the payment offline or if the payment is no longer necessary.

Sample Delete Payment Link Request

Delete Payment Link API Reference [REST][NVP]

The gateway automatically expires the session if:

  • the payment is not made within 3 months of the payment link's being generated, the payer will no longer be able to use the payment link to make the payment
  • the number of attempted payments exceeds 25, the payer will no longer be able to access the payment link to complete the transaction
  • the payment using a payment link has been completed, or
  • the merchant initiates the deletion request.

Test a Payment Link

After you have set up your account and built your integration, you should test the payment link using your test merchant profile (Your merchant ID begins with "TEST"). The Mastercard Payment Gateway provides a test-hosted checkout page to verify the payment link.

  1. Enter the payment details and request the payment link through the INITIATE_CHECKOUT operation. A Payment Link URL is returned when the INITIATE CHECKOUT operation is successful.
  2. Make the payment using the test card listed in the Card Transaction Test Details.

Webhook Notifications

It is recommended that you opt for the notification service to receive webhook notifications if the payment is successful. For additional information about webhook notifications and configuration, refer to Webhook Notifications.

Copyright © 2022 MasterCard