Hosted fields

Hosted fields are a small card form (number, expiry, security code, and optionally the name and either a postal code or the full billing address) served from secure.ordercard.io inside an iframe on your checkout. Card details go from the shopper’s browser straight to the vault. Your page only ever sees the resulting token and the card’s brand and last four digits, which keeps your website out of PCI DSS scope for card handling.

The form comes in two layouts, a label and box for every field or related fields joined in one box, and takes your fonts and colors. Details your checkout already asks for, like the name or address, can stay on your own form and go along with the card when you tokenize.

Add them to a page

<div id="card"></div>
<script
  src="https://secure.ordercard.io/v1/ordercard-1.0.1.js"
  integrity="sha384-QBnpuSP7J012rvvj6klsOBsjIaT4qqalwBd1UgQkFNB5/GtRp6pP/2HA+4LNZvIE"
  crossorigin="anonymous"
></script>
<script>
  const card = OrderCard.init("oc_pk_live_…", {
    container: "#card",
    fields: { name: true, postal_code: true },
    theme: { fontFamily: "Inter, sans-serif", borderRadius: "8px", focusBorderColor: "#2563eb" },
  });

  card.on("ready", () => console.log("form is ready"));
  card.on("paymentMethod", (token, details) => console.log(token, details.brand, details.last4));
  card.on("errors", (errors) => console.log(errors));
</script>

Then, when the shopper submits your checkout:

const { token, card: details } = await card.tokenize({
  billing: { email: "jane@example.com" },
});

tokenize() resolves with { token, card } and rejects with a list of errors. Send the token to your server and charge it. The form asks for the name and postal code here; anything else your checkout collected goes in billing (see details from your own form).

Treat what the browser sends as what the shopper typed. Which customer a card belongs to is your server’s call: send customer_reference when you charge or retain the token. The form refuses customer and customer_reference, so nobody can slip a card into someone else’s wallet from a checkout page.

Which websites can load the form

The form only loads on the origins listed on the publishable key (scheme, host and port, like https://shop.example.com). On any other page it shows a configuration error instead of the form. Add your staging and local origins to a sandbox key, and only your real checkout to the live key.

Pin the script

ordercard-1.0.1.js never changes. With its integrity value the browser runs the file only if every byte is the one OrderCard released, so nobody can change the script on your checkout without the browser refusing it. A new version gets a new address; update both the address and the integrity value when you move to it.

1.0.1 always talks to secure.ordercard.io, even if you serve a copy of the file yourself. 1.0.0 talks to whichever host serves it, so keep loading it from secure.ordercard.io.

https://secure.ordercard.io/v1/ordercard.js always serves the newest 1.x and changes without notice, so it cannot carry an integrity value. It is handy while you build; pin a version on a live checkout.

What happens to the card

• The form checks the card (number length and check digit, expiry in the future, security code length) and that every field you turned on is filled in before anything is sent. Problems show next to the field, and the shopper’s cursor goes to the first one.
• The vault encrypts the number and returns a pending token. A pending token is deleted after 24 hours unless a successful charge retains it (the default) or you retain it yourself.
• The security code is kept encrypted for 15 minutes so the first charge can send it, then deleted. It is never stored.

Next

• Options and styling shows every init() option and how to restyle the form.
• Events and methods lists what the form tells your page and what your page can ask of it.
• In sandbox, Developers → Try hosted fields in the dashboard runs the real form with your sandbox key. Try the layouts, fields and colors there and copy the matching code. Use card on Developers → Test cards opens it with that card filled in.