.. meta::
   :description: Hosted Fields integration with Cyber: embed the Hosted Fields JS SDK card fields into the Connecting Party payment page, exchange the card for a hostedFieldsToken and process the transaction with it.

.. _hosted_payment_fields:

Hosted Fields
#############

.. role:: ex

.. role:: code

.. _hosted_payment_fields_introduction:

Introduction
====================================================

In a regular payment form the card number, expiry date and CVV live in the DOM of the Connecting Party page: every script on the page can read them (including third-party ones — analytics, chat widgets, tags), they travel to the Connecting Party server and end up in its logs. Any vulnerability on the page, or a single compromised third-party library, means a card data leak.

Hosted Fields separates the fields from the page by origin. Each card field is a dedicated :ex:`iframe` loaded from the Cyber domain: its content is not accessible to the Connecting Party page code nor to the Connecting Party server. Card data goes straight from the :ex:`iframe` to Cyber and is exchanged there for a **hostedFieldsToken** — a short-lived single-use string the card cannot be reconstructed from.

This page describes how to embed such fields into a payment page, obtain a :ex:`hostedFieldsToken` and process a payment with it, without passing card data through Connecting Party systems. The scheme has four practical implications.

Card data never enters Connecting Party systems
  Not the DOM, the page javascript, the requests to the Connecting Party server, or its logs. This significantly reduces PCI DSS scope.

  .. note:: The applicable Self-Assessment Questionnaire (SAQ) is to be agreed with a QSA — it depends on more than the card data collection method alone.

The Payer stays on the Connecting Party page
  Unlike a redirect to a payment page or a full-page Cyber form, checkout is not interrupted: there are no redirects, the browser address does not change, and the :code:`Pay` button belongs to the Connecting Party page.

Layout and field placement remain under Connecting Party control
  The SDK creates the fields in exactly the :ex:`div` elements specified in the configuration, and knows nothing about how they are arranged. The containers are styled with the Connecting Party page's own css, with no restrictions; the text inside the field is styled through the SDK, see :ref:`Appearance<hosted_payment_fields_appearance>`.

The server side changes in one parameter
  Only the :ex:`hostedFieldsToken` arrives from the browser to the Connecting Party server. The Connecting Party server must still initiate the transaction itself — the token only replaces the card parameters in that call, it does not process a payment on its own. The payment is processed with the same server-to-server call as without Hosted Fields — for example a :ref:`Sale</api/v4/sale/>`, but several other calls accept the token as well: the card parameters — :ex:`credit_card_number`, :ex:`expire_month`, :ex:`expire_year`, :ex:`cvv2` — are replaced with a single :ex:`hosted_fields_token` parameter. The remaining order parameters (:ex:`amount`, :ex:`currency`, :ex:`client_orderid`, :ex:`order_desc`, Payer address and email) are sent unchanged. See :ref:`Step 3<hosted_payment_fields_step3>` for the full list of calls that accept the token.

.. _hosted_payment_fields_prerequisites:

What to Obtain from Cyber
====================================================

:ex:`ENDPOINTID` and :ex:`MERCHANTLOGIN` in the examples are placeholders. Real values are provided by Cyber on onboarding, independently for the sandbox and the production environment.

.. list-table::
   :widths: 25, 75
   :header-rows: 1
   :class: longtable

   * - Parameter
     - Description
   * - Endpoint ID
     - Identifier of the Endpoint the payment is processed on. Used in the URL of server calls and passed on SDK initialization as :ex:`endpointId`.
   * - Merchant login
     - Merchant login provided by Cyber. Sent as :ex:`oauth_consumer_key` when signing requests. The Endpoint must belong to this login.
   * - RSA key pair
     - Needed for signing with OAuth 1.0a RSA-SHA256, the method used in the examples on this page. Two keys generated together, one private and one public: the **private** key signs the requests and must be kept secret from everyone — it never leaves the Connecting Party server; the **public** key is sent to the support manager and is used to verify that a request was signed with the respective private key. This is one of the supported signature methods — others, for example OAuth HMAC-SHA1, use a control key instead of a key pair; see :ref:`Request Authentication Methods<request_authentication_methods>`.
   * - SDK script URL
     - Where the browser loads the SDK and the card fields from: :ex:`https://gate.e-securegate.com/sdk/hosted-fields/latest/index.js` for production, :ex:`https://sandbox.e-securegate.com/sdk/hosted-fields/latest/index.js` for the sandbox.

The keys are generated with a `Key-Pair-Factory tool <https://github.com/payneteasy/key-pair-factory>`_ or :ref:`OpenSSL<rsa_sha256_generating_key_pair_via_openssl>`, see :ref:`Generating Key Pair<rsa_sha256_generating_key_pair>`. The signing procedure is described in :ref:`OAuth RSA-SHA256<RSA-SHA256>`.

.. warning::
  | The RSA **private** key signs server calls and stays on the Connecting Party server. It must never appear in page markup, in page javascript, in a :ex:`data` attribute, in a cookie, or in any response the browser can read.
  | The only credential that crosses into the browser is the :ex:`ephemeralTicket` from :ref:`Step 1<hosted_payment_fields_step1>`, and it is not a cryptographic key of any kind: it is a single-use pass that admits exactly one tokenization on one Endpoint, which is why putting it on the page is safe.

.. _hosted_payment_fields_flow:

Tokenization Flow
====================================================

Three parties take part: the Payer, the Connecting Party — its checkout page and its server — and Cyber — the card fields it embeds as :ex:`iframe` elements inside the Connecting Party page, and the server behind them. The checkout page and the card fields both live in the Payer's browser but belong to different origins, which is what keeps the card data out of reach of the page. The diagram below illustrates the flow on the example of a :ref:`Sale</api/v4/sale/>` call — see (14) for the other calls the same token works with.

