A payment link is a hosted, shareable way to collect a payment without building a checkout. You create the link with a single API call, send the customer the URL (by email, SMS, or chat), and they pay on a branded page. Funds settle into the same account as your other card payments.

Common use cases

• Collect a one-off payment when you don't have a storefront or app checkout
• Send a "pay now" request by email or text, with the amount already locked
• Take payment over the phone by texting a link instead of reading card numbers aloud
• Re-bill a returning customer using the card saved from their first payment

Create your first payment link

The fastest way to see this work: create a link, then share the payment_link URL from the response. Send the minimal request below — the full field list is in the Request reference.

POST /checkout/v3/device

{
  "name": "Invoice 1042",
  "deviceType": "Link2Pay",
  "merchantId": 1000156763,
  "enabled": true,
  "onSuccessUrl": "https://your-app.example.com/paid",
  "onFailureUrl": "https://your-app.example.com/failed"
}

You'll get back the link resource. Share the payment_link URL with your customer; store the returned id so you can retrieve, disable, or delete the link later.

{
  "id": "faf264a2-bedc-494e-97e8-96ec87020a14",
  "name": "Invoice 1042",
  "deviceType": "Link2Pay",
  "deviceTypeName": "Payment Link",
  "enabled": true,
  "merchantId": 1000156763,
  "onSuccessUrl": "https://your-app.example.com/paid",
  "onFailureUrl": "https://your-app.example.com/failed",
  "transactionCount": 0,
  "transactionTotalAmount": "0",
  "customerCount": 0,
  "payment_link": "https://<pce-hosted-pay-page>/d/faf264a2-bedc-494e-97e8-96ec87020a14/v3"
}

The endpoint is POST /checkout/v3/device; deviceType must be Link2Pay.

Scenarios

Every payment link is created with POST /checkout/v3/device. What changes per scenario is the fields you set on the link.

Before you begin (all scenarios)

• You have your merchantId and PCE API credentials.
• Your onSuccessUrl / onFailureUrl endpoints are reachable to receive the customer after payment.

Scenario 1: Collect a fixed amount

(Lock the amount so the customer can't change it)

Use this to bill a specific amount — an invoice, a quote, a deposit. Create the link with POST /checkout/v3/device, setting MinPaymentAmount and MaxPaymentAmount to the same value to lock the field.

Request

POST /checkout/v3/device

{
  "name": "Invoice 1042",
  "deviceType": "Link2Pay",
  "merchantId": 1000156763,
  "enabled": true,
  "MinPaymentAmount": 250,
  "MaxPaymentAmount": 250,
  "onSuccessUrl": "https://your-app.example.com/paid",
  "onFailureUrl": "https://your-app.example.com/failed"
}

To let the customer choose the amount instead (for example, a donation or an open balance), omit both MinPaymentAmount and MaxPaymentAmount.

Scenario 2: Show and pre-fill an invoice number

(Match the payment back to your system)

Create the link with POST /checkout/v3/device, turning on the invoice-number field with InvoiceFieldEnabled and pre-filling it so the customer doesn't type it. The invoice number is returned to your onSuccessUrl and is the reliable way to reconcile the payment.

Request

POST /checkout/v3/device

{
  "name": "Invoice 1042",
  "deviceType": "Link2Pay",
  "merchantId": 1000156763,
  "enabled": true,
  "MinPaymentAmount": 250,
  "MaxPaymentAmount": 250,
  "InvoiceFieldEnabled": true,
  "payment_InvoiceNumber": "S114964",
  "onSuccessUrl": "https://your-app.example.com/paid",
  "onFailureUrl": "https://your-app.example.com/failed"
}

You can also pre-fill the invoice number and email directly on the hosted URL by appending query parameters:

https://<pce-hosted-pay-page>/d/{id}/v3?invoiceNumber=S114964&[email protected]

Scenario 3: Make a link one-time-use

(Prevent a second payment on the same link)

A payment link stays payable until you turn it off — the same link can be paid more than once. To enforce a single payment, disable or delete the link once you've confirmed the first payment.

Disable it (keeps the record, stops new payments) with PUT /checkout/v3/device — resend the link with enabled set to false:

PUT /checkout/v3/device?id=faf264a2-bedc-494e-97e8-96ec87020a14

{
  "name": "Invoice 1042",
  "deviceType": "Link2Pay",
  "merchantId": 1000156763,
  "enabled": false,
  "MinPaymentAmount": 250,
  "MaxPaymentAmount": 250
}

Or delete it entirely with DELETE /checkout/v3/device:

DELETE /checkout/v3/device?id=faf264a2-bedc-494e-97e8-96ec87020a14

Scenario 4: Re-bill a returning customer

(Charge a card the customer already used on a link)

When a customer pays through a link, PCE stores their card and creates a customer record. Reuse that saved token for later charges — no new link required.

1. Get the payment and its customer with GET /checkout/v3/payment/{id} using includeCustomer=true, and read the customerId.
2. List the customer's saved cards and take the token.
3. Charge the saved card with POST /checkout/v3/payment:

POST /checkout/v3/payment

{
  "paymentType": "Sale",
  "merchantId": "1000156763",
  "tenderType": "Card",
  "amount": 250,
  "source": "API",
  "customer": { "id": "10000001463608" },
  "cardAccount": { "token": "TNKY0O723SQMX3XWRV1JULV9WKP1HPSH" }
}

For repeating schedules, see Invoicing & Recurring Billing.

Track and reconcile

Your onSuccessUrl and onFailureUrl receive the customer after payment, with transaction details (including transId and the invoice number) as query parameters.

As a fallback — for example, if your callback doesn't fire — list payments taken through links with GET /checkout/v3/payment filtered by the payment-link source:

GET /checkout/v3/payment?merchantId=1000156763&source=link2Pay&status=any&transactionType=any&tenderType=any&dateType=Today&limit=50&offset=0

Request reference

The fields for POST /checkout/v3/device. The scenarios above use subsets of these.

Key response fields: id (use it to retrieve, update, or delete the link), payment_link (the hosted URL to share), deviceTypeName (Payment Link), and transactionCount / transactionTotalAmount (activity on the link).

Manage payment links

Brand the payment page

Control the look of the hosted payment page — fonts, colors, and logo — with the payment link settings. These apply to every payment link for the merchant.

Read the current settings

GET /checkout/v3/paymentlinksetting?merchantId=1000156763

Update the settings

POST /checkout/v3/paymentlinksetting?merchantId=1000156763

{
  "fontFamily": "Arial",
  "fontSize": 10,
  "fontColor": "#a72626",
  "backgroundColor": "#cb1515",
  "logo": "",
  "logoWidth": 0,
  "logoHeight": 0,
  "logoSize": 0
}

Read via GET /checkout/v3/paymentlinksetting; save via POST /checkout/v3/paymentlinksetting.

Next steps

See also

• Sale — take a card payment directly from your app
• Invoicing & Recurring Billing — send a payable invoice
• Reports & Reconciliation — track the payments you collect