HOSTED PAYMENT FIELDS

Version: 1.0.0
Released: 2025/10/23

Hosted Payment Fields (HPF)

Hosted Payment Fields provide an optimal balance between security, customization flexibility, and ease of payment page integration.

This integration method does not require PCI DSS Level 1 certification, as all sensitive payment data is processed and stored on our platform.

Checkout workflow (steps to perform) is shown below.

Perform a server-to-server request to URL {{CHECKOUT_HOST}}/api/v1/session/token to obtain a session token. Please see CHECKOUT -> Integration Flow -> Authentication request parameters section.

Response Example (success)

""token"": "ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOaUo5LmV5SnBZWFFpT2pFM05UUTVNak0yTlRJc0ltcDBhU0k2SWpGak9XSXpaamRsTFRjMll6SXRNVEZtTUMwNE9EZGtMVGhoTm1SaE1qWmtNVGhpTUNJc0ltVjRjQ0k2TVRjMU5Ea3lOekkxTW4wLlZ5aUc3ZVJ1dWdlYzk1cnM5OG5HRGhrSGJXdGxuU3BJdFc5aGhNNGlac3BKUi1maHZWWWVJeEc5OUxBcnEtR1BqTnR0RDJNRVFUN2dWRU0tQ2VIOE1aelpKR3VKN0R3cEptaUg0ODAtOW9RLU9UV2ZwUHZzQWFUSmRWZkw2Ui1nUkhadlRmMDc2YXlVWlhoTDF6U0tLYWdaOW5adkFlSHJTZE82OWFtNDkxbl9LVlpNTjRYUW5IWlV0dFJKNzBTdmpsbEpaaW04ZUZKQWE5NTZzQ08zSWtTbWlLcHlOTE52S0d4WHBBcVYtQ0g5M25vYzBJcnduc2U2aE9HLVRnbVlaV3RXeWlCZGFLa0psRWxKY0tVLWZ5VWduQmhsQWx6aVhBejRFS1ZnLXZTdHQ3WWk5ZmhYd1ctNm1BRGJtbmgxYjdlVURDclJMMmkzSHhLd0NiTXZrSE9BMFpyRjE5cGJoLXZzSnhNa05ydUNZRi02NHJRRVZYc2hJdEhhMnVWQnJUWTlZYmFUbWdRaENEanJxZWtQVEhfM0tKQV9FUExBU01yT19GeTBZcmRkajZBVGpROXUwWWZHVkpaV2p3UzVvRWwxQlZzUHNEZERncUlrWXdoSXQtbTFIcndlcXROYVNsTUtoVXQ5azE4SVlJbzZjc2oycU1acXFtQ2VURHBwMXZsXzk2VnBwc2xGLVdXdnUxRWd6X3BscVF0NzVkQVBvZWV1YXFyQ3pKT0NVRGIzdWVmbElQN3ZhTEFNekw2dEgzWUZycjZsRlhfbmNtYVhNRXpib2k1ejEtVmoyY0YzOEE2YV9MM041WllCcFBaTGJVaUFuTHh1M1Q2cWhSVEhjV1NpUTZZMFQ4WndUNkVjRWFvaEI1WVJqSFo3NGNkWC00UTVaR3AwT2Jj"}

Integrate the HostedFields JavaScript library into your payment page and initialize the HostedFields() object, specifying the HTML element identifiers for card data input fields.

Example

<script src="https://{{CHECKOUT_HOST}}/sdk/hosted-fields.js"></script>

<script>

const token = "{{session_token}}";
const config = {
    sessionToken: token,
    fields: {
        card: {
            id: "card-container", //identifier of container for rendering iframe with card number input
            placeholder: "Сard number",
            style: { //styles for this particular input
                input: {
                    color: "red",
                },
                "::placeholder": {
                    "font-size": "1rem",
                    color: "blue",
                },
                ".hosted-field-card-brand-logo": {
                    border: "1px solid silver;",
                }
            },
        },
        expiry: {
            id: "expiry-container",
            placeholder: "Expiry"
        },
        cvv: {
            id: "cvv-container",
            placeholder: "CVV"
        }
    },
    style: { //general style for all these inputs
        input: {
            "font-size": "1rem",
        },
        "::placeholder": {
            "font-size": "1rem",
            color: "#777",
            "font-style": "italic"
        }
    }
};

var hostedFields = new HostedFields();

hostedFields.init(config);

<script>

(Optional) Use the listeners mechanism to handle input validation errors in the card data fields. Library allows to use listeners for 3 types of events: focus, input and blur. Input event also contains a validation result that can be used for different purposes

hostedFields.cardOn.input = function(data) {
    if (!data.valid) {
        document.querySelector("#card-container").classList.add("input-invalid");
    } else {
        document.querySelector("#card-container").classList.remove("input-invalid");
    }
};
hostedFields.cardOn.focus = function() {
    some code here...
};
hostedFields.cardOn.blur = function() {
    some code here...
};

Once the customer has entered their card details, call the hostedFields.collectIframesData() method.
Send an HTTP request to process the payment.

Request endpoint: {{CHECKOUT_HOST}}/api/v1/processing/purchase/card

Request Headers: Token: {{session_token}}

Request Parameters

Parameter	Type	Mandatory, Limitations	Description
`name`	String	Required	Example: JOHN DOE
`with_hosted_fields`	Bool	Required	Example: true
`billing_address`	object	Optional	Example: `“billing_address”: {“country”:”US”, “state”:”SA”, “city”:”Hong Kong”, “address”:”Moor Building 35274 State ST Fremont. U.S.A”, “zip”:”94538”, “phone”:”+14035555555”, “district”:”Brentwood”, “house_number”:”123”}`
`browser_info`	object	Optional	Example: `“browser_info”: {“color_depth”:”24”, “java_enabled”:”false”, “java_script_enabled”:”true”, “language”:”en-US”, “screen_height”:”1600”, “screen_width”:”2560”, “time_zone_offset”:”-180”, “user_agent”:”Mozilla/5.0 (Macintosh; Intel Mac OS X 14.4; rv:125.0) Gecko/20100101 Firefox/125.0”, “platform”:”Linux x86_64”}`
`email`	String	Optional	Example: test@gmail.com
`birth_day`	String	Optional	Example: 1970-02-17
`selected_language`	String	Optional	Example: en

Response Parameters

Parameter	Type	Description
`result`	String	Possible values: • success — transaction is successfully completed • decline — transaction is declined • redirect — redirect is required • waiting — transaction is being processed • undefined — uncertain payment status due to some problems
`redirect_url`	String	If `result = redirect`, this parameter contains the URL to which the customer must be redirected.
`redirect_params`	Array	If this parameter is returned, the redirect must be performed using the POST method; otherwise, the redirect should be executed using the GET method.
`decline_message`	String	If `result = decline`, this parameter contains the decline message.
`public_id`	String	The unique identifier of the payment.

Callback to Merchant has the same structure as for usual Checkout Integration - please see CHECKOUT -> Integration Flow -> Callback Notification section.