Manage Payment Links

Last updated: November 13, 2024

On this page, find out how to:

Have you registered to begin using Payment Links? Contact your Solution Engineer or [email protected]. During integration, you'll be able to specify your payment capture and 3D Secure settings.
Create your secret and public API keys in the Dashboard.
You can set up webhooks to be notified when the payment has been approved, so you can continue the sales fulfillment flow.

When requesting a payment from a customer using Payment Links solution, you can create a Payment Links session. This can be sent to the customer through a method that best suits you.

To display a button that will redirect the customer after their payment is approved, make sure your API request includes a return_url parameter with your chosen URL value.

To get a detailed view of all required and optional fields, see our API reference.

Note

Checkout.com does not support Payment Links embedded within an iframe.

Note

http://localhost/ can only be used for the URL fields during testing and will not work in production.

post

https://api.checkout.com/payment-links

The fields you're required to supply in your request vary depending on the payment method used. To see which fields are required, refer to the Payment methods table.


1{
2  "amount": 1000,
3  "currency": "GBP",
4  "reference": "ORD-123A",
5  "billing": {
6    "address": {
7      "country": "GB"
8    }
9  },
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "return_url": "https://example.com/payments/return"
15}

Some payment methods may require you to provide additional fields or specific values when you perform a payment request. Refer to the API reference for more details.

Payment method	Field requirements
Card payments	No additional requirements.
Apple Pay	Apple Pay is processed as a card transaction.
Google Pay	Google Pay is processed as a card transaction.
Alipay CN	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `CN`, for China `currency` value must be one of: `CNY` `HKD` `SGD`
Alipay HK	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `HK`, for Hong Kong `currency` value must be one of: `HKD` `SGD`
Bancontact	`customer.name` must be provided `billing.address.country` value must be `BE`, for Belgium `currency` value must be `EUR`
Benefit Payment Gateway	`billing.address.country` value must be `BH`, for Bahrain `currency` value must be `BHD` `reference` must be provided
Dana	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `ID`, for Indonesia `currency` value must be one of: `IDR` `HKD` `SGD`
EPS	`billing.address.country` value must be `AT`, for Austria `currency` value must be `EUR`
GCash	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `PH`, for the Philippines `currency` value must be one of: `PHP` `HKD` `SGD`
iDEAL	`billing.address.country` value must be `NL`, for Netherlands `currency` value must be `EUR`
Kakao Pay	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `KR`, for South Korea `currency` value must be one of: `KRW` `HKD` `SGD`
Klarna	`products[]` must be provided `customer.name` must be provided `billing.address.country` value must be one of: `AT`, for Austria `AU`, for Australia `BE`, for Belgium `CH`, for Switzerland `CZ`, for Czech Republic `DE`, for Germany `DK`, for Denmark `ES`, for Spain `FR`, for France `FI`, for Finland `GB`, for United Kingdom `GR`, for Greece `IE`, for Ireland `IT`, for Italy `NL`, for Netherlands `NO`, for Norway `PL`, for Poland `PT`, for Portugal `SE`, for Sweden `currency` value must be one of: `AUD` `CHF` `CZK` `DKK` `EUR` `GBP` `NOK` `PLN`
KNET	`billing.address.country` value must be `KW`, for Kuwait `currency` value must be `KWD` `locale` value must be `ar` – if no value is provided, the `en-GB` locale is used by default
Multibanco	`customer.name` must be provided `billing.address.country` value must be `PT`, for Portugal `currency` value must be `EUR`
Przelewy24	`customer.name` must be provided `customer.email` must be provided `billing.address.country` value must be `PL`, for Poland `currency` value must be `EUR` or `PLN`
QPay	`billing.address.country` value must be `QA`, for Qatar `currency` value must be `QAR` `description` must be provided
stc pay	`billing.address.country` must be set to `SA` `currency` value must be `SAR` `reference` must be provided
Touch 'n Go	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `MY`, for Malaysia `currency` value must be one of: `MYR` `HKD` `SGD`
TrueMoney	`amount` must be provided `customer.email` or `customer.id` must be provided `payment_type` must be set to `Regular` or `Recurring` `products[]` must be provided for each `product` in `products[]`, the following must be provided: `name` `quantity` `reference` `unit_price` `billing.address.country` value must be `TH`, for Thailand `currency` value must be one of: `THB` `HKD` `SGD`
Venmo	`billing.address.country` must be `US`, for the United States `currency` value must be `USD`


