Payment Links enable merchants to accept payments through a secure, hosted checkout page, without requiring a full website or checkout integration. They can be shared as standalone URLs or embedded directly into a merchant’s website, offering a fast and flexible way to collect payments.

A Payment Link is a hosted payment form generated through PCE. When a customer opens the link, they can enter payment details and complete the transaction securely. Links can be configured with branding, preset amounts, custom fields, and redirect URLs to fit the merchant’s workflow.

Payment Links are not meant to replace full e-commerce checkout solutions.

Key features:

Secure Checkout: All transactions use PCE’s PCI-compliant infrastructure.
Configurable: Add custom fields, brand elements, and preset amounts.
Flexible Delivery: Share the link directly or embed it as an HTML form.
Amount Control: Lock or restrict payment amounts using min/max values.

It is recommended that clients set up their webhook service to receive real-time updates as soon as a customer completes a payment via a payment link.

How it works

a. Add Custom Fields (Optional)

Use the POST /checkout/v3/paymentproperty?merchantId={merchantId}&echo=true API endpoint to create Custom Fields.

Parameter	Required	Description
`name`	✅	Unique identifier for the custom field. This label appears on the Payment Link form (e.g., invoice, PO Number, Customer Reference).
`fieldDataType`		Defines the type of data the field will accept. Common types include `Text`, `Number`, `Boolean` ,`List`, or `Decimal`.
`required`		Indicates whether the customer must fill this field before submitting the payment. Set to `true` for mandatory fields and `false` for optional fields.

For every custom field, it is critical to store the unqiue id . Use this for retrieving or updating the field details.
You can fetch the details of a Custom Field using the GET /checkout/v3/paymentproperty/{paymentPropertyId}?merchantId={merchantId} API endpoint.
You can also fetch all the Custom Fields created for a merchant using the GET /checkout/v3/paymentproperty?merchantId={merchantId} API endpoint.

b. Create a Payment Link

Use the POST /checkout/v3/device?echo=true API endpoint to create Payment Links. This link represents the hosted checkout page customers will use to submit their payment.

Parameter	Required	Description
`name`	✅	Unique name used to identify the Payment Link.
`merchantId`	✅	Unique merchant identifier for whom the link is created.
`deviceType`		Must be `Link2Pay` for Payment Links.
`enabled`		Activates or deactivates the Payment Link.
`onSuccessUrl`		Redirect URL for successful transactions.
`onFailureUrl`		Redirect URL for failed or cancelled transactions.
`MinPaymentAmount`		Minimum allowed payment amount the customer can enter.
`MaxPaymentAmount`		Maximum allowed payment amount the customer can enter.

This API call creates a Link2Pay payment form with configuration details such as link name, merchant ID, status, and redirects.
You can also add any additional inputs on the payment page, such as PO Number, Customer Reference, or internal tracking fields. These fields are called the Custom Fields and they must be created before they can be attached within a Payment Link.
For every enabled Payment Link, it is critical to store the unqiue id of the Payment Link. Use this for retrieving or updating the payment link.
You can fetch details of the Payment link via GET /checkout/v3/device?id={paymentLinkId} API endpoint.
You can also fetch all Payment links created for a merchant via GET /checkout/v3/device?merchantId={merchantId} API endpoint.

c. Share Payment Link with Customer

Once the payment link is created, the API response will return a paymentLinkId. Use this id to construct the final payment URL using the following format:

<base-url>/mxcustomer/d/{paymentLinkId}/v3

Replace {paymentLinkId} with the actual value returned in the API response before sharing the link with your customer.

d. Customer Makes Payment

The customer can access the shared link and complete the payment through the hosted checkout page. Upon successful payment:

A vaulted card and customer object are automatically created in the system.
The customer is redirected to the return URL (if configured).

You can then extract the Transaction ID from the URL’s query parameters.

Customize your Link

The following table shows all of the additional fields that can be added by changing the URL, so you can capture all the information you need when customers pay through your Payment Link page. This is done by adding a query parameter at the end of the URL and an ampersand between each of the parameters. All of are following parameters are optional.

You can pass any of the below optional query parameters to pre‑fill or customize fields in the payment form.

Query Parameter	Values	Description
Address	Street address	Populates billing address line 1.
AllowPartial	1 or 0	Enables partial payments if set to 1.
Amt	Numeric float	Amount due for the transaction.
City	City	Populates billing city.
Memo	Text or JSON object	Invoice memo or custom metadata payload.
CustomerName	Text	Billing contact name.
CustomerId	PCE customer ID	Links the payment to an existing customer record.
InvoiceNumber	Alphanumeric	Invoice reference or transaction identifier.
Email	Email address	Billing email address.
hideRequired	1 or 0	Hides the “Required” label on the payment page.
Lang	en / es	Sets display language (English or Spanish).
ShowMemo	1 or 0	Displays a memo field on the payment page.
Phone	Number	Billing phone number.
Cell	Number	Mobile phone number.
PONumber	Alphanumeric	Purchase order reference.
showHeader	1 or 0	Displays merchant information at the top of the page.
showOrder	1 or 0	Displays order information or device name.
State	Two Character Abbreviation	Populates billing state.
Zip	5‑digit number	Populates billing ZIP/postal code.

Update: clientData is deprecated. Use Memo (supports JSON payloads) and/or InvoiceNumber for custom metadata and reconciliation.

Payment Link Settings

Payment Link Settings allow merchants to customize the look and feel of hosted payment pages. These settings control how the payment link page appears to the customer—such as the font, size, colors, and branding elements like logos.

By updating these settings, merchants can ensure their payment experience is aligned with their brand identity and provides a consistent customer journey.

Use PUT /checkout/v3/paymentlinksetting?merchantId={merchantId}&echo=true API endpoint to update the visual and branding attributes of the payment link.

When this API is called, the updated settings are saved and applied to all payment links generated for the merchant. This request allows you to configure:

Setting Name	Description
fontFamily	Defines the font style to be used on the payment link page (e.g., Arial, Roboto). Helps maintain brand consistency.
fontSize	Controls the overall text size displayed on the payment link page.
fontColor	Hex color code representing the text color used throughout the page.
backgroundColor	Hex color code defining the background color of the payment link page.
logo	Base64-encoded image string or logo URL used to display the merchant’s branding on the payment page.
logoWidth	Specifies the width (in pixels) at which the logo should be rendered.
logoHeight	Specifies the height (in pixels) at which the logo should be rendered.
logoSize	Defines the overall scale or size parameter for the logo if width/height aren't explicitly set.

Use GET /checkout/v3/paymentlinksetting?merchantId={merchantId} to view the current styling and configuration applied to payment links. This returns the merchant’s active payment link styling configuration, including fonts, colors, and branding attributes.

Pending Items

Links to urls are yet to be edited.