Morapay Developer Docs

Get a 200 OK from the Merchant API v1 using the official TypeScript SDK.

Prerequisites

Node.js 18+
A Morapay merchant account with TEST API keys (pk_test_* / sk_test_*)
Keys created under Dashboard → Developers → API keys

The SDK is server-side only. Never embed sk_* in browsers, mobile apps, or checkout bundles.

Install the SDK

npm
yarn
pnpm

npm install @morapay/sdk

yarn add @morapay/sdk

pnpm add @morapay/sdk

Initialize Morapay

Only API keys are required. baseUrl and checkoutBaseUrl default to production hosts.

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

const morapay = new Morapay({
  publicKey: process.env.MORAPAY_PUBLIC_KEY!,
  secretKey: process.env.MORAPAY_SECRET_KEY!,
});

Create a payment link

The SDK uses a callable resource pattern: list with (), get with (id).

const link = await morapay.link.create({
  title: "Invoice #42",
  amount: 100,
  currency: "USD",
});

console.log(morapay.buildCheckoutUrl(link.publicCode));

Expected responses

Every response is JSON with a success flag. Signed requests include Morapay-Key, Morapay-Timestamp, and Morapay-Signature headers.Success for POST /api/v1/merchant/links:

200 OK

{
  "success": true,
  "data": {
    "id": "link_abc123",
    "title": "Invoice #42",
    "amount": 100,
    "currency": "USD",
    "publicCode": "abc123xyz",
    "status": "ACTIVE",
    "paidAt": null
  }
}

422 Unprocessable Entity

{
  "success": false,
  "error": "Invalid payload. amount failed platform minimum check.",
  "code": "links.amount.below_minimum",
  "safeMessage": "This amount is below the minimum allowed for mobile money checkout in this region.",
  "displayMessage": "The transaction amount must be at least 1.00 GHS.",
  "why": "Mobile network operators enforce a platform floor transaction limit.",
  "howToFix": "Validate cart totals before calling morapay.link.create() or morapay.products.link().",
  "docUrl": "https://docs.morapay.io/errors/codes/links-amount-below-minimum",
  "uiHint": {
    "severity": "warning",
    "placement": "inline",
    "actionText": "Update amount"
  },
  "requestId": "req_1717483920_abc",
  "details": {}
}

The SDK unwraps data on success and throws a typed MorapayError subclass on failure.Success. morapay.link.create() resolves to the link object:

{
  "id": "link_abc123",
  "title": "Invoice #42",
  "amount": 100,
  "currency": "USD",
  "publicCode": "abc123xyz",
  "status": "ACTIVE",
  "paidAt": null
}

Failure: the same 422 body becomes a thrown error:

import {
  MorapayInvalidRequestError,
  MorapayErrorCode,
  isMorapayError,
} from "@morapay/sdk";

try {
  await morapay.link.create({ title: "Order", amount: 0.5, currency: "GHS" });
} catch (err) {
  if (
    err instanceof MorapayInvalidRequestError &&
    err.code === MorapayErrorCode.LinksAmountBelowMinimum
  ) {
    err.displayMessage;  // safe for customer UI
    err.requestId;       // pass to support
    console.error(err.format());
  }
}

🛑 [MorapayInvalidRequestError] -> Invalid payload. amount failed platform minimum check.

[Code]        links.amount.below_minimum
[Request ID]  req_1717483920_abc
[Status]      422 Unprocessable Entity

[Why this happened]
Mobile network operators enforce a platform floor transaction limit.

[How to fix it]
Validate cart totals before calling morapay.link.create() or morapay.products.link().

[Display message]
The transaction amount must be at least 1.00 GHS.

See Authentication for signing details and Error handling for the full error envelope.

Next steps

Native UI components

Render errors and checkout UI without boilerplate.

Webhooks

Receive real-time payment and payout events.

Payment links

Deep dive into links, products, and checkout sessions.

Error handling

Consultant-grade errors with requestId and UI hints.

API reference

REST endpoints for catalog, disbursement, and payout rails.

Getting started

Concepts

Frontend & UI

Developer tools

Errors

Support

Quickstart

Prerequisites

Next steps

Native UI components

Webhooks

Payment links

Error handling

API reference

​Prerequisites

​Next steps

Native UI components

Webhooks

Payment links

Error handling

API reference

Prerequisites

Next steps