Embedded Experience

The Embedded Experience is the fastest path to a working checkout. You create an intent on your backend, pass the embed_url to your frontend, and MoneyHash renders the full checkout inside an iframe or redirect - method selection, card entry, 3DS, and provider communication - with no additional frontend development required.

Prerequisites

Before starting your integration:

1. Access your MoneyHash Organization and Account from the dashboard
2. Connect your payment providers to the account
3. Configure your Payment Defaults and Flow
4. Retrieve your API keys from the dashboard
5. Complete your server-side integration - the Embedded Experience requires an intent created on your backend

How it works

Your backend creates a payment intent and receives an embed_url in the response. You pass that URL to your frontend and render it - either as an iframe or a redirect. MoneyHash takes over from there, presenting the customer with the checkout experience and handling all payment steps internally.

Step 1 - Create an intent and get the embed URL

Create an intent on your backend using the Payment APIs endpoint. The response includes data.embed_url - this is the URL you render on your frontend. API Reference

Example response

{
  "status": {
    "code": 200,
    "message": "success",
    "errors": []
  },
  "data": {
    "embed_url": "https://embed.moneyhash.io/embed/payment/98j1dWM?mh_intent_secret=64a9fdd02d117939aa2d",
    "intent_secret": "64a9fdd02d117939aa2d",
    "id": "98j1dWM",
    "status": "UNPROCESSED",
    "amount": 50,
    "amount_currency": "AED",
    "state": "INTENT_FORM",
    "state_details": {
      "embed_url": "https://embed.moneyhash.io/embed/payment/98j1dWM?mh_intent_secret=64a9fdd02d117939aa2d"
    },
    "payment_status": {
      "status": "NO_AUTHORIZE_ATTEMPTS"
    }
  }
}

The embed_url is available at both data.embed_url and data.state_details.embed_url - they are identical. Use either.

For intent creation parameters, redirect URLs, and idempotency - see Create & Complete a Basic Payment.

Step 2 - Render the checkout

Pass the embed_url to your frontend and render it using one of the two methods below.

Iframe

Embed the checkout directly inside your page. The customer completes the payment without leaving your site.

<iframe
  src="https://embed.moneyhash.io/embed/payment/98j1dWM?mh_intent_secret=64a9fdd02d117939aa2d"
  width="100%"
  height="600px"
  frameborder="0"
  allow="payment">
</iframe>

Redirect

Redirect the customer to the checkout URL. The customer completes the payment on the MoneyHash-hosted page and is redirected back to your site via the redirect URLs set at intent creation.

<a href="https://embed.moneyhash.io/embed/payment/98j1dWM?mh_intent_secret=64a9fdd02d117939aa2d">
  Proceed to payment
</a>

Step 3 - Handle webhooks

MoneyHash sends webhooks to your webhook_url as the payment progresses. Listen for transaction.purchase.successful with payment_status.status: CAPTURED to confirm the payment and fulfill the order.

For the full webhook reference - see Webhooks.

Customization

Loader UI

The loading screen that appears while the embed initializes can be customized via query parameters appended to the embed_url.

Example

https://embed.moneyhash.io/embed/payment/98j1dWM?mh_intent_secret=64a9fdd02d117939aa2d
  &loader[backgroundColor]=#ffffff
  &loader[color]=#6d5bd0
  &loader[icon]=https://yourdomain.com/logo.png
  &loader[size]=48
  &loader[animate]=true

Branding

Beyond the loader, the checkout UI respects your organization's branding configuration - logo, brand color, and accent color - set in the MoneyHash dashboard under Settings → Organization → Branding. These apply automatically to every embed without any code changes.

Limitations

The Embedded Experience gives you a working checkout with minimal setup. However it has inherent constraints by design:

Next steps