Accept card payments with one API call.

curl -X POST https://api.brokkrpay.com/api/payment-links \
  -H "Authorization: Bearer bpk_test_your_token_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": 180,
    "currency": "USD",
    "reference": "order-1042",
    "returnUrl": "https://your-store.com/checkout/complete"
  }'
# amount 180 charges $180.00 — whole dollars, NOT cents.
# The response carries a checkoutUrl you redirect the customer to.

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "state": "PENDING",
  "mode": "test",
  "amount": 180,
  "currency": "USD",
  "delivery": "direct",
  "expiresAt": "2026-07-22T12:00:00.000Z",
  "checkoutUrl": "https://…/pay/aBcD…"
}

amount is whole currency units, not cents

Most processors take minor units. We do not. 180 charges $180.00. If you send 18000 expecting $180.00 you will charge $18,000 — that is a valid amount and we will accept it.

Which amounts are accepted

Your customer pays on a hosted page whose line items come from our storefront’s product catalog — you never register products with BrokkrPay. So the total has to be reachable as a sum of the prices in that catalog (repeats allowed). It is dense at ordinary retail amounts, so in practice this only bites on unusual totals; when it does, creation fails with a 400 naming the amount, before the customer ever sees a payment page. Round to a nearby amount, or ask us to add the price point.

Redirect the top-level page

window.location.href = checkoutUrl, or an ordinary link. Not a popup — it gets blocked — and not an iframe, which breaks Apple Pay and Google Pay. The URL is opaque and single-use; treat it as the whole integration, because there is no BrokkrPay script to load.

<!-- Your checkout page. It never talks to BrokkrPay directly: it calls
     YOUR OWN endpoint, which runs the server-side create above. -->
<button id="pay">Pay with Stripe</button>

<script>
  document.getElementById("pay").addEventListener("click", async (e) => {
    e.target.disabled = true;                     // no double-submits

    const res = await fetch("/create-payment", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ cartId: CART_ID }),
    });
    const { checkoutUrl } = await res.json();

    // Full-page redirect. Not a popup (blocked) and not an iframe (breaks
    // Apple Pay and Google Pay).
    window.location.href = checkoutUrl;
  });
</script>

Show the retail-partner disclosure before the customer commits

You own the page the customer clicks from, so the disclosure about how the purchase appears on their statement has to be rendered next to your pay button. Skipping it is what turns a legitimate charge into a dispute.

// Your checkout page, where the customer comes back to.
app.get("/checkout/complete", async (req, res) => {
  const { orderId, status } = req.query;
  // status is "success" or "cancelled" — a hint for what to render, never
  // proof of payment. Read the order state you stored from the webhook.
  const order = await db.orders.findByBrokkrPayId(orderId);

  if (order.state === "SUCCESS") {
    return res.render("checkout-complete", { order });
  }
  // Cancelled, or the webhook hasn't landed yet — show a pending/retry state.
  res.render("checkout-pending", { order, status });
});

Single-page apps: use a path, not a hash

We append ?orderId=…&status=… to your returnUrl exactly as you wrote it. If your URL contains a #, the query string ends up inside the fragment where location.search can’t read it. Put your own reference in the path and redirect server-side:

// Hash-routed SPA? We append ?orderId=…&status=… to your returnUrl
// verbatim. On a hash URL that lands INSIDE the fragment, where
// location.search cannot see it:
//
//   https://store.com/#/checkout/done  →  https://store.com/#/checkout/done?orderId=…
//                                                              ^ unreadable
//
// Use a path-based returnUrl and redirect server-side instead:
returnUrl = "https://your-store.com/checkout/complete/" + cartId;

app.get("/checkout/complete/:cartId", (req, res) => {
  const { orderId, status } = req.query;   // readable — plain path, real query
  res.redirect(`/?status=${status}#/order/${req.params.cartId}`);
});

curl https://api.brokkrpay.com/api/orders/<orderId> \
  -H "Authorization: Bearer bpk_test_your_token_here"

{
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "state": "SUCCESS",
  "amount": 180,
  "currency": "USD",
  "storeId": "your-site-id",
  "clientReference": "order-1042",
  "paymentMethod": "link",
  "lineItems": [ … ],
  "sessionExpiresAt": "2026-07-22T12:00:00.000Z",
  "statusDetail": null,
  "createdAt": "2026-07-21T12:00:00.000Z",
  "updatedAt": "2026-07-21T12:04:11.000Z"
}

Keep the orderId ↔ reference mapping

This endpoint is keyed by our orderId, while your own records are keyed by your reference. Store the two against each other when the create call returns — without it you can receive a webhook you cannot look up, or hold a reference you cannot query.

{
  "type": "order.state_changed",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "storeId": "your-site-id",
  "state": "SUCCESS",
  "previousState": "PENDING",
  "amount": 180,
  "currency": "USD",
  "mode": "test",
  "reference": "order-1042",
  "timestamp": "2026-07-05T12:00:00.000Z"
}

app.post("/webhook", express.json(), async (req, res) => {
  const event = req.body; // order.state_changed

  // Acknowledge FIRST, then do the work. We give you 5 seconds and do not
  // retry, so a slow fulfilment must not hold the response open.
  res.sendStatus(200);

  if (event.state !== "SUCCESS") return;

  // Reconcile on orderId — it is always present. "reference" is only there if
  // you sent one when creating the link, so treat it as a convenience, not a key.
  const order =
    (await db.orders.findByBrokkrPayId(event.orderId)) ??
    (event.reference ? await db.orders.findByReference(event.reference) : null);

  // Unknown order? The create call may not have returned to you yet. Buffer and
  // retry briefly rather than dropping the event — see "Ordering" below.
  if (!order) return bufferForRetry(event);

  fulfillOrder(order, event.amount);
});

Order states

Ordering: a webhook can arrive before the create call returns

The first PENDING event is emitted as soon as the order exists — which is before POST /api/payment-links has finished responding to you. If your handler persists the order only after that response, there is a window in which an arriving event refers to an order you have never heard of. Usually that is the harmless PENDING, but a fast payer or a slow response can make it SUCCESS. Persist your order before calling us, and buffer events for unknown orderIds for a few seconds rather than dropping them.

Retries and acknowledgement

Reply within 5 seconds. We treat any 2xx as delivered and do not currently retry — a non-2xx, a timeout or a connection failure is recorded in your dashboard’s delivery log and not sent again. So acknowledge first and do your fulfillment work after, and use the delivery log (plus GET /api/orders/:orderId) to catch anything your endpoint missed while it was down.

Verify the signature on every delivery

Every webhook carries a Brokkr-Signature header: an HMAC over the raw request body, keyed by the whsec_… secret shown next to your endpoint in the dashboard. Verify it before parsing the JSON — most frameworks consume the body during parsing and leave you nothing to verify against. Secrets are per environment, so a test delivery can never validate against your live secret. Also check the mode field (test or live) as a second line of defence, and treat the webhook — never the customer returning to your site — as the signal to fulfill.

Test card

4242 4242 4242 4242

Any future expiry, any CVC. Test orders never charge a real card.