Checkout.com API logo

Payment Links

Create a Payment Link to accept and process payment details.

Create a Payment Link

Create a Payment Link and pass through all the payment information, like the amount, currency, country and reference.

SecurityAPI Key: ApiSecretKey
Request
Request Body schema: application/json
required
amount
required
integer >= 1

The payment amount. The exact format depends on the currency.

currency
required
string = 3 characters

The three-letter ISO currency code of the payment.
The currency and billing.address.country fields determine which payment methods are shown on the payment page.

required
object

The billing details.

payment_type
string
Default: "Regular"

This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)

Enum: "Regular" "Recurring"
payment_ip
string <ipv4> <= 45 characters
Deprecated

The Customers IP address. Only IPv4 and IPv6 addresses are accepted.

object

An optional description that is displayed on the customer's statement identifying a purchase

reference
string <= 50 characters

A reference you can use to identify the payment. For example, an order number.

  • For Amex payments, this must be at most 30 characters.
  • For Benefit payments, the reference must be a unique alphanumeric value.
  • For iDEAL payments, the reference is required and must be an alphanumeric value with a 35-character limit.
description
string <= 100 characters

A description of the payment.

display_name
string

The merchant name to display to customers on the checkout page.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel to use for the payment.

This field is required if you have more than one processing channel associated with your API key.

Array of objects (Amount Allocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

expires_in
integer [ 1 .. 5184000 ]
Default: 86400

The time for which the link remains valid, in seconds.

object

The customer's details

object

The address any products are being sent to.

object (PaymentInterfacesRecipient)

Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.

object (PaymentInterfacesProcessing)

Use the processing object to influence or override the data sent during card processing

allow_payment_methods
Array of strings

Specifies which payment method options to present to the customer.

The values in this field override any equivalent values in disabled_payment_methods.

Some payment methods have additional field requirements. See the documentation for more information.

Items Enum: "alipay_cn" "alipay_hk" "alma" "applepay" "bancontact" "benefit" "bizum" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "mbway" "mobilepay" "multibanco" "octopus" "p24" "paynow" "paypal" "plaid" "qpay" "remember_me" "sepa" "stcpay" "stored_card" "tabby" "tamara" "tng" "truemoney" "twint" "vipps" "wechatpay"
disabled_payment_methods
Array of strings

Specifies which payment method options to not present to the customer.

If you specify the same payment method in this field and in allow_payment_methods, the disabled_payment_methods value will be overridden.

Any payment method options not explicitly specified in this field will be presented to the customer by default.

Items Enum: "alipay_cn" "alipay_hk" "alma" "applepay" "bancontact" "benefit" "bizum" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "mbway" "mobilepay" "multibanco" "octopus" "p24" "paynow" "paypal" "plaid" "qpay" "remember_me" "sepa" "stcpay" "stored_card" "tabby" "tamara" "tng" "truemoney" "twint" "vipps" "wechatpay"
Array of objects [ 1 .. 1000 ] items

Contains details about the products in the order.

object (The Metadata Schema)

Allows you to store additional information about the transaction. This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.

object

Information required for 3D Secure payments.

object

Configures the risk assessment performed during payment processing.

object

Configures the parameters for customer retries.

A customer retry is a payment attempt performed by the customer on the checkout page. This differs from authorization request retries performed in the back end by Checkout.com.

object

The sender of the payment.

return_url
string <uri> <= 255 characters

If provided, the success page will include a button that redirects your customer to the provided URL.

locale
string
Default: "en-GB"

Creates a translated version of the page in the specified language

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
capture
boolean

Whether to capture the payment (if applicable).

capture_on
string <date-time>

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true.

object

Details about the payment instruction.

object

Configuration options for specific payment methods.

Responses
201

Create Payment Link Page

401

Unauthorized

422

Invalid data was sent

post/payment-links
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "payment_ip": "90.197.169.245",
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for Gold Necklace",
  • "display_name": "The Jewelry Shop",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount_allocations": [
    ],
  • "expires_in": 604800,
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "allow_payment_methods": [
    ],
  • "disabled_payment_methods": [
    ],
  • "products": [],
  • "metadata": { },
  • "3ds": {
    },
  • "risk": {
    },
  • "customer_retry": {
    },
  • "sender": {
    },
  • "return_url": "https://example.com/success",
  • "locale": "ar",
  • "capture": true,
  • "capture_on": "2019-08-24T14:15:22Z",
  • "instruction": {
    },
  • "payment_method_configuration": {
    }
}
Response samples
application/json
{}

Get Payment Link details

Retrieve details about a specific Payment Link using its ID returned when the link was created. In the response, you will see the status of the Payment Link.

For more information, see the Payment Links documentation.

SecurityAPI Key: ApiSecretKey
Request
path Parameters
id
required
string = 15 characters ^pl_[A-Za-z0-9_-]{12}$

The unique identifier for a Payment Link.

Responses
200

Payment Link details retrieved successfully

401

Unauthorized

404

Payment Link session not found

get/payment-links/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Payments.Links;

ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    PaymentLinkDetailsResponse response = await api.PaymentLinksClient().Get("payment_link_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "id": "pl_ELqQJXdXzabU",
  • "status": "Active",
  • "payment_id": "pay_88cb4e671m1da22e9bbbyx",
  • "amount": 100,
  • "currency": "GBP",
  • "reference": "ORD-123A",
  • "description": "Payment for Gold Necklace",
  • "created_on": "2021-08-19T20:25:28.725Z",
  • "expires_on": "2021-08-20T20:25:28+08:00",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount_allocations": [
    ],
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "products": [],
  • "metadata": { },
  • "locale": "ar",
  • "return_url": "https://example.com/success",
  • "_links": {}
}
➔ Next to Hosted Payments Page