Create a Hosted Payments Page to accept and process payment details.
Hosted Payments Page Operations
Create a Hosted Payments Page to accept and process payment details.
The three-letter ISO currency code of the payment
The billing details
For redirect payment methods, this overrides the default success redirect URL configured on your account
The URL to which the customer should be directed if they cancel the payment
For redirect payment methods, this overrides the default failure redirect URL configured on your account
This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)
The authorization type.
The information to process a recurring payment request. To be used when the payment_type is Recurring.
The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
An optional description that is displayed on the customer's statement identifying a purchase
A reference you can use to identify the payment. For example, an order number.
Unauthorized
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"
}
}
}Pattern: ^hpp_[A-Za-z0-9_-]{12}$The unique identifier for a Hosted Payments Page.
Unauthorized
Hosted Payments Page not found
curl 'https://{prefix}.api.sandbox.checkout.com/hosted-payments/{id}' \
--header 'Authorization: YOUR_SECRET_TOKEN'
{
"id": "hpp_xGQBg0AXl3cM",
"status": "Payment Pending",
"amount": 100,
"currency": "GBP",
"reference": "ORD-123A",
"description": "Payment for Gold Necklace",
"customer": {
"email": "brucewayne@email.com",
"name": "Bruce Wayne"
},
"billing": {
"address": {
"address_line1": "123 High St.",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"phone": {
"country_code": "+1",
"number": "415 555 2671"
}
},
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"failure_url": "https://example.com/failure",
"_links": {
"self": {
"href": "https://{prefix}.api.sandbox.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
},
"redirect": {
"href": "https://pay.sandbox.checkout.com/page/hpp_xGQBg0AXl3cM"
}
}
}