Every one of these happened in a real integration. The first two change what the customer sees: instead of the Express Dinero checkout, they get a different-looking checkout or an extra verification screen.
Cause: opening anything other than #/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 Express Dinero 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.myexpressdinero.com/embed/button/ with data-embed-key), a hand-built app.myexpressdinero.com/?s=<code> link, or opening the checkout in a desktop pop-up window. All of these share the payer's existing Express Dinero session, and that session overrides the prefilled recipient. Your page cannot clear Express Dinero'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. |