Skip to content

Manage Payment Links

Last updated: 6th July 2022

On this page, find out how to:


Before you begin

  • Have you registered to begin using Payment Links? Contact your Solution Engineer or tech.support@checkout.com. During integration, you'll be able to specify your payment capture and 3D Secure settings.
  • You can set up webhooks to be notified when the payment has been approved, so you can continue the sales fulfilment flow.
  • To practice API calls request a test account and use the Sandbox version of the endpoint.

Create a Payment Link

Step 1: Create a new Payment Link session

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 get a detailed view of all required and optional fields, see our API reference.

You can provide a return_url in your API request. Once their payment is confirmed, the customer will be redirected to wherever the link is directed to. This could be back to your website, for example.

Endpoints

Testing

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

    Required parameters for certain payment methods

    Depending on the payment method, certain parameters are required. Please use the table below to find out more.

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    {
    "amount": 1000,
    "currency": "GBP",
    "reference": "ORD-123A",
    "billing": {
    "address": {
    "country": "GB"
    }
    },
    "customer": {
    "name": "Bruce Wayne",
    "email": "brucewayne@gmail.com"
    },
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure",
    "cancel_url": "https://example.com/payments/checkout"
    }

    Payment methods

    We've listed the available payment methods for the Payment Links below.

    Different payment methods have different required and optional fields when making a request. We've shown examples of these below.

    You can view a request example with all of these fields on our API reference.

    Payment methodField requirements

    Bancontact

    • billing.address.country: BE for Belgium.
    • currency: EUR.
    • customer.name is required.

    EPS

    • billing.address.country: AT for Austria.
    • currency: EUR.

    Giropay

    • billing.address.country: DE for Germany.
    • currency: EUR.

    iDEAL

    • currency should be set to EUR.
    • billing.address.country: NL for Netherlands.

    Klarna

    Klarna only accepts primary currency and address combinations. We use the 2-letter ISO country code, and a 3-letter ISO currency code.

    These country and currency combinations also expect specific locales. They are specified in the following list.

    • Austria: AT - EUR - en-AT
    • Denmark: DK - DKK - en-DK or da-DK
    • Finland: FI - EUR - en-FI or fi-FI
    • Germany: DE - EUR - en-DE or de-DE
    • Netherlands: NL - EUR - en-NL or nl-NL
    • Norway: NO - NOK - en-NO or nb-NO
    • Sweden: SE - SEK - en-SE or sv-SE
    • Switzerland: CH - CHF - de-CH, fr-CH, it-CH or en-CH
    • United Kingdom: GB - GBP - en-GB

    Required fields for all accepted countries:

    • customer.name
    • customer.email
    • billing.address.address_line1
    • billing.address.city
    • billing.address.zip
    • products (object)

    KNET

    • billing.address.country: KW for Kuwait.
    • currency to KWD.
    • locale: ar
      en-GB is the default if field is not provided.

    Mada

    • billing.address.country: SA for Saudi Arabia
    • currency: SAR.

    Multibanco

    • billing.address.country: PT for Portugal.
    • currency: EUR.
    • customer.name is required.

    PayPal

    • reference is required.
    • billing.address.country and currency is required and can be any that are supported.

    Przelewey24

    • billing.address.country: PL for Poland.
    • currency: EUR or PLN.
    • customer.name is required.
    • customer.email is required.

    SEPA Direct Debit

    • currency should be set to EUR.
    • billing.address.country is required and can be any country that is supported.
    • customer.name is required.

    Sofort

    Response example

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

    Step 2: Send the link to your customer

    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 Checkout.com-hosted payment page to complete their payment. Once they have completed the payment, they will be redirected to a Checkout.com-hosted confirmation page. The button at the bottom of the page redirects the customer to the specified URL only if you provide a return_url when creating a Payment Link, so make sure you include it in your API request.


    Check the status of a Payment Link

    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.

    Endpoints

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

      get

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

      Response examples

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