Go-live Checklist

Use this checklist to confirm your integration is ready before you cut over to Production. It’s intended for integrations that talk to the Beam API directly; if you use Beam through a connected website or plug-in, you can skip it.

When everything in Essentials is checked, follow the Switching to Production guide for the actual cutover. The Optional hardening section is for higher-volume or business-critical integrations.

Essentials

Error handling

• Handle errors meaningfully. Don’t bubble raw API responses to end users. Distinguish them when surfacing messages — API_VALIDATION_ERROR (bad input) is not the same as INVALID_JSON_ERROR (malformed request). See Error Handling for the full catalog.

Webhook handling

• Verify signatures with the HMAC key from Lighthouse. Drop any request whose X-Beam-Signature doesn’t match. See Webhooks.
• Dedupe by event id (or by resource id + event type). Webhook delivery is at-least-once — expect occasional duplicates, including retries after a successful ack if Beam’s response check times out.
• Don’t assume ordering. Events can arrive out of order; resolve final state from the latest authoritative resource, not from event sequence.
• Return 2xx quickly. If your handler does meaningful work (update orders, send emails, analytics), enqueue it and ack immediately. Beam retries up to 10 times with exponential backoff before giving up.

Observability

• Log enough to debug. At minimum: request id, endpoint, status code, error code. Without these, support tickets for “my charge failed” become harder to solve.
• Never log card data or PII. That includes PAN, CVV, full names, addresses, contact info. Card information should appear in logs only as last4.

Optional hardening

These are worth implementing if your integration has high transaction volume, runs unattended, or where a duplicate charge would be expensive to reconcile. They aren’t required for typical merchant integrations.

• Send an idempotency key on every POST and PATCH. Use V4 UUIDs or another high-entropy string. Prevents a network-level retry from creating duplicate charges or refunds. See Request Idempotency.
• Back off on 429s. Beam returns TOO_MANY_REQUESTS_ERROR under load. Implement exponential backoff with jitter rather than retrying tightly.
• Retry 5xx and timeouts — but only with the same idempotency key, otherwise you risk double-charging.

Ready to launch?

Once Essentials is green, follow Switching to Production. That page covers the cutover (keys, base URL, webhooks) and a final smoke test before you take real traffic.