Morapay Developer Docs

Morapay is designed so merchants ship native-feeling checkout and error UI: components live in your DOM tree, inherit your typography, and avoid unpolished full-page iframe embeds.

Philosophy

Layer	What Morapay provides
API	Intent-driven error payloads (`displayMessage`, `uiHint`)
SDK	`MorapayUi.toast()` for vanilla JS
Checkout widget	Hybrid modal: native shell + secure canvas iframe for PCI/MoMo
`@morapay/react`	Drop-in React components **

Error UI today

Every API error includes a rendering blueprint:

{
  "displayMessage": "The transaction amount must be at least 1.00 GHS.",
  "uiHint": {
    "severity": "warning",
    "placement": "inline",
    "actionText": "Update amount"
  }
}

Vanilla toast

import { MorapayUi } from "@morapay/sdk";

try {
  await morapay.products.link("prod_123", { amount: 0.5, currency: "GHS" });
} catch (err) {
  MorapayUi.toast(err, {
    onAction: () => recalculateCart(),
  });
}

morapay.ui.toast(err) is equivalent. Toasts are **browser-only; they no-op when document is unavailable (server-side).

Placement hints

`uiHint.placement`	When to use
`inline`	Form validation: render under the input
`toast`	Transient network or rate-limit errors
`modal`	Critical payout or permission failures

Load the widget from your checkout host:

<script src="https://checkout.morapay.io/widget/morapay-checkout.js"></script>
<script>
  MorapayCheckout.openModal({
    mode: "payment-link",
    publicCode: "abc123",
    onSuccess: (payload) => console.log("paid", payload),
  });
</script>

Not a full-page iframe. The outer modal is native (Shadow DOM on your page). Only the card/MoMo/KYC canvas runs inside a secure iframe (?hybrid=1&canvas=1). Server-side URL helpers:

morapay.buildPaymentLinkEmbedUrl("abc123", { flow: "onramp" });
morapay.buildBusinessPayWidgetUrl("acme-store");

@morapay/react will wrap MorapayErrorView, checkout forms, and hooks. See the React hooks page for the planned API.

Next steps

React hooks

Planned @morapay/react component API.

Custom styling

Theme tokens and Tailwind integration.

Getting started

Concepts

Frontend & UI

Developer tools

Errors

Support

Native components

Philosophy

Error UI today

Vanilla toast

Placement hints

Checkout widget

Next steps

React hooks

Custom styling

​Philosophy

​Error UI today

​Vanilla toast

​Placement hints

​Checkout widget

​Next steps

React hooks

Custom styling

Philosophy

Error UI today

Vanilla toast

Placement hints

Checkout widget

Next steps