.. uml::
  :align: center

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 2
  skinparam ParticipantPadding 30
  actor Payer as Customer
  box "Payer's Browser"
    participant "Connecting Party\nCheckout Page" as Page
    participant "Card Fields\n(3 iframes)" as Fields
  end box
  participant "Connecting Party\nServer" as Merchant
  participant "Cyber" as g
  autonumber
  Customer -> Page: Checkout
  activate Merchant
  == Page preparation ==
  Merchant -> g: Request an ephemeralTicket
  note right of Merchant
    Only an ephemeralTicket is issued here — this step
    does not initiate a transaction by itself
  end note
  activate g
  g --> Merchant: ephemeralTicket
  deactivate g
  Merchant -> Page: Payment page with the ephemeralTicket
  note right
    The RSA private key never leaves the server: only the
    already-issued single-use ephemeralTicket goes to the browser
  end note
  deactivate Merchant
  == Card data entry ==
  Page -> Fields: HostedFields.init()
  Fields --> Page: onReady()
  Customer -> Fields: Enter card data
  note right of Fields
    Card data stays inside the iframes
  end note
  == Tokenization ==
  Customer -> Page: Click "Pay"
  Page -> Fields: sdk.tokenize(ephemeralTicket)
  activate Fields
  Fields -> g: Card data + ephemeralTicket
  activate g
  g --> Fields: hostedFieldsToken
  deactivate g
  Fields --> Page: onToken(hostedFieldsToken)
  deactivate Fields
  == Payment ==
  Page -> Merchant: POST /merchant/pay
  activate Merchant
  Merchant -> g: /api/v4/sale/ with hosted_fields_token
  note right of Merchant
    Tokenization only exchanged the card for a token —
    this Sale call is what actually initiates the transaction
  end note
  activate g
  g --> Merchant: Order ID
  g -> g: Process Sale
  group Get Final Status
    group Receive Connecting Party Callback
      g -> Merchant: Callback with final status
      Merchant --> g: HTTP 200
      deactivate g
    end
    group Order Status Request
      Merchant -> g: Get status by Order ID
      activate g
      g --> Merchant: Final status
      deactivate g
    end
  end
  Merchant --> Page: Payment result
  deactivate Merchant
  Page -> Customer: Show result

| (2,3) The :ex:`ephemeralTicket` is issued for a specific Endpoint, lives for 15 minutes and is consumed by a single tokenization. The request is signed with OAuth 1.0a RSA-SHA256, see :ref:`Step 1. Obtain an ephemeralTicket<hosted_payment_fields_step1>`.
| (4) The :ex:`ephemeralTicket` is safe to expose in the browser; the RSA private key is not, see the :ref:`warning above<hosted_payment_fields_prerequisites>`.
| (5,6) The SDK creates one :ex:`iframe` per specified :ex:`div` and calls :ex:`onReady` once all of them have loaded — see :ref:`Step 2. Fields and Tokenization<hosted_payment_fields_step2>`.
| (7) Entered values never leave the Cyber windows: neither the DOM, nor the page javascript, nor the Connecting Party server can see them, see :ref:`Restrictions<hosted_payment_fields_restrictions>`.
| (9,12) :ex:`sdk.tokenize()` asks the :ex:`pan` field to collect the values of all fields and exchange them for a :ex:`hostedFieldsToken`; the result is delivered back to the page through :ex:`onToken`, see :ref:`Step 2<hosted_payment_fields_step2>`.
| (10) The :ex:`pan` field collects the values of all three fields: the neighbouring :ex:`iframe` elements are loaded from the same origin and read each other directly, bypassing the Connecting Party page.
| (11) A :ex:`hostedFieldsToken` is returned — a string of up to 2048 characters, valid for 5 minutes, that the card cannot be reconstructed from. The :ex:`ephemeralTicket` is spent at this point: a new payment attempt requires a new one.
| (13) This is the Connecting Party's own server endpoint, not Cyber's — its name and format are entirely up to the Connecting Party, see the :ex:`sendHostedFieldsTokenToServer` call in :ref:`Step 2<hosted_payment_fields_step2>`.
| (14) This call is what actually initiates the transaction — tokenization by itself only exchanged the card for a token. A regular Sale request, but with :ex:`hosted_fields_token` instead of the card parameters, see :ref:`Step 3. Payment with the hostedFieldsToken<hosted_payment_fields_step3>`.
| (15) The response is asynchronous: it carries the Order ID, but not the payment status. See :ref:`Async-Response<asynchronous_response>`.
| (17,18) To implement callback with final status handling see :ref:`Connecting Party Callback<merchant_callbacks>`.
| (19,20) To implement order status request see :ref:`Order Status Request</api/v2/status/>` by Order ID. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.

The same flow as an interactive diagram — step by step, with the request and the response of each step:

.. raw:: html

   <link rel="stylesheet" href="../_static/hf-flow/hf-flow.css">
   <script src="../_static/hf-flow/hf-flow.js"></script>
   <div class="hf-flow"
        data-payment-gateway-name="Cyber"
        data-pg-domain="sandbox.e-securegate.com"
        data-merchant-domain="merchant.com"
        data-api-context="/paynet"
        data-assets-path="/sdk/hosted-fields/latest"
        data-panel-height="34vh"></div>

.. _hosted_payment_fields_integration:

Integration
====================================================

Reference merchant integrations are published on `GitHub <https://github.com/payneteasy/hosted-fields-examples>`_ — the same payment, the same screens, the same flow, differing in the server stack and in whether the page is plain javascript or React: PHP, Node.js (Express), Python (Flask), .NET (ASP.NET Core), Go, Ruby (Sinatra), Java (Spring Boot), Kotlin (Ktor) and Rust (axum), plus React pages on Next.js and on Go. They cover all three steps below, the OAuth 1.0a signature included, and are a working starting point for your own.

.. _hosted_payment_fields_step1:

Step 1. Obtain an ephemeralTicket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :ex:`ephemeralTicket` is issued for a specific Endpoint, lives for 15 minutes and is consumed by a single tokenization. The Connecting Party server requests it with the :ref:`/api/v4/tokenize/create-ephemeral-ticket</api/v4/tokenize/create-ephemeral-ticket/>` call: the URLs, the request, the response and the errors are described there. The request is signed the same way as other server calls — in the examples here with :ref:`OAuth 1.0a RSA-SHA256<RSA-SHA256>`; other signature methods are supported as well, see :ref:`Request Authentication Methods<request_authentication_methods>`.

