Payment Links

Create a Payment Link to accept and process payment details.

Payment Links Operations

post/payment-links
get/payment-links/{id}

Create a Payment Link

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

Body·

required

application/json

amount
Type: integer
min:
1
required

The payment amount. The exact format depends on the currency.
currency
Type: string
min length:
3
max length:
3
required

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.
billing
Type: object
required

The billing details.
payment_type
Type: string enum

This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)
values
- Regular
- Recurring
authorization_type
Type: string enum

The authorization type.
values
- Final
- Estimated
payment_plan
Type: object ·

The information to process a recurring payment request. To be used when the payment_type is Recurring.
payment_ip
Type: string ·
max length:
45Format: ipv4
deprecated

The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
billing_descriptor
Type: object

An optional description that is displayed on the customer's statement identifying a purchase
reference
Type: string ·
max length:
50
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
Type: string
max length:
100

A description of the payment.
display_name
Type: string

The merchant name to display to customers on the checkout page.
processing_channel_id
Type: string Pattern: ^(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.

Responses

application/json
401

Unauthorized
application/json

post/payment-links

curl 'https://{prefix}.api.sandbox.checkout.com/payment-links' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "amount": 1000,
  "currency": "GBP",
  "payment_type": "Regular",
  "authorization_type": "Estimated",
  "payment_plan": {
    "amount_variability": "Variable",
    "days_between_payments": 28,
    "total_number_of_payments": 5,
    "current_payment_number": 3,
    "expiry": "20251031",
    "name": "Subscription 1234",
    "start_date": "20260507",
    "amount": 1234
  },
  "billing_descriptor": {
    "name": "",
    "city": "",
    "reference": ""
  },
  "reference": "ORD-123A",
  "description": "Payment for Gold Necklace",
  "display_name": "The Jewelry Shop",
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "amount_allocations": [
    {
      "id": "ent_w4jelhppmfiufdnatam37wrfc4",
      "amount": 1000,
      "reference": "ORD-5023-4E89",
      "commission": {
        "amount": 1000,
        "percentage": 1.125
      }
    }
  ],
  "expires_in": 604800,
  "customer": {
    "email": "ali.farid@example.com",
    "name": "Ali Farid",
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    },
    "summary": {
      "registration_date": "2023-05-01",
      "first_transaction_date": "2023-07-01",
      "last_payment_date": "2023-08-01",
      "total_order_count": 15,
      "last_payment_amount": 500,
      "is_premium_customer": true,
      "is_returning_customer": true,
      "lifetime_value": 500
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "billing": {
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "recipient": {
    "dob": {},
    "account_number": "5555554444",
    "address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "state": "",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "first_name": "Jia",
    "last_name": "Tsang"
  },
  "processing": {
    "aft": true,
    "discount_amount": 0,
    "shipping_amount": 300,
    "tax_amount": 3000,
    "invoice_id": "",
    "brand_name": "",
    "locale": "en-US",
    "partner_customer_risk_data": {
      "key": "",
      "value": ""
    },
    "custom_payment_method_ids": [
      ""
    ],
    "airline_data": [
      {
        "ticket": {
          "number": "045-21351455613",
          "issue_date": "2023-05-20",
          "issuing_carrier_code": "AI",
          "travel_package_indicator": "B",
          "travel_agency_name": "World Tours",
          "travel_agency_code": "01"
        },
        "passenger": [
          {
            "first_name": "John",
            "last_name": "White",
            "date_of_birth": "1990-05-26",
            "address": {
              "country": "US"
            }
          }
        ],
        "flight_leg_details": [
          {
            "flight_number": "101",
            "carrier_code": "BA",
            "class_of_travelling": "J",
            "departure_airport": "LHR",
            "departure_date": "2023-06-19",
            "departure_time": "15:30",
            "arrival_airport": "LAX",
            "stop_over_code": "x",
            "fare_basis_code": "SPRSVR"
          }
        ]
      }
    ],
    "accommodation_data": [
      {
        "name": "The Sea View Hotel",
        "booking_reference": "HOTEL123",
        "check_in_date": "2023-06-20",
        "check_out_date": "2023-06-23",
        "address": {
          "address_line1": "123 Beach Road",
          "zip": "10001"
        },
        "state": "FL",
        "country": "USA",
        "city": "Los Angeles",
        "number_of_rooms": 2,
        "guests": [
          {
            "first_name": "Jane",
            "last_name": "Doe",
            "date_of_birth": "1985-07-14"
          }
        ],
        "room": [
          {
            "rate": "70",
            "number_of_nights_at_room_rate": "3"
          }
        ]
      }
    ],
    "order_id": "123456789",
    "surcharge_amount": 200,
    "duty_amount": 0,
    "shipping_tax_amount": 100,
    "affiliate_id": "",
    "affiliate_url": "www.mycrypto.com",
    "purchase_country": "",
    "merchant_initiated_reason": "Delayed_charge",
    "campaign_id": 1,
    "original_order_amount": 10,
    "receipt_id": "10",
    "merchant_callback_url": "",
    "line_of_business": "Flights",
    "pan_preference": "fpan",
    "provision_network_token": true,
    "reconciliation_id": "4123495123",
    "aggregator": {
      "sub_merchant_id": "9cf70789ba90123",
      "aggregator_id_visa": "10012345",
      "aggregator_id_mc": "00000123456"
    }
  },
  "allow_payment_methods": [
    "card",
    "applepay",
    "googlepay"
  ],
  "disabled_payment_methods": [
    "eps",
    "ideal",
    "knet"
  ],
  "products": [
    {
      "reference": "",
      "url": "https://example.com/products/gold-necklace",
      "name": "Gold Necklace",
      "quantity": 1,
      "price": 1000
    }
  ],
  "metadata": {
    "additionalProperty": "anything"
  },
  "3ds": {
    "enabled": false,
    "attempt_n3d": false,
    "challenge_indicator": "no_preference",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "risk": {
    "enabled": false
  },
  "customer_retry": {
    "max_attempts": 2
  },
  "sender": {},
  "return_url": "https://example.com/success",
  "locale": "en-GB",
  "capture": true,
  "capture_on": "",
  "instruction": {
    "purpose": "donations"
  },
  "payment_method_configuration": {
    "applepay": {
      "account_holder": {},
      "store_payment_details": "disabled"
    },
    "card": {
      "store_payment_details": "disabled",
      "account_holder": {}
    },
    "googlepay": {
      "account_holder": {},
      "store_payment_details": "disabled"
    }
  }
}'

Show Schema

{
  "id": "pl_ELqQJXdXzabU",
  "expires_on": "2020-08-20T20:25:28+08:00",
  "reference": "ORD-123A",
  "warnings": [
    {
      "code": "payment_method_unavailable",
      "description": "The card was provided in the `allow_payment_methods` object, but no card schemes are configured.",
      "value": "card"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
    },
    "redirect": {
      "href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
    }
  }
}

Create Payment Link Page

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.

Path Parameters

id
Type: string ·
min length:
15
max length:
15Pattern: ^pl_[A-Za-z0-9_-]{12}$
required

The unique identifier for a Payment Link.

Responses

application/json
401

Unauthorized
404

Payment Link session not found

get/payment-links/{id}

curl 'https://{prefix}.api.sandbox.checkout.com/payment-links/{id}' \
  --header 'Authorization: YOUR_SECRET_TOKEN'

Show Schema

{
  "id": "pl_ELqQJXdXzabU",
  "status": "Active",
  "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",
  "customer": {
    "email": "brucewayne@email.com",
    "name": "Bruce Wayne"
  },
  "billing": {
    "address": {
      "address_line1": "123 High St.",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "country_code": "+1",
      "number": "415 555 2671"
    }
  },
  "return_url": "https://example.com/success",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-links/pl_ELqQJXdXzabU"
    },
    "redirect": {
      "href": "https://pay.sandbox.checkout.com/link/pl_ELqQJXdXzabU"
    }
  }
}

Payment Link details retrieved successfully