Skip to content

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.
  • Create your secret and public API keys in the Dashboard.
  • Set up webhooks to be notified when the payment has been approved, so you can continue the sales fulfilment flow.

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

    Copied!

    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

    KNET

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

    Multibanco

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

    Przelewy24

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

    Sofort

    • currency should be set to EUR
    • billing.address.country is required

    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"
    }

    Response example

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

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

    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}

        Copied!

        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": "hpp_xGQBg0AXl3cM",
          "status": "Payment Pending",
          "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/hosted-payments/hpp_xGQBg0AXl3cM"
          },
          "redirect": {
          "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
          }
          }
          }

          Next steps

          Customize your Hosted Payments Page

          Find out how your Hosted Payments Page can be customized.