Hosted Payment Fields Integration

A guide to the Hosted Payment Fields integration — the option to reach for when you want full control over the look of your checkout page (a "Stripe-style" checkout) without the PCI burden of handling raw card data yourself.

In one sentence: your checkout page is entirely yours — HTML, CSS, layout — except the card number/CVV/expiry inputs, which are actually invisible iframes served by the Gateway. Submitting the form doesn't send card data to your server; it sends the Gateway a paymentToken, which you then process via the Direct Integration.

1. Where this fits

See Choosing the right integration method for the full comparison. In short:

Hosted Payment Fields is a hybrid: structurally it's a Direct Integration (you submit the payment yourself, server-side), but because the sensitive inputs are hosted iframes rather than your own <input> elements, you never touch card data and keep the same low PCI scope as Hosted Payment Pages. This is what avoids the "redirect or iframe the whole page" tradeoff — no full-page handoff, no whole-page iframe, just the individual card fields.

2. Loading the library

Client-side JavaScript, loaded from your Gateway host. jQuery is required and must load first:

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://YOUR-GATEWAY-HOST/sdk/web/v1/js/hostedfields.min.js"></script>

This exposes window.hostedFields, with Form and Field class prototypes, plus a jQuery plugin convenience layer ($(el).hostedForm(), $(el).hostedField()).

3. Field types

Six predefined field components:

Declare a field one of three ways (pick one style, don't mix):

<input type="hostedfield:cardNumber" name="card-number">
<div class="hostedfield" data-hostedfield-type="cardExpiryDate"></div>
<input data-hostedfield='{"type":"cardCVV"}'>

4. Setting up the form

var form = new window.hostedFields.classes.Form(document.forms[0], {
    autoSetup: true,
    autoSubmit: true,
    merchantID: 'merchant123'
});

5. The token generation flow

1. Form submission triggers autoSubmit().
2. Every field validates via validate().
3. getPaymentDetails() builds a paymentToken containing the encrypted field values.
4. addPaymentToken() adds that token to the form as a hidden field.
5. The form submits the token, not raw card data.

Your page (browser)                         Gateway
──────────────────────────────────────────────────────────
Hosted fields render inline (iframes)
Customer types card details ────────────▶ (data never touches your JS/DOM)
Form submits
  autoSubmit() → validate() → getPaymentDetails() → paymentToken generated
  paymentToken attached to your form
Your form submits paymentToken to YOUR server
Your server sends paymentToken to the Gateway via the Direct Integration ──▶ processed

autoSubmit()'s promise resolves with a success flag, error messages, validation details, and the token string itself, if you want to intercept it rather than letting the form submit automatically.

6. Submitting the token (Direct Integration)

Once you have the paymentToken, send it to your own server, then forward it to the Gateway via the standard Direct Integration request — the same basic fields as any other transaction (merchantID, action, amount, type, currencyCode, countryCode, signature, etc.) — plus the token.

⚠️ Not yet verified: the official guide's Hosted Payment Fields Library reference (what this section is built from) does not spell out the exact field name(s) for submitting a card paymentToken produced by this library through the Direct Integration, nor whether a paymentMethod value is required alongside it (the way wallet tokens require paymentMethod=applepay|androidpay|googlepay — see Digital Wallets → Direct Implementation). Confirm the exact Direct-request field name/format for a Hosted-Fields-generated token with Breathepay/the gateway team before relying on this in production. Everything above §6 (loading the library, field types, form config, token generation) is directly from the official library reference and can be relied on as-is.

7. Styling

Hosted field styles must live in a dedicated stylesheet(s), marked with the hostedfield class — the library only parses selectors matching link.hostedfield[rel=stylesheet], style.hostedfield.

• Supported: text-level properties — colour, font-weight, letter-spacing, etc.
• Not supported (for security/consistency reasons): layout properties.
• Pseudo-classes work: :focus, :invalid, plus library-provided state classes like .hf-valid and .hf-user-invalid.

8. Events

Namespaced events fire on both Form and Field objects.

Form events: presubmit (before submission handling starts), valid (data passed validation), submit-invalid (validation failed), error (an exception occurred).

Field events: lifecycle (create, destroy, ready) and interaction (focus, blur, input, change), all prefixed hostedfield:.

9. Field-level methods

10. Digital wallets alongside Hosted Fields — open question

The checkout redesign ("Stripe-style") calls for a combined experience: your own styled checkout page, hosted card fields for card payments, and Apple Pay / Google Pay buttons on the same page.

This specific combination is not documented anywhere — not in the official Hosted Payment Fields Library reference (which has zero mention of wallets), and not in the Digital Wallets pages of the official guide either. This is genuinely unverified integration work, not settled documentation.

What we do know, and the most likely shape of the answer:

• A wallet payment (Apple Pay / Google Pay) produces its own token via the wallet's own JS APIs (Apple's ApplePaySession, Google's Pay API) — this is separate from the hostedFields library entirely.
• That wallet token is then submitted via the Direct Integration, using paymentMethod=applepay|androidpay|googlepay + paymentToken (see Digital Wallets → Direct Implementation) — the same Direct endpoint that a Hosted-Fields-generated card token would go to (pending confirmation of that field name, see §6 above).
• In practice this likely means: render the wallet buttons yourself alongside the hosted card fields, and branch your server-side submission logic on which token you received (card token from hostedFields, vs Apple/Google token from the wallet's own API) — but this needs validating against a real merchant account with wallets boarded before being treated as fact.

Recommend confirming this end-to-end flow with Breathepay's gateway team (or by testing against a sandbox account) before committing to a build timeline for the combined checkout.

11. Quick reference

Load:      <script src=".../sdk/web/v1/js/hostedfields.min.js"></script>  (jQuery first)
Fields:    cardNumber, cardCVV, cardExpiryDate, cardStartDate, cardIssueNumber, cardDetails
Flow:      form submit → validate() → getPaymentDetails() → paymentToken → submit to your server
Then:      your server → Gateway Direct Integration with the token (exact field TBC, see §6)
Styling:   dedicated stylesheet(s) marked `hostedfield`; text-level CSS only, no layout props
Wallets:   NOT covered by this library — separate token flow, unverified combined integration (§10)

12. Sources & verification notes

Read and used directly: Gateway Integration Guide, Hosted Payment Fields Library reference (references/code-references/integration-libraries/hosted-payment-fields-library.md).

Not yet verified — confirm before relying on:

• Exact Direct-request field name/format for submitting a card paymentToken produced by this library (§6).
• Any combined wallets + Hosted Fields integration pattern (§10) — this is not documented by the Gateway anywhere we've found; treat as open engineering work, not settled fact.