Payments

Payments are a two-step flow. You open a short-lived tokenization session, embed the hosted card form it returns, and receive a single-use token when the cardholder submits. You then send that token to the charge endpoint, which builds the order from your catalog, prices it, and authorizes the card — all in one request.

Raw card data never touches your servers. The form is served from secure.firearmcart.com, a separate origin from both your storefront and the API, and the only thing that crosses back into your page is a token plus the card’s brand and last four digits.

Choosing a payment type

payment_type decides where the card comes from:

• token — a card the shopper just entered in the iframe. Pass the token you received.
• card_on_file — the customer’s most recently saved card that has not expired. No token is needed, but the customer must already have one; there is no way to select a specific saved card.

Talking to the iframe

The form communicates entirely over postMessage. Send allowed_origins when you create the session — it is the allowlist the iframe checks on every inbound message, and an empty allowlist blocks your own tokenize command, leaving the form unsubmittable.

<iframe id="fc-payment" src="IFRAME_URL_FROM_THE_TOKENIZE_RESPONSE"
        style="border:0;width:100%;height:200px"></iframe>

const SECURE_ORIGIN = "https://secure.firearmcart.com";

window.addEventListener("message", (event) => {
  if (event.origin !== SECURE_ORIGIN) return;

  switch (event.data.type) {
    case "ready":
      // { height } — resize the iframe to fit the form.
      document.getElementById("fc-payment").style.height =
        `${event.data.payload.height}px`;
      break;
    case "token":
      // { token, card: { last_four, brand, exp_month, exp_year } }
      chargeWithToken(event.data.payload.token);
      break;
    case "error":
      // payload is a plain string.
      console.error(event.data.payload);
      break;
  }
});

// Nothing else submits the form — there is no button inside the iframe.
document.getElementById("fc-payment").contentWindow.postMessage(
  { type: "tokenize" },
  SECURE_ORIGIN,
);

Outbound messages go to the first entry in allowed_origins, so list the embedding page’s origin first. Sessions are single-use and expire after 15 minutes; create a fresh one for every checkout attempt.

Money units

The charge endpoint is the one place in the API where both money conventions meet in a single exchange, so read them per field rather than per endpoint:

That last row is a genuine inconsistency, not a typo: the transaction object on the charge response is hand-built and converts to cents, while the transactions[] array returned by Orders uses TransactionResource, which emits dollars.

Identifiers

customer_id, product_id and items[].variant_id are store-scoped ids — per-store sequential integers, the same ones Customers and Products hand out. Two identifiers here are UUIDs rather than team-scoped numbers:

• shipping_rate_id, whose value is the rate_id UUID from Shipping, taxation & FFL dealers.
• transaction.transaction_id on the charge response.

Failure modes worth planning for

There is no idempotency key. If a charge request times out on your side, you cannot safely retry it — the authorization may already have gone through and a retry creates a second order and a second charge. Reconcile against Orders instead.

Declines are recorded, not discarded. A declined card leaves a real order in status failed with a failed transaction attached, and both are visible in the dashboard and over the API.

Fraud controls fail closed and opaque. Blacklist matches and the US-cards-only and block-prepaid checkout settings all reject before the gateway is contacted, and they surface as 500 processing_error rather than a specific 4xx — deliberately, so the response cannot be used to probe your rules.

Every request on this page also needs a token with the matching ability; see Authentication for how abilities are granted. Charging is throttled harder than the rest of the API at 30 requests per minute per team.