1{
2  "id": "pl_ELqQJXdXzabU",
3  "reference": "ORD-123A",
4  "expires_on": "2020-08-20T20:25:28+08:00",
5  "_links": {
6    "redirect": {
7      "href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
8    }
9  }
10}

Retrieve the Payment Link from _links.redirect.href to send to your customer.

This could be by email, text message, social media, live chat—wherever your customer wants to pay.

When they visit the link, they will be presented with a Hosted Payments Page to complete their payment. Once they have completed the payment, they will be redirected to a Checkout.com-hosted confirmation page.

To keep track of the payments you request through Payment Links, you can check the status using the id returned when you created the session. It will look like pl_ELqQJXdXzabU.

There are three statuses:

Active: The Payment Link can accept a payment from the customer. A payment may have been attempted by the customer but not completed successfully.
Payment Received: A payment has been received successfully using this Payment Link.
Expired: The Payment Link has expired and can no longer be accessed.

For a full explanation of the fields, see our API reference.

get

https://api.checkout.com/payment-links/{id}


1{
2  "id": "pl_ELqQJXdXzabU",
3  "status": "Active",
4  "payment_id": "undefined",
5  "amount": 200,
6  "currency": "GBP",
7  "reference": "ORD-123A",
8  "description": "Payment for Gold Necklace",
9  "expires_on": "2021-08-20T20:25:28+08:00",
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "billing": {
15    "address": {
16      "address_line1": "123 High St.",
17      "address_line2": "Flat 456",
18      "city": "London",
19      "zip": "SW1A 1AA",
20      "country": "GB"
21    },
22    "phone": {
23      "country_code": "+44",
24      "number": "1234567890"
25    }
26  },
27  "products": [
28    {
29      "name": "Gold Necklace",
30      "quantity": 1,
31      "price": 200
32    }
33  ],
34  "_links": {
35    "self": {
36      "href": "https://api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
37    },
38    "redirect": {
39      "href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
40    }
41  }
42}


1{
2  "id": "pl_ELqQJXdXzabU",
3  "status": "Payment Received",
4  "payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
5  "amount": 200,
6  "currency": "GBP",
7  "reference": "ORD-123A",
8  "description": "Payment for Gold Necklace",
9  "expires_on": "2021-08-20T20:25:28+08:00",
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "billing": {
15    "address": {
16      "address_line1": "123 High St.",
17      "address_line2": "Flat 456",
18      "city": "London",
19      "zip": "SW1A 1AA",
20      "country": "GB"
21    },
22    "phone": {
23      "country_code": "+44",
24      "number": "1234567890"
25    }
26  },
27  "products": [
28    {
29      "name": "Gold Necklace",
30      "quantity": 1,
31      "price": 200
32    }
33  ],
34  "_links": {
35    "self": {
36      "href": "https://api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
37    },
38    "redirect": {
39      "href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
40    },
41    "payment": {
42      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
43    },
44    "payment_actions": {
45      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
46    }
47  }
48}


1{
2  "id": "pl_ELqQJXdXzabU",
3  "status": "Expired",
4  "payment_id": "undefined",
5  "amount": 200,
6  "currency": "GBP",
7  "reference": "ORD-123A",
8  "description": "Payment for Gold Necklace",
9  "expires_on": "2021-08-20T20:25:28+08:00",
10  "customer": {
11    "name": "John Smith",
12    "email": "[email protected]"
13  },
14  "billing": {
15    "address": {
16      "address_line1": "123 High St.",
17      "address_line2": "Flat 456",
18      "city": "London",
19      "zip": "SW1A 1AA",
20      "country": "GB"
21    },
22    "phone": {
23      "country_code": "+44",
24      "number": "1234567890"
25    }
26  },
27  "products": [
28    {
29      "name": "Gold Necklace",
30      "quantity": 1,
31      "price": 200
32    }
33  ],
34  "_links": {
35    "self": {
36      "href": "https://api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
37    },
38    "redirect": {
39      "href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
40    }
41  }
42}

Customize Payment Links

Find out how a Payment Link can be customized.

Manage Payment Links

Before you begin

Create a Payment Link

Step 1: Create a new Payment Link session

Note

Endpoints

Note

Request example

Payment method field requirements

Response example

Step 2: Send the link to your customer

Check the status of a Payment Link

Endpoints

Response examples

Next steps

Customize Payment Links