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, text message, 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
- enables faster payment, and
- allows you to follow up with a customer after a transaction fails or a shopping cart is abandoned.
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
Prerequisites
Before you initiate a checkout operation, ensure the following attributes are set for Payment Links:
- apiOperation: Set field value to INITIATE_CHECKOUT.
- checkoutMode: Set field value to PAYMENT_LINK.
- interaction.operation: Choose transaction type as AUTHORIZE or PURCHASE.
- interaction.merchant.name: The name of your business displayed to the payer in the checkout page.
- interaction.merchant.url: The URL of your business's website.
- order.amount: The total amount for the order. This is the net amount plus any surcharge.
- order.currency: The currency of the order.
- order.description: A short textual description of the contents of the order.
- paymentLink.errorUrl: The URL to which you want to redirect the payer's browser in the event of an error when invoking the payment link, such as an order already paid, a payment link expired, an invalid payment link, and so on.
If specified and an error occurs, the gateway will provide the error code (
errorCode) and description (errorDescription) as query string parameters. The gateway will also preserve any query string parameters you may have included in errorUrl.For example, if you specify paymentLink.errorUrl as https://merchant.com/myPaymentLinkErrorPage.html, in the event of an error, this errorUrl would receive the following query string parameters from the gateway: https://merchant.com/myPaymentLinkErrorPage.html?errorCode=ERROR_CODE&errorDescription=Error+message. See the Error Codes and Descriptions section for more information.
This field is optional. When this field is not specified, the payer, in the event of an error, will be redirected to the default error screen. - order.id: A unique identifier for this order to distinguish it from any other order you create.
- paymentLink.expiryDateTime: Expiration date and time of this Payment Link. Default is 3 months.
- paymentLink.numberOfAllowedAttempts: The number of allowed attempts after which the payer will no longer be able to pay using the Payment Link. Default is 25 attempts.
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.
{
"apiOperation": "INITIATE_CHECKOUT",
"checkoutMode": "PAYMENT_LINK",
"interaction": {
"operation": "AUTHORIZE",
"merchant": {
"name": "<your_merchant_name>",
"url": "<website_url>"
}
},
"order": {
"currency": "USD",
"amount": 1234,
"id": "<order_ID>",
"description": "Ordered goods"
},
"paymentLink": {
"expiryDateTime": "2021-12-10T02:16:00.993Z",
"numberOfAllowedAttempts": "3"
}
}
Initiate Checkout API Reference [REST][NVP]
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
{
"checkoutMode": "PAYMENT_LINK",
"merchant": "<your_merchant_id>",
"paymentLink": {
"expiryDateTime": "2021-12-10T02:16:00.993Z",
"id": "PAYLINK0001060519617G19059484L2",
"numberOfAllowedAttempts": 3,
"url": https://test-nbkpayment.mtf.gateway.mastercard.com/pbl/PAYLINK0001060519617G19059484L2
},
"result": "SUCCESS",
"successIndicator": "c89f62baad174e12"
}
Sharing payment links
The merchant shares the payment link with the payer through various communication channels, such as email, text message, 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.
| URL | https://test-nbkpayment.mtf.gateway.mastercard.com/api/rest/version/64/merchant/{merchantId}/link/{linkId} |
| HTTP Method | DELETE |
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 gateway provides a test-hosted checkout page to verify the payment link.
- 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.
- 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.
Error Codes and Descriptions
This table describes the list of error codes with descriptions.
| Error Code | Description |
|---|---|
| EXPIRED | The payment link has expired. Please contact the payment requestor. |
| PAID | The order associated with this payment link has been paid. Please contact the payment requestor |
| USAGE_COUNT_EXCEEDED | The maximum permitted attempts have exceeded. Please contact the payment requestor |
| DOES_NOT_EXIST | This payment link is invalid. Please contact the payment requestor |
| UNEXPECTED_ERROR | An unexpected error has occurred. Please contact the payment requestor |
| DELETED | This payment link was deleted. Please contact the payment requestor |