Skip to content
Integrate / Hosted Payments Page / Manage your Hosted Payments Page

Manage your Hosted Payments Page

Last updated: October 26, 2022

On this page, find out how to:

Before you begin

  • Have you registered to begin using Hosted Payments Page? Contact your Solution Engineer or support@checkout.com. During integration, you'll be able to specify your payment capture and 3D Secure settings.
  • Find your secret and public API keys in the Hub.
  • 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 Hosted Payments Page

Step 1: Create a new Hosted Payments Page

When a customer purchases something from you, you can create a Hosted Payments Page session by using the post/hosted-payments endpoint and providing us with details of the purchase.

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

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/hosted-payments

    Payment methods

    We've listed the available payment methods for the Hosted Payments Page below.

    Different payment methods have different required and optional fields when making a request. We've listed 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.

    Google Pay

    Google Pay is processed as a card transaction, so all required fields are the same as with a card payment.

    This also means it will be rendered as a payment option when allow_payment_methods: [“card”] is passed in the session request or when conditions for card and Google Pay are met.

    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 or de-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.

    Przelewy24

    • 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

    Request example

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

    Response example

    The response will include the redirect link to which you should redirect your customer to finalize the payment.

    1
    {
    2
      "id": "hpp_xGQBg0AXl3cM",
    3
      "reference": "ORD-123A",
    4
       "_links": {
    5
        "self": {
    6
          "href": "https://api.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
    7
        },
    8
         "redirect": {
    9
           "href": "https://pay.checkout.com/page/hpp_xGQBg0AXl3cM"
    10
         }
    11
       }
    12
     }

    Step 2: Redirect your customer

    Redirect the customer to the _links.redirect URL you received in the response above, using either a server-side or client-side call.

      1
      res.redirect(hostedPaymentsResponse._links.redirect.href);

      If loading the Hosted Payments Page in an iframe, you will need to add allow="payment" as an attribute on the iframe.

      Step 3: Confirm the payment status

      When your customer completes the payment, they will be redirected to the success URL. The session ID (cko-session-id) or payment ID (cko-payment-id) is provided in the query parameter included in the redirect URL. It will look something this:

      • http://example.com/success?cko-session-id=sid_ubj2q76miwundwlk72vxt2i7
      • http://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpit4

      You can set up webhooks to be notified when the payment has been approved, so you can continue the sales fulfilment flow.

      Check the status of a Hosted Payments Page

      To keep track of the payments you request as a Hosted Payments Page, you can check the status using the id returned when you created the session. It will look like hpp_xGQBg0AXl3cM.

      There are three statuses:

      • Payment Pending: The Hosted Payments Page 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 Hosted Payments Page.
      • Expired: The Hosted Payments Page 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/hosted-payments/{id}

        Response examples

          1
          {
          2
            "id": "hpp_xGQBg0AXl3cM",
          3
            "status": "Payment Pending",
          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": "Bruce Wayne",
          12
              "email": "brucewayne@email.com"
          13
            },
          14
            "billing": {
          15
              "address": {
          16
                "address_line1": "Checkout.com",
          17
                "address_line2": "90 Tottenham Court Road",
          18
                "city": "London",
          19
                "state": "London",
          20
                "zip": "W1T 4TJ",
          21
                "country": "GB"
          22
              },
          23
              "phone": {
          24
                "country_code": "+1",
          25
                "number": "4155552671"
          26
              }
          27
            },
          28
            "products": [
          29
              {
          30
                "name": "Gold Necklace",
          31
                "quantity": 1,
          32
                "price": 200
          33
              }
          34
            ],
          35
            "_links": {
          36
              "self": {
          37
                "href": "https://api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
          38
              },
          39
              "redirect": {
          40
                "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
          41
              }
          42
            }
          43
          }

          Next steps

          Customize your Hosted Payments Page

          Find out how your Hosted Payments Page can be customized.

          Learn more

          On this page

          Before you begin
          Create a Hosted Payments Page
          Check the status of a Hosted Payments Page
          Next steps