Developer Docs

Common Mistakes

Every one of these happened in a real integration.

Docs menuCommon Mistakes
Quick Start Setup & Credentials Prefill API Opening the Checkout Phones & In-App Browsers Webhooks Paying Your Users Reconciliation Environments Common Mistakes Go-Live Checklist FAQ

Every one of these happened in a real integration. The first two change what the customer sees: instead of the RocketRamp checkout, they get a different-looking checkout or an extra verification screen.

A different checkout or an extra verification screen appears

Cause: opening anything other than https://app.myrocketramp.com/embed/<embed_code>. Other checkout endpoints and hosted payment pages show the payer a different checkout and an extra verification step. It usually starts as a workaround after the Prefill API refused an API key without wallet_embed:write.

Fix: use only the Prefill API and the /embed/ address, for every RocketRamp payment you take, including invoices and bills. If prefill refuses the key, create a key with wallet_embed:write. Do not switch endpoints.

The recipient is missing, or the payer lands in their own account

Cause: the old embed button script (app.myrocketramp.com/embed/button/ with data-embed-key), a hand-built app.myrocketramp.com/?s=<code> link, or opening the checkout in a desktop pop-up window. All of these share the payer's existing RocketRamp session, and that session overrides the prefilled recipient. Your page cannot clear RocketRamp's cookie, so "log out first" does not work.

Fix: open /embed/<embed_code> in the iframe modal on desktop and Android browsers (it gets its own session), and as a link only on Safari and iPhone. Create a new embed_code for every attempt.

SymptomCause and fix
Forbidden: invalid embed domain in the modalYour domain is not approved on this merchant's Domain Whitelist. Submit it; use the link until it is approved.
Forbidden: missing embed originThe iframe has referrerpolicy="no-referrer". Set referrerpolicy="origin".
Clicking the button does nothingwindow.open() ran after an await and was blocked. Open first, or use a link.
Sign-in code never completes in the modal (iPhone, Safari)WebKit blocks the checkout's cookie inside iframes. Use the link on those browsers.
"In-app browser detected" with no way out (Android)Use the intent:// hand-off to your own payment page (Phones & In-App Browsers).
Invalid API Key or Merchant mismatchThe key and Merchant ID are from different accounts, or the key is not plain text. Send the matching pair before rotating anything.
Payments complete, nothing is creditedThe webhook URL points at an old server, was entered in the dashboard (unsigned), or the secret on your server is out of date.
The signature never matchesSigning the body without timestamp + ".", signing parsed JSON, or comparing hex instead of base64.
The payment cannot be matched to a customerMatching on metadata (not in the webhook) or on the payer's email. Save and match embed_code.
A customer was credited twiceNo UNIQUE constraint on transfer_id, so a retry credited again.
A failed payment was creditedCrediting on any webhook. Credit only embed_transfer with status: "success".
Paying users with the transfer API (/v1/merchants/transfer/*)It needs one token, charges a fee, and doesn't show in the wallet app. Use Disbursements.
?