The :ex:`ephemeralTicket` is then embedded into the page being served — into a javascript variable or a :ex:`data` attribute. It is safe to expose in the browser: it allows exactly one tokenization on the given Endpoint, after which it is withdrawn.

.. warning:: Issue a new :ex:`ephemeralTicket` for every payment attempt. It is not a session credential and must not be cached, reused between Payers, or handed out to a page that is not about to take a card. The key that signs this very request is a different thing and stays on the server, see the :ref:`warning above<hosted_payment_fields_prerequisites>`.

.. warning:: The clock of the Connecting Party server must be accurate: :ex:`oauth_timestamp` outside the permitted window (10 minutes by default) is rejected, and a repeated :ex:`oauth_nonce` is rejected as well.

.. _hosted_payment_fields_step2:

Step 2. Fields and Tokenization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Markup: an empty :ex:`div` per field, the payment button, and an element for the error message. The :ex:`hf-field` class should be present in the markup from the start — the SDK sets it as well, but until the :ex:`iframe` loads the container would otherwise have zero height and the layout would jump. The payment button starts disabled and is enabled from :ex:`onReady`.

.. code-block:: html

  <label for="cardNumber">Card number</label>
  <div id="cardNumber" class="hf-field"></div>

  <label for="expiryDate">Expiry date</label>
  <div id="expiryDate" class="hf-field"></div>

  <label for="cvv">CVV</label>
  <div id="cvv" class="hf-field"></div>

  <button id="pay" type="button" disabled>Pay</button>
  <p id="formError" class="form-error"></p>

  <script src="https://sandbox.e-securegate.com/sdk/hosted-fields/latest/index.js"></script>

The script URL carries no parameters. The fields build the tokenization address themselves — from their own address, the :ex:`endpointId`, and the context path of the installation, which travels inside the :ex:`ephemeralTicket`. None of it comes from the :ex:`init` options, so a value taken from page javascript cannot redirect the card data, see :ref:`Restrictions<hosted_payment_fields_restrictions>`. Cyber rejects a ticket issued on another installation (error :ex:`4003`).

.. note:: The script tag above is synchronous and placed at the end of :ex:`<body>`, so :ex:`HostedFields` is available to the next :ex:`<script>` immediately. For :ex:`async` or :ex:`defer` loading see :ref:`Loading the SDK<hosted_payment_fields_loading>`.

