Checkout.com API logo

Hosted Payments Page

Create a Hosted Payments Page to accept and process payment details.

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.

SecurityAPI Key: ApiSecretKey
Request
Request Body schema: application/json
required
currency
required
string = 3 characters

The three-letter ISO currency code of the payment

required
object

The billing details

success_url
required
string <uri> <= 255 characters

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

cancel_url
required
string <uri> <= 255 characters

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

failure_url
required
string <uri> <= 255 characters

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

amount
integer >= 0

The payment amount. The exact format depends on the currency

payment_type
string
Default: "Regular"

This must be specified for card payments where the cardholder is not present (i.e., recurring or mail order / telephone order)

Enum: "Regular" "Recurring"
payment_ip
string <ipv4> <= 45 characters
Deprecated

The Customers IP address. Only IPv4 and IPv6 addresses are accepted.

object

An optional description that is displayed on the customer's statement identifying a purchase

reference
string <= 50 characters

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.
description
string <= 100 characters

A description of the payment

display_name
string

The merchant name to display to customers on the checkout page.

processing_channel_id
string^(pc)_(\w{26})$

The processing channel to be used for the payment

Array of objects (Amount Allocations) [ 1 .. 50 ] items

The sub-entities that the payment is being processed on behalf of

object

The customer's details

object

The address any products are being sent to.

object (PaymentInterfacesRecipient)

Information about the recipient of the payment's funds. Applies to Account Funding Transactions, and VISA or Mastercard domestic UK transactions processed by financial institutions.

object (PaymentInterfacesProcessing)

Use the processing object to influence or override the data sent during card processing

allow_payment_methods
Array of strings

Specifies which payment method options to present to the customer.

The values in this field override any equivalent values in disabled_payment_methods.

Some payment methods have additional field requirements. See the documentation for more information.

Items Enum: "alipay_cn" "alipay_hk" "alma" "applepay" "bancontact" "benefit" "bizum" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "mbway" "mobilepay" "multibanco" "octopus" "p24" "paynow" "paypal" "plaid" "qpay" "remember_me" "sepa" "stcpay" "stored_card" "tabby" "tamara" "tng" "truemoney" "twint" "vipps" "wechatpay"
disabled_payment_methods
Array of strings

Specifies which payment method options to not present to the customer.

If you specify the same payment method in this field and in allow_payment_methods, the disabled_payment_methods value will be overridden.

Any payment method options not explicitly specified in this field will be presented to the customer by default.

Items Enum: "alipay_cn" "alipay_hk" "alma" "applepay" "bancontact" "benefit" "bizum" "card" "dana" "eps" "gcash" "googlepay" "ideal" "kakaopay" "klarna" "knet" "mbway" "mobilepay" "multibanco" "octopus" "p24" "paynow" "paypal" "plaid" "qpay" "remember_me" "sepa" "stcpay" "stored_card" "tabby" "tamara" "tng" "truemoney" "twint" "vipps" "wechatpay"
Array of objects [ 1 .. 1000 ] items

Contains details about the products in the order.

object

Configures the risk assessment performed during payment processing.

object

Configures the parameters for customer retries.

A customer retry is a payment attempt performed by the customer on the checkout page. This differs from authorization request retries performed in the back end by Checkout.com.

object

The sender of the payment.

object (The Metadata Schema)

Allows you to store additional information about the transaction. This object only allows one level of depth, so cannot accept non-primitive data types such as objects or arrays.

locale
string
Default: "en-GB"

Creates a translated version of the page in the specified language

Enum: "ar" "da-DK" "de-DE" "el" "en-GB" "es-ES" "fi-FI" "fil-PH" "fr-FR" "hi-IN" "id-ID" "it-IT" "ja-JP" "ms-MY" "nb-NO" "nl-NL" "pt-PT" "sv-SE" "th-TH" "vi-VN" "zh-CN" "zh-HK" "zh-TW"
object

Information required for 3D Secure payments

capture
boolean

Whether to capture the payment (if applicable).

capture_on
string <date-time>

A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set capture to true.

object

Details about the payment instruction.

object

Configuration options for specific payment methods.

Responses
201

Created Hosted Payments Page

401

Unauthorized

422

Invalid data was sent

post/hosted-payments
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "GBP",
  • "payment_type": "Regular",
  • "payment_ip": "90.197.169.245",
  • "billing_descriptor": {
    },
  • "reference": "ORD-123A",
  • "description": "Payment for Gold Necklace",
  • "display_name": "The Jewelry Shop",
  • "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  • "amount_allocations": [
    ],
  • "customer": {
    },
  • "shipping": {
    },
  • "billing": {
    },
  • "recipient": {
    },
  • "processing": {
    },
  • "allow_payment_methods": [
    ],
  • "disabled_payment_methods": [
    ],
  • "products": [],
  • "risk": {
    },
  • "customer_retry": {
    },
  • "sender": {
    },
  • "success_url": "https://example.com/payments/success",
  • "cancel_url": "https://example.com/payments/cancel",
  • "failure_url": "https://example.com/payments/failure",
  • "metadata": { },
  • "locale": "ar",
  • "3ds": {
    },
  • "capture": true,
  • "capture_on": "2019-08-24T14:15:22Z",
  • "instruction": {
    },
  • "payment_method_configuration": {
    }
}
Response samples
application/json
{}

Get Hosted Payments Page details

Retrieve details about a specific Hosted Payments Page using the ID returned when it was created. In the response, you will see the status of the Hosted Payments Page.

For more information, see the Hosted Payments Page documentation.

SecurityAPI Key: ApiSecretKey
Request
path Parameters
id
required
string = 16 characters ^hpp_[A-Za-z0-9_-]{12}$

The unique identifier for a Hosted Payments Page.

Responses
200

Hosted Payments Page details retrieved successfully

401

Unauthorized

404

Hosted Payments Page not found

get/hosted-payments/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Payments.Hosted;

ICheckoutApi api = CheckoutSdk.Builder().StaticKeys()
    .SecretKey("secret_key")
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    HostedPaymentDetailsResponse response = await api.HostedPaymentsClient().GetHostedPaymentsPageDetails("hosted_payment_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{}
➔ Next to Forex