---
title: "Payments"
description: "Tokenize a card in a hosted iframe, then charge it and create the order in one call."
---
> API Reference Index
> Fetch the complete API index at: https://docs.firearmcart.com/api/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```html
```
```js
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:
| Direction | Fields | Unit |
|-----------|--------|------|
| Request | `items[].price`, `shipping`, `tax` | Integer **cents** |
| Response | `order.subtotal`, `order.tax`, `order.shipping`, `order.total`, `items[].price`, `items[].subtotal` | Float **dollars** |
| Response | `transaction.amount` | Integer **cents** |
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](/api/resources/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](/api/resources/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](/api/resources/shipping-taxation-ffl).
- `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](/api/resources/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](/api/authentication) for how abilities are granted. Charging is throttled harder
than the rest of the API at 30 requests per minute per team.
## Create a tokenization session
`POST /v1/payments/tokenize`
Opens a 15-minute, single-use session for the hosted card form and returns an iframe URL to embed. The cardholder types their card on secure.firearmcart.com, so raw PAN and CVV never reach your server; the iframe posts a single-use token back to the parent window, which you then send to POST /v1/payments/charge.
- **Operation id:** `payments.tokenize`
- **Required ability:** `payments:tokenize`
- **Rate limit:** 60 requests/minute per team
#### Body parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `styling` | object | no | CSS overrides for the card form. Only the eight keys below survive validation — any other key is stripped before it reaches the form. |
| `styling.fontFamily` | string | no | Font stack for the form. Max 255 characters. Example: `Inter, sans-serif` |
| `styling.fontSize` | string | no | Base font size; labels and error text derive from it. Max 20 characters. Example: `16px` |
| `styling.borderRadius` | string | no | Input corner radius. Max 20 characters. Example: `8px` |
| `styling.borderColor` | string | no | Resting input border colour. Max 20 characters. Example: `#e5e7eb` |
| `styling.focusBorderColor` | string | no | Focused input border colour; also tints the focus ring. Max 20 characters. Example: `#3b82f6` |
| `styling.backgroundColor` | string | no | Input background colour. Max 20 characters. Example: `#ffffff` |
| `styling.textColor` | string | no | Input text colour. Max 20 characters. Example: `#111827` |
| `styling.errorColor` | string | no | Validation message colour. Max 20 characters. Example: `#ef4444` |
| `allowed_origins` | array | no | Origins permitted to exchange postMessage with the iframe. Each entry must be a valid URL. Optional to the validator but required in practice — see the caveats. Example: `["https://shop.example.com"]` |
#### Request
```bash
curl -X POST "https://api.firearmcart.com/v1/payments/tokenize" \
-H "Authorization: Bearer $FIREARMCART_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"allowed_origins": ["https://shop.example.com"],
"styling": {
"fontFamily": "Inter, sans-serif",
"fontSize": "16px",
"borderRadius": "8px",
"focusBorderColor": "#3b82f6"
}
}'
```
#### Responses
##### 200 — Session created. Embed iframe_url and wait for the ready message.
```json
{
"session_id": "9f3d2b7e-6c41-4b0a-9a1d-2f8c5e7a1b34",
"iframe_url": "https://secure.firearmcart.com/api-payment-form/9f3d2b7e-6c41-4b0a-9a1d-2f8c5e7a1b34",
"expires_at": "2026-08-11T14:15:00+00:00"
}
```
##### 403 — The token is missing the payments:tokenize ability.
```json
{
"message": "Invalid ability provided."
}
```
##### 422 — Validation failed. Stock framework envelope — a summary message plus a per-field errors map.
```json
{
"message": "The allowed origins field must be an array.",
"errors": {
"allowed_origins": [
"The allowed origins field must be an array."
]
}
}
```
#### Caveats
- allowed_origins is optional to the validator but effectively required. Omit it and the session stores an empty allowlist, which makes the iframe reject every inbound message from the parent window — including the {type: 'tokenize'} command that submits the form. The form ships no submit button, so tokenization can never fire. Always send at least your own origin.
- The iframe posts its token, error and ready messages to allowed_origins[0] only. Extra entries widen the inbound allowlist but never receive outbound messages, so list the embedding origin first.
- Only fontFamily, fontSize, borderRadius, borderColor, focusBorderColor, backgroundColor, textColor and errorColor are honoured. labelColor and placeholderColor appear in older FirearmCart documentation but are dropped by validation before they reach the form, which falls back to its defaults (#374151 and #9ca3af).
- The session is single-use: it is deleted the instant a card is tokenized, and it expires 15 minutes after creation either way. Re-loading a spent or expired iframe URL returns HTTP 410. Create a fresh session per checkout attempt.
- The card form applies its own throttle of 10 tokenizations per 10 minutes per end-user IP, independently of this endpoint's 60/minute team limit.
- expires_at is computed at response time as now + 15 minutes, and is returned as an ISO-8601 string with a UTC offset.
## Charge a card
`POST /v1/payments/charge`
Creates an order from the supplied line items and charges it in a single call. Totals are computed server-side from your catalog, your shipping rates and your tax configuration unless you override them. The order row is persisted either way — a decline leaves a real order in status failed alongside a failed transaction.
- **Operation id:** `payments.charge`
- **Required ability:** `payments:charge`
- **Rate limit:** 30 requests/minute per team
#### Body parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customer_id` | integer | no | The customer's `customer_id`. Required unless email is supplied. The customer must already exist — this endpoint never creates one. Example: `1042` |
| `email` | string | no | Customer email, used to look the customer up when customer_id is absent. Required unless customer_id is supplied. Matched case-insensitively (trimmed and lowercased before the query). Max 255 characters. Example: `dana@example.com` |
| `payment_type` | string | yes | Either token (charge a freshly tokenized card) or card_on_file (charge the customer's most recent unexpired saved card). Example: `token` |
| `token` | string | no | The UUID handed back by the tokenization iframe. Required when payment_type is token, ignored otherwise. Example: `1c9a4e60-7f5d-4a63-9c11-8d0e3b6f2a77` |
| `items` | array