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.
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.
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.
| Symptom | Cause and fix |
|---|---|
Forbidden: invalid embed domain in the modal | Your domain is not approved on this merchant's Domain Whitelist. Submit it; use the link until it is approved. |
Forbidden: missing embed origin | The iframe has referrerpolicy="no-referrer". Set referrerpolicy="origin". |
| Clicking the button does nothing | window.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 mismatch | The 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 credited | The 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 matches | Signing the body without timestamp + ".", signing parsed JSON, or comparing hex instead of base64. |
| The payment cannot be matched to a customer | Matching on metadata (not in the webhook) or on the payer's email. Save and match embed_code. |
| A customer was credited twice | No UNIQUE constraint on transfer_id, so a retry credited again. |
| A failed payment was credited | Crediting 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. |