.. code-block:: css

  /* the field container is a regular element of the Connecting Party page */
  .hf-field {
      height       : 48px;
      box-sizing   : border-box;
      border       : 1px solid #d5dae1;
      border-radius: 8px;
      background   : #fff;
  }
  .hf-field iframe  { display: block; width: 100%; height: 100%; border: 0; }
  .hf-field--focus  { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37, 99, 235, .18);
                      outline: none; }
  .hf-field--filled { border-color: #b9c0ca; }
  .hf-field--error  { border-color: #dc2626; }

  .form-error { margin: 4px 0 0; font-size: 12px; color: #dc2626; }

.. note:: :ex:`.hf-field--error` is set and removed by the SDK itself — on every field, on a failed tokenization — so the page only has to style it. See :ref:`State Classes on the Container<hosted_payment_fields_state_classes>`.

Initialization and result handling.

.. code-block:: javascript

  //embedded by the Connecting Party server when serving the page
  const ENDPOINT_ID   = 'ENDPOINTID';  //Endpoint identifier provided by Cyber
  const EPHEMERAL_KEY = '...';         //single-use ephemeralTicket from Step 1

  const FIELD_STYLE = {
      input      : {fontFamily: 'Helvetica, Arial, sans-serif', fontSize: '16px', color: '#1f2937',
                    padding: '0 13px'},
      placeholder: {color: '#9aa4b2'},
      focus      : {outline: 'none'}
  };

  const payButton = document.getElementById('pay');

  const sdk = HostedFields.init({
      endpointId: ENDPOINT_ID,
      fields    : {
          cardNumber: {type: 'pan', placeholder: '1234 1234 1234 1234', style: FIELD_STYLE},
          expiryDate: {type: 'exp', style: FIELD_STYLE},
          cvv       : {type: 'cvv', style: FIELD_STYLE}
      },
      onReady: () => {payButton.disabled = false;},
      onToken: sendHostedFieldsTokenToServer,
      onError: showError
  });

  payButton.addEventListener('click', () => {
      clearErrors();
      payButton.disabled = true;               //one tokenization per ephemeralTicket
      sdk.tokenize(EPHEMERAL_KEY);
  });

  //the hostedFieldsToken is received - send it to the Connecting Party server, Step 3;
  //showPaymentResult is the Connecting Party page code displaying the result to the Payer
  function sendHostedFieldsTokenToServer(hostedFieldsToken) {
      fetch('/merchant/pay', {
          method : 'POST',
          headers: {'Content-Type': 'application/x-www-form-urlencoded'},
          body   : new URLSearchParams({hosted_fields_token: hostedFieldsToken})
      }).then(response => response.text()).then(showPaymentResult);
  }

  //onError receives a HostedFieldsError: message and tip are for the log,
  //payerMessage is the only part safe to show to the Payer - and it is not always present
  function showError(error) {
      console.error(`[HostedFields] ${error.code}: ${error.message}`, error.tip, error.field);
      document.getElementById('formError').textContent =
          error.payerMessage || 'The payment could not be completed. Please try again.';
      payButton.disabled = false;
  }

  function clearErrors() {
      document.getElementById('formError').textContent = '';
  }

.. warning:: A failed tokenization spends the :ex:`ephemeralTicket` only if Cyber has already accepted the card data. After any :ex:`onError` in the :ex:`4xxx` range, request a new :ex:`ephemeralTicket` (Step 1) before letting the Payer press :code:`Pay` again — reloading the page with a fresh key is the simplest way to do it.

The SDK is loaded from the Cyber host and must not be copied to the Connecting Party page's domain: it derives from its own script address where to load the card fields from and whose messages to accept. A copy hosted on the Connecting Party page's domain would create the fields on that same domain — that is, the very form the integration is meant to replace — so :ex:`init` refuses to start in that case (error :ex:`1009`).

.. note:: If CSP is configured on the page, allow the Cyber domain in :ex:`script-src` (loading :ex:`index.js`) and in :ex:`frame-src` (the fields themselves).

.. _hosted_payment_fields_step3:

Step 3. Payment with the hostedFieldsToken
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :ex:`hostedFieldsToken` is placed into a regular payment request in the :ex:`hosted_fields_token` parameter — for example a :ref:`Sale</api/v4/sale/>`; the calls that accept the token are listed :ref:`below<hosted_payment_fields_step3_calls>`. The card number, expiry date and CVV are not sent — they are not available to the Connecting Party, and the Payment Gateway takes them from the token. The request is signed as usual for the chosen call. The parameter, the rules the request must follow and a request example are described on the page of each call.

.. _hosted_payment_fields_step3_calls:

The token is accepted in place of the card parameters by the following calls.

.. list-table::
   :widths: 35, 25, 40
   :header-rows: 1
   :class: longtable

   * - Call
     - Parameter
     - Notes
   * - :ref:`/api/v4/sale/<api_v4_sale_hosted_fields_parameters>`
     - :ex:`hosted_fields_token`
     -
   * - :ref:`/api/v2/sale/<api_v2_sale_hosted_fields_parameters>`
     - :ex:`hosted_fields_token`
     -
   * - :ref:`/api/v2/preauth/<api_v2_preauth_hosted_fields_parameters>`
     - :ex:`hosted_fields_token`
     -
   * - :ref:`/api/v4/transfer/<transfer_hosted_fields_parameters>`
     - :ex:`destination-hosted-fields-token`
     - Receiver card only, and only for :ex:`deposit2card` (D2C). :ex:`destination_expire_month` and :ex:`destination_expire_year` must not be sent.

The response is asynchronous: it carries the Order ID, but not the payment status, see :ref:`Async-Response<asynchronous_response>`. The final status is requested with a separate :ref:`Order Status Request</api/v2/status/>` or delivered as a :ref:`Connecting Party Callback<merchant_callbacks>`.

.. note:: Tokenization alone does not initiate a transaction — the Connecting Party server must still send a Sale (or another call from the table above) to actually process the payment.

.. _hosted_payment_fields_reference_section:

SDK Reference
====================================================

The SDK exposes a single object, :ex:`HostedFields`, with a single method, :ex:`init`.

.. _hosted_payment_fields_loading:

Loading the SDK
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:ex:`window.HostedFields` appears when the script has executed, and the SDK announces itself in two more ways so that :ex:`async` and :ex:`defer` loading do not require polling. Pick whichever fits the page.

.. list-table::
   :widths: 30, 70
   :header-rows: 1
   :class: longtable

   * - Way
     - When to use
   * - Synchronous :ex:`<script src>`
     - The simplest one. Place the tag at the end of :ex:`<body>`: :ex:`HostedFields` is available to the next :ex:`<script>` immediately.
   * - :ex:`window.onHostedFieldsReady`
     - Define this function **before** the SDK script tag; the SDK calls it once with the API object. Works with :ex:`async` and :ex:`defer`.
   * - :ex:`hosted-fields:ready` event on :ex:`document`
     - For several independent listeners, or for a CSP without :ex:`unsafe-inline`. The API object is in :ex:`event.detail`.

.. code-block:: html

  <script>
    window.onHostedFieldsReady = function (HostedFields) {
      var sdk = HostedFields.init({/* ... */});
    };
  </script>
  <script src="https://sandbox.e-securegate.com/sdk/hosted-fields/latest/index.js" async></script>

.. code-block:: html

  <script>
    document.addEventListener('hosted-fields:ready', function (event) {
      var sdk = event.detail.init({/* ... */});
    });
  </script>
  <script src="https://sandbox.e-securegate.com/sdk/hosted-fields/latest/index.js" async></script>

.. warning:: The SDK must be loaded with a classic :ex:`<script src>` tag — synchronous, :ex:`async`, :ex:`defer` or inserted dynamically. It is not an ES module and is not published as an npm package: the origin of the card fields is derived from :ex:`document.currentScript`, which is :ex:`null` in a module or in a bundler build (error :ex:`1006`).

.. note:: :ex:`init` waits for :ex:`DOMContentLoaded` internally, so it may be called from the :ex:`<head>` — the field containers do not have to exist yet at that moment.

HostedFields.init(options)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :widths: 20, 10, 70
   :header-rows: 1
   :class: longtable

   * - Parameter
     - Required
     - Description
   * - :ex:`endpointId`
     - yes
     - Endpoint identifier. Without it :ex:`init` throws :ex:`1001` immediately instead of deferring the error until the payment button is pressed.
   * - :ex:`fields`
     - yes
     - :ex:`{<div id>: <field description>}` — which fields to create and in which containers. A field description is either a type string (:ex:`'pan'`) or an object :ex:`{type, placeholder, style}`. A :ex:`pan` field is mandatory (:ex:`1008`).
   * - :ex:`onToken`
     - yes
     - :ex:`function(hostedFieldsToken)` — tokenization succeeded.
   * - :ex:`onError`
     - yes
     - :ex:`function(error)` — tokenization or field loading failed; :ex:`error` is a :ref:`HostedFieldsError<hosted_payment_fields_errors>`.
   * - :ex:`onReady`
     - no
     - :ex:`function()` — called once when every field :ex:`iframe` has loaded. The natural place to enable the payment button.
   * - :ex:`loadTimeout`
     - no
     - How long to wait for a field to load, in milliseconds. Default :ex:`10000`; exceeding it produces :ex:`2001` or :ex:`2002`.

:ex:`init` may be called only once per page; a second call throws :ex:`1010` until :ex:`destroy()` is called. The method returns an object with three methods and one promise.

.. list-table::
   :widths: 30, 70
   :header-rows: 1
   :class: longtable

   * - Member
     - Description
   * - :ex:`tokenize(ephemeralTicket)`
     - Asks the :ex:`pan` field to collect the values of all fields and exchange them for a :ex:`hostedFieldsToken`. :ex:`ephemeralTicket` is the single-use key from :ref:`Step 1<hosted_payment_fields_step1>`. The result is delivered to :ex:`onToken` or :ex:`onError`. A second call while the first is still running is ignored with warning :ex:`2008`; a response that does not arrive within 30 seconds produces :ex:`2005`.
   * - :ex:`setStyle(divId, style)`
     - Changes the styling of an already created field on the fly. An unknown :ex:`divId` is reported as warning :ex:`5003`.
   * - :ex:`destroy()`
     - Removes the :ex:`iframe` elements, the state classes, the ARIA attributes and the injected stylesheet, and unsubscribes from messages. Idempotent; :ex:`tokenize` and :ex:`setStyle` after it are ignored with warning :ex:`5006`. After :ex:`destroy()` a new :ex:`init` is allowed.
   * - :ex:`ready`
     - A promise fulfilled at the same moment as :ex:`onReady` and rejected with the first field loading error. An alternative to the callback, convenient with :ex:`await`.

.. note:: :ex:`ready` is created whether or not it is used. If the fields fail to load and nothing is attached to it, the browser console will additionally show an unhandled promise rejection next to the :ex:`onError` call — attach a :ex:`.catch()` if that noise is unwanted.

Field Types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :widths: 15, 25, 60
   :header-rows: 1
   :class: longtable

   * - Type
     - Default placeholder
     - Input and formatting
   * - :ex:`pan`
     - :ex:`Card number`
     - - Digits only, 19 maximum, split into groups of 4.
       - The spaces between groups are decoration: :ex:`Backspace` removes the digit before the space, :ex:`Delete` removes the digit after it.
   * - :ex:`exp`
     - :ex:`MM / YY`
     - - Digits only, 4 maximum, displayed as :ex:`MM / YY`.
       - The separator is a position rather than a character: it can neither be deleted nor typed, it can only be stepped over — with the arrow keys or with :ex:`Space`.
   * - :ex:`cvv`
     - :ex:`CVV`
     - Digits only, 4 maximum.

The :ex:`pan` field is mandatory: it initiates the tokenization and collects the values from its neighbours. Exactly four values are sent to Cyber: :ex:`pan`, :ex:`expMonth`, :ex:`expYear`, :ex:`cvv`. No other field types are provided by the SDK — the cardholder name, email and other order data remain regular fields of the Connecting Party form and are sent from the Connecting Party server in the Sale request.

A non-empty :ex:`placeholder` in the field description overrides the default value. An unknown type throws :ex:`1004`.

.. _hosted_payment_fields_state_classes:

State Classes on the Container
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The state of a field is only visible to its :ex:`iframe`: focus and input happen in a foreign window, so :ex:`:focus-within` and :ex:`:has()` do not reach the Connecting Party page. Instead, the SDK toggles classes on the container.

.. list-table::
   :widths: 30, 70
   :header-rows: 1
   :class: longtable

   * - Class
     - Description
   * - :ex:`hf-field`
     - Always — set when the :ex:`iframe` is created. Should be present in the markup as well.
   * - :ex:`hf-field--focus`
     - The field is focused.
   * - :ex:`hf-field--filled`
     - Something has been entered into the field.
   * - :ex:`hf-field--error`
     - Tokenization failed. Set by the SDK on **every** field at once, because a tokenization error is not attributed to a particular one; removed on the next successful tokenization.

The SDK also sets :ex:`role="group"` and an :ex:`aria-label` (:ex:`Card number`, :ex:`Expiry date`, :ex:`CVV`) on each container, and :ex:`aria-invalid` alongside :ex:`hf-field--error`.

.. note:: To keep the field keyboard-accessible when the page defines no focus style of its own, the SDK injects a default focus outline for :ex:`.hf-field--focus`. The rule is inserted as the first stylesheet in :ex:`<head>`, so any page rule of the same specificity overrides it. If you draw your own focus indicator, add :ex:`outline: none` to your :ex:`--focus` rule; do not remove the indicator without a replacement.

.. note:: Custom modifiers of your own (for example :ex:`hf-field--invalid`) are added and removed by the Connecting Party page; the SDK does not touch them.

.. _hosted_payment_fields_appearance:

Appearance
====================================================

Customization is split in two by the domain boundary.

**The container and the iframe element belong to the Connecting Party DOM.** Size, border, background, corner radius, shadow, :ex:`:hover`, transitions and animations, resize behaviour — plain css of the Connecting Party page, with no restrictions here. The field page is deliberately transparent, with no background or border of its own.

**The content of the field lives in the Cyber window.** Connecting Party css does not reach inside; only what is passed through the SDK in the :ex:`style` sections gets in.

Style Sections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :widths: 25, 75
   :header-rows: 1
   :class: longtable

   * - Section
     - Description
   * - :ex:`input`
     - Inline style of the :ex:`<input>` itself.
   * - :ex:`placeholder`
     - The :ex:`::placeholder` rule inside the field.
   * - :ex:`focus`
     - The :ex:`:focus` rule inside the field.

Allowed Properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Only cosmetics is allowed inside the field.

.. list-table::
   :widths: 25, 75
   :header-rows: 1
   :class: longtable

   * - Group
     - Properties
   * - Colour
     - :ex:`color`, :ex:`backgroundColor`, :ex:`caretColor`
   * - Font
     - :ex:`font`, :ex:`fontFamily`, :ex:`fontSize`, :ex:`fontStyle`, :ex:`fontWeight`, :ex:`fontVariant`, :ex:`fontVariantNumeric`
   * - Tracking and line
     - :ex:`letterSpacing`, :ex:`wordSpacing`, :ex:`lineHeight`
   * - Text
     - :ex:`textAlign`, :ex:`textTransform`
   * - Padding and border
     - :ex:`padding`, :ex:`paddingTop`, :ex:`paddingRight`, :ex:`paddingBottom`, :ex:`paddingLeft`, :ex:`border`, :ex:`borderColor`, :ex:`borderRadius`, :ex:`outline`
   * - Other
     - :ex:`transition`

A property name is accepted both in camelCase and in kebab-case: :ex:`fontSize` and :ex:`font-size` are the same thing.

.. warning:: A value must be a string and must not contain :ex:`;`, :ex:`{`, :ex:`}`, :ex:`<`, :ex:`>`, :ex:`url(` or :ex:`expression(`. A property failing the check is dropped with warning :ex:`5001` or :ex:`5002` in the browser console; the rest are applied and the field keeps working.

Examples
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Basic Styling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: javascript

  const FIELD_STYLE = {
      input      : {
          fontFamily        : '-apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
          fontSize          : '16px',
          fontVariantNumeric: 'tabular-nums',
          color             : '#1f2937',
          caretColor        : '#2563eb',
          padding           : '0 13px'
      },
      placeholder: {color: '#9aa4b2'},
      focus      : {outline: 'none'}
  };

  const sdk = HostedFields.init({
      endpointId: ENDPOINT_ID,
      fields    : {
          cardNumber: {type: 'pan', placeholder: '1234 1234 1234 1234',
                       style: {...FIELD_STYLE, input: {...FIELD_STYLE.input, letterSpacing: '0.5px'}}},
          expiryDate: {type: 'exp', style: FIELD_STYLE},
          //CVV is short - centred it looks better
          cvv       : {type: 'cvv',
                       style: {...FIELD_STYLE, input: {...FIELD_STYLE.input, textAlign: 'center'}}}
      },
      onReady: () => {payButton.disabled = false;},
      onToken: sendHostedFieldsTokenToServer,
      onError: showError
  });

.. _hosted_payment_fields_field_states:

Field States
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Focus, filled state and error are drawn by Connecting Party css through the container classes — the border and the shadow are laid out as usual. The base :ex:`.hf-field`, :ex:`--focus`, :ex:`--filled` and :ex:`--error` rules are defined in :ref:`Step 2<hosted_payment_fields_step2>`; :ex:`:hover` and transitions are added here.

.. code-block:: css

  .hf-field {
      height       : 48px;
      box-sizing   : border-box;
      border       : 1px solid #d5dae1;
      border-radius: 8px;
      background   : #fff;
      transition   : border-color .15s, box-shadow .15s;
  }
  /* :hover is more specific, without :not() it would repaint the focused field border back to grey */
  .hf-field:hover:not(.hf-field--focus):not(.hf-field--error) { border-color: #b9c0ca; }
  .hf-field--filled { border-color: #b9c0ca; }
  .hf-field--focus  { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37, 99, 235, .18);
                      outline: none; }
  .hf-field--error  { border-color: #dc2626; }

Highlighting After a Decline
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The border is painted by Connecting Party css from the :ex:`hf-field--error` class the SDK sets, while the text inside the field is only reachable through :ex:`setStyle`. This is an extended version of :ex:`showError` / :ex:`clearErrors` from :ref:`Step 2<hosted_payment_fields_step2>`: repainting the input itself is added to the message below the form.

.. code-block:: javascript

  function showError(error) {
      console.error(`[HostedFields] ${error.code}: ${error.message}`, error.tip, error.field);
      document.getElementById('formError').textContent =
          error.payerMessage || 'The payment could not be completed. Please try again.';
      sdk.setStyle('cardNumber', cardNumberStyle('#dc2626'));
      payButton.disabled = false;
  }

  function clearErrors() {
      document.getElementById('formError').textContent = '';
      sdk.setStyle('cardNumber', cardNumberStyle('#1f2937'));
  }

  function cardNumberStyle(color) {
      return {
          input      : {...FIELD_STYLE.input, letterSpacing: '0.5px', color: color},
          placeholder: FIELD_STYLE.placeholder,
          focus      : FIELD_STYLE.focus
      };
  }

.. warning:: :ex:`setStyle` overwrites the field styling completely: the previous inline style is dropped, and the :ex:`::placeholder` and :ex:`:focus` rules are rebuilt from scratch based on what you pass — include every section you want to keep, not only the one that changed. The placeholder text itself (set via the field's :ex:`placeholder` option) is untouched by :ex:`setStyle`.

.. _hosted_payment_fields_errors:

Errors
====================================================

:ex:`onError` receives a :ex:`HostedFieldsError` object — an :ex:`Error` subclass with a stable numeric code, so an integration reacts to :ex:`error.code` rather than to a text.

.. list-table::
   :widths: 20, 80
   :header-rows: 1
   :class: longtable

   * - Property
     - Description
   * - :ex:`code`
     - Numeric code from the registry below. Stable: a code is never reused for another meaning.
   * - :ex:`message`
     - Developer-facing description, in English. **Not** for showing to the Payer.
   * - :ex:`tip`
     - What to check. Developer-facing as well. Filled in by the SDK from its own registry by :ex:`code`, not sent by Cyber.
   * - :ex:`payerMessage`
     - The only part safe to show to the Payer, and only present for some errors — :ex:`3001` and :ex:`4004` carry one. Also filled in by the SDK, because Cyber messages are English-only. When it is absent, show your own generic text.
   * - :ex:`field`
     - The :ex:`div id` of the field the error relates to, when it relates to one.

:ex:`String(error)` gives :ex:`[HostedFields] <code>: <message>`.

Codes are grouped into ranges, and the range determines how the error reaches the integration.

.. list-table::
   :widths: 15, 30, 55
   :header-rows: 1
   :class: longtable

   * - Range
     - Channel
     - Meaning
   * - :ex:`1xxx`
     - Thrown by :ex:`init`
     - Configuration: wrong options or wrong loading. Happens before any :ex:`iframe` is created, and is a mistake in the integration rather than a runtime condition. The exception is :ex:`1005`, which depends on the markup and therefore goes to :ex:`onError`.
   * - :ex:`2xxx`
     - :ex:`onError`
     - Environment and field lifecycle: loading, handshake, timeouts.
   * - :ex:`3xxx`
     - :ex:`onError`
     - What the Payer entered. Carries :ex:`payerMessage`.
   * - :ex:`4xxx`
     - :ex:`onError`
     - Cyber declined the tokenization.
   * - :ex:`5xxx`
     - :ex:`console.warn`
     - Diagnostics that do not stop the payment. Never reaches :ex:`onError`.

.. _hosted_payment_fields_error_codes:

Error Codes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :widths: 10, 45, 45
   :header-rows: 1
   :class: longtable

   * - Code
     - Message
     - What to do
   * - :ex:`1001`
     - :code:`endpointId is required`
     - Pass :ex:`endpointId` in the :ex:`init` options.
   * - :ex:`1002`
     - :code:`onToken must be a function`
     - Pass a callback as :ex:`onToken`.
   * - :ex:`1003`
     - :code:`fields must be a non-empty object`
     - Describe at least one field in :ex:`fields`.
   * - :ex:`1004`
     - :code:`unknown field type "X" for #divId`
     - Expected :ex:`pan`, :ex:`exp` or :ex:`cvv`.
   * - :ex:`1005`
     - :code:`element #divId not found`
     - The container is missing from the markup. Note that :ex:`init` already waits for :ex:`DOMContentLoaded`, so this is a real absence, not a race.
   * - :ex:`1006`
     - :code:`cannot detect script origin`
     - The SDK was loaded not as a classic :ex:`<script src>` — as an ES module or through a bundler, see :ref:`Loading the SDK<hosted_payment_fields_loading>`.
   * - :ex:`1007`
     - :code:`invalid segment: X`
     - The context path inside the :ex:`ephemeralTicket` is not a single path segment matching :ex:`^[a-z0-9-]{1,32}$`. The ticket is malformed — obtain a new one, see :ref:`Step 1<hosted_payment_fields_step1>`.
   * - :ex:`1008`
     - :code:`pan field is not configured`
     - Tokenization is initiated by the :ex:`pan` field, so it cannot be omitted.
   * - :ex:`1009`
     - :code:`SDK is loaded from the merchant origin`
     - :ex:`index.js` was copied to the Connecting Party domain. Load it from the Cyber host, see :ref:`Step 2<hosted_payment_fields_step2>`.
   * - :ex:`1010`
     - :code:`init() has already been called`
     - Call :ex:`destroy()` before initializing again.
   * - :ex:`1011`
     - :code:`field endpoint/type query is missing`
     - Internal: an :ex:`iframe` of a card field was created by something other than the SDK. Reported in the console of the field, not through :ex:`onError`.
   * - :ex:`2001`
     - :code:`field #divId iframe failed to load`
     - The :ex:`iframe` never loaded within :ex:`loadTimeout`. Check the CSP :ex:`frame-src` and network access to the Cyber host.
   * - :ex:`2002`
     - :code:`field #divId loaded but sent no handshake`
     - Something loaded at that address, but it is not a card field — most often a :code:`404` page. Check the SDK script URL.
   * - :ex:`2003`
     - :code:`field protocol version N is not supported`
     - The SDK and the field page are from different releases. Reload the page; if it persists, report it to support.
   * - :ex:`2004`
     - :code:`card fields are not loaded yet`
     - :ex:`tokenize` was called before the fields were ready. Enable the payment button from :ex:`onReady`.
   * - :ex:`2005`
     - :code:`tokenize timed out`
     - No response within 30 seconds. Let the Payer try again with a new :ex:`ephemeralTicket`.
   * - :ex:`2006`
     - :code:`field #divId became ready after the load timeout`
     - A warning-grade condition on a slow connection: increase :ex:`loadTimeout`.
   * - :ex:`2007`
     - :code:`payment token arrived after tokenize timed out and was discarded`
     - The :ex:`ephemeralTicket` has been spent, but the token came too late to be used. Request a new :ex:`ephemeralTicket` for the next attempt.
   * - :ex:`2008`
     - :code:`tokenize is already in progress`
     - The second :code:`Pay` click. Disable the button until :ex:`onToken` or :ex:`onError`.
   * - :ex:`3001`
     - :code:`expiry date is incomplete`
     - The expiry date is entered partially. An incomplete value is not sent: :ex:`3` would otherwise be submitted as the year 2003. Carries a :ex:`payerMessage`.
   * - :ex:`3002`
     - :code:`field exp not found` / :code:`field cvv not found`
     - The field is described in :ex:`fields`, but its container is missing from the markup, so the :ex:`pan` field has nothing to collect the value from.
   * - :ex:`4001`
     - :code:`ephemeral ticket expired or already spent`
     - The :ex:`ephemeralTicket` is older than 15 minutes or has already been used. Request a new one.
   * - :ex:`4002`
     - :code:`endpointId does not match the ticket`
     - The :ex:`endpointId` passed to :ex:`init` is not the one the :ex:`ephemeralTicket` was issued for.
   * - :ex:`4003`
     - :code:`segment does not match endpoint owner`
     - The :ex:`ephemeralTicket` was issued on another installation of Cyber. Request one on the installation the :ex:`endpointId` belongs to.
   * - :ex:`4004`
     - :code:`card data rejected by the platform`
     - The card did not pass the Cyber checks — a too short number, an expired card, a non-numeric CVV. Carries a :ex:`payerMessage`. The :ex:`ephemeralTicket` is spent, so a new attempt needs a new one.
   * - :ex:`4900`
     - The Cyber response as it is
     - Any other decline of the tokenization. The text is a raw platform response: log it and show the Payer your own generic message, not this.
   * - :ex:`5001`
     - :code:`style property is not allowed: X`
     - Property :ex:`X` is outside the allowed list, see :ref:`Appearance<hosted_payment_fields_appearance>`. The remaining properties are applied and the field keeps working.
   * - :ex:`5002`
     - :code:`style value is not allowed: X=Y`
     - The value is not a string, or it contains :ex:`;`, :ex:`{`, :ex:`}`, :ex:`<`, :ex:`>`, :ex:`url(` or :ex:`expression(`.
   * - :ex:`5003`
     - :code:`setStyle: unknown divId "X"`
     - The :ex:`divId` does not match any key of the :ex:`fields` map.
   * - :ex:`5004`
     - :code:`container #divId already holds a field iframe`
     - :ex:`init` was called twice for the same container. The old :ex:`iframe` is removed.
   * - :ex:`5005`
     - :code:`malformed field_event message`
     - A symptom of a version mismatch between the SDK and the field page.
   * - :ex:`5006`
     - :code:`tokenize called after destroy()` / :code:`setStyle called after destroy()`
     - The instance has already been destroyed; call :ex:`init` again to get a new one.

.. note:: Whatever the code inside the :ex:`4xxx` range, the :ex:`ephemeralTicket` is spent: obtain a new one before letting the Payer try again. What differs is what else to do — :ex:`4001` and :ex:`4900` mean retry, :ex:`4002` and :ex:`4003` are integration mistakes that a retry will not fix, and :ex:`4004` means the Payer has to correct the card.

.. _hosted_payment_fields_restrictions:

Restrictions
====================================================

The restrictions below are not a shortcoming but the very reason the scheme exists: everything listed would either take card data outside the Cyber window or allow a genuine field to be replaced with a counterfeit one. If any of them blocks a scenario, contact Cyber support instead of working around it.

.. list-table::
   :widths: 40, 60
   :header-rows: 1
   :class: longtable

   * - Not available
     - Reason
   * - Reading the field value, whole or character by character
     - This is the card data itself: the card number, expiry date and CVV. Only the event name (:ex:`focus`, :ex:`blur`, :ex:`input`) and the "field is empty" flag leave the field.
   * - Receiving the input content in a custom handler (:ex:`keydown`, :ex:`input`, :ex:`change`)
     - A handler with access to the value leaks the card number digit by digit — the isolation is bypassed without a single hacking attempt. The :ex:`input` event is delivered as a state class change, but without the value and without its length.
   * - Setting the address the tokenization is sent to
     - The field derives it from its own address, the :ex:`endpointId` it was loaded with, and the context path carried inside the :ex:`ephemeralTicket` — never from the :ex:`init` options. The context path must be a single :ex:`^[a-z0-9-]{1,32}$` path segment, so it cannot point the request at another host. Otherwise an XSS on the Connecting Party page would be enough to divert a card to a foreign server.
   * - Serving the SDK from the Connecting Party domain
     - A same-origin copy would create the fields on the Connecting Party domain — the very form the integration replaces. :ex:`init` refuses to start (:ex:`1009`).
   * - Inside the field: positioning, dimensions, :ex:`opacity`, :ex:`visibility`, :ex:`clip`, :ex:`transform`, negative margins
     - These properties hide the genuine field and put a foreign one in its place: the Payer sees a regular form and enters the card into a counterfeit. The size and position of the field itself are set by the container, where there are no restrictions.
   * - Loading an external resource inside the field (:ex:`url(...)`)
     - A request to an external address from the window where the card is entered is a ready-made leak channel.
   * - Modifying or reading the internal markup of the field
     - It is a Cyber document and may change at any moment; its structure must not be relied upon.
   * - Reaching the field content through :ex:`iframe.contentDocument` or :ex:`frames[...]`
     - It is a window of another domain: the browser denies access (:ex:`SecurityError`) and the restriction cannot be bypassed. The fields are managed through the object returned by :ex:`init`.
   * - Performing two tokenizations with one :ex:`ephemeralTicket`
     - The key is single-use; a new payment attempt requires a new one.

Troubleshooting
====================================================

Error codes are listed in :ref:`Error Codes<hosted_payment_fields_error_codes>`. The table below covers the symptoms that come without one.

.. list-table::
   :widths: 40, 60
   :header-rows: 1
   :class: longtable

   * - Symptom
     - Troubleshooting
   * - A server call is rejected with :code:`error-id=...` and :code:`message=...`, :code:`401`
     - The request failed the signature check or authentication. Most common: the server clock is outside the :ex:`oauth_timestamp` window, :ex:`oauth_nonce` is reused, the Endpoint does not belong to the login from :ex:`oauth_consumer_key`, or a wrong public key is configured on the Endpoint. See :ex:`message` for the reason and quote :ex:`error-id` to support.
   * - The signature is accepted, but :ex:`create-ephemeral-ticket` returns no ticket
     - Check the :ex:`endpointId` and its settings on the Cyber side: tokenization must be enabled on this Endpoint, and the Endpoint must belong to the login the request is signed with.
   * - A Sale request is rejected with :code:`At most one of ... should be set.`
     - The request carries a second source of card data next to :ex:`hosted_fields_token` — a card number, a :ex:`temporary_card_record_id` or a :ex:`card_recurring_payment_id`, see the rules on the page of the call, listed in :ref:`Step 3<hosted_payment_fields_step3_calls>`.
   * - A Sale request is rejected with :code:`When 'hosted_fields_token' present ... should not be set.`
     - :ex:`expire_month`, :ex:`expire_year` or :ex:`cvv2` is still being sent. They come from the token and must be removed from the request.
   * - A Sale request is declined with a reference to the token
     - The :ex:`hostedFieldsToken` has expired (5 minutes) or has already been spent — for example, the form was submitted to the server twice. Every payment requires its own tokenization.
   * - The fields do not appear, a script or frame loading error in the console
     - The page CSP does not allow the Cyber domain: :ex:`script-src` is required for :ex:`index.js` and :ex:`frame-src` for the fields.
   * - :code:`HostedFields is not defined`
     - The initialization code runs before the SDK script has executed. With :ex:`async` or :ex:`defer` use :ex:`window.onHostedFieldsReady` or the :ex:`hosted-fields:ready` event, see :ref:`Loading the SDK<hosted_payment_fields_loading>`.
   * - :code:`[HostedFields] window.HostedFields is already defined`
     - The SDK script is included twice on the page. Leave one tag.
   * - The layout jumps on page load
     - The containers have no :ex:`hf-field` class in the source markup: they have zero height until the :ex:`iframe` is created.
   * - The focus ring looks foreign
     - It is the SDK's default focus outline. Override it in your own :ex:`.hf-field--focus` rule — but replace it, do not just remove it, see :ref:`State Classes on the Container<hosted_payment_fields_state_classes>`.

.. note:: When investigating an issue, keep in mind that the field content is not available to the Connecting Party either: card values will not appear in the console or in the page debugger under any settings — this is the expected behaviour, not a malfunction.