Skip to content

Manage your Hosted Payments Page

Last updated: 6th July 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 tech.support@checkout.com. During integration, you'll be able to specify your payment capture and 3D Secure settings.
  • 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.

    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

    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);

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