Create a Hosted Payments Page session

​

Create a Hosted Payments Page session and pass through all the payment information, like the amount, currency, country and reference.

To get started with our Hosted Payments Page, contact your solutions engineer or request support.

Body·
required
application/json
  • currency
    Type: string
    min length:  
    3
    max length:  
    3
    required

    The three-letter ISO currency code of the payment

  • billing
    Type: object
    required

    The billing details

  • success_url
    Type: string
    max length:  
    255    Format: uri
    required

    For redirect payment methods, this overrides the default success redirect URL configured on your account

  • cancel_url
    Type: string
    max length:  
    255    Format: uri
    required

    The URL to which the customer should be directed if they cancel the payment

  • failure_url
    Type: string
    max length:  
    255    Format: uri
    required

    For redirect payment methods, this overrides the default failure redirect URL configured on your account

  • amount
    Type: integer
    min:  
    0

    The payment amount. The exact format depends on the currency

  • 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:  
    45    Format: 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.
Responses
  • application/json
  • 401

    Unauthorized

  • application/json
Request Example for post/hosted-payments
curl 'https://{prefix}.api.sandbox.checkout.com/hosted-payments' \
  --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
      }
    }
  ],
  "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
    }
  ],
  "risk": {
    "enabled": false
  },
  "customer_retry": {
    "max_attempts": 2
  },
  "sender": {},
  "success_url": "https://example.com/payments/success",
  "cancel_url": "https://example.com/payments/cancel",
  "failure_url": "https://example.com/payments/failure",
  "metadata": {
    "additionalProperty": "anything"
  },
  "locale": "en-GB",
  "3ds": {
    "enabled": false,
    "attempt_n3d": false,
    "challenge_indicator": "no_preference",
    "allow_upgrade": true,
    "exemption": "low_value"
  },
  "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"
    },
    "stored_card": {
      "customer_id": "",
      "instrument_ids": [
        ""
      ],
      "default_instrument_id": ""
    }
  }
}'

{
  "id": "hpp_xGQBg0AXl3cM",
  "reference": "ORD-123A",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
    },
    "redirect": {
      "href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
    }
  }
}

Created Hosted Payments Page