Morapay Developer Docs

Transactions represent completed and in-flight payments across crypto and fiat rails. Base path: /api/v1/merchant

Endpoints

Method	Path	Description
`GET`	`/transactions`	List transactions
`GET`	`/transactions/:id`	Transaction detail
`POST`	`/transactions/:id/refunds`	Request refund
`GET`	`/settlements`	List payouts to your balance
`GET`	`/settlements/:id`	Settlement detail
`GET`	`/settlements/:id/transfer-status`	MoMo or bank transfer status
`POST`	`/settlements/withdraw`	Withdraw clearing balance
`GET`	`/summary`	Dashboard KPIs
`GET`	`/limits`	Platform limits for tenant

List transactions

GET /api/v1/merchant/transactions

Query	Description
`page`, `limit`	Pagination
`status`	Filter by status
`type`	Transaction type
`from`, `to`	ISO date range

curl -s "https://api.morapay.io/api/v1/merchant/transactions?page=1&limit=20" \
  -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
  -H "Morapay-Timestamp: $TIMESTAMP" \
  -H "Morapay-Signature: v1=$SIGNATURE"

200 OK

{
  "success": true,
  "data": [
    {
      "id": "txn_uuid",
      "type": "PAYMENT",
      "status": "COMPLETED",
      "amount": "100.00",
      "currency": "USD",
      "createdAt": "2026-03-01T12:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1 }
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid request signature.",
  "code": "auth.signature.mismatch",
  "requestId": "req_txn401"
}

Get transaction

GET /api/v1/merchant/transactions/:id Returns line items, fees, payer metadata, and linked payment link or subscription when present.

curl -s "https://api.morapay.io/api/v1/merchant/transactions/txn_uuid" \
  -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
  -H "Morapay-Timestamp: $TIMESTAMP" \
  -H "Morapay-Signature: v1=$SIGNATURE"

200 OK

{
  "success": true,
  "data": {
    "id": "txn_uuid",
    "type": "PAYMENT",
    "status": "COMPLETED",
    "amount": "100.00",
    "currency": "USD"
  }
}

404 Not Found

{
  "success": false,
  "error": "Transaction not found.",
  "code": "resource.not_found",
  "requestId": "req_txn404"
}

Refund

POST /api/v1/merchant/transactions/:id/refunds Portal users need finance role. Merchant API keys have full tenant access.

Field	Type	Required	Description
`amount`	string / number	No	Partial refund; omit for full
`reason`	string	No	Internal note

curl -s -X POST "https://api.morapay.io/api/v1/merchant/transactions/txn_uuid/refunds" \
  -H "Content-Type: application/json" \
  -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
  -H "Morapay-Timestamp: $TIMESTAMP" \
  -H "Morapay-Signature: v1=$SIGNATURE" \
  -d '{ "amount": "100.00", "reason": "Customer request" }'

202 Accepted

{
  "success": true,
  "data": {
    "id": "refund_uuid",
    "transactionId": "txn_uuid",
    "status": "PENDING",
    "amount": "100.00"
  }
}

403 Forbidden

{
  "success": false,
  "error": "Your role or key does not allow this action.",
  "code": "FORBIDDEN_MERCHANT_ROLE",
  "requestId": "req_refund403"
}

422 Unprocessable Entity

{
  "success": false,
  "error": "Transaction is not refundable.",
  "code": "request.validation_failed",
  "requestId": "req_refund422"
}

Settlements and withdrawals

GET /api/v1/merchant/settlements lists merchant payouts. POST /api/v1/merchant/settlements/withdraw withdraws to a linked MoMo or bank account. Withdraw body: { "amount", "currency", "payoutMethodId" }.

curl -s -X POST "https://api.morapay.io/api/v1/merchant/settlements/withdraw" \
  -H "Content-Type: application/json" \
  -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
  -H "Morapay-Timestamp: $TIMESTAMP" \
  -H "Morapay-Signature: v1=$SIGNATURE" \
  -d '{
    "amount": "500.00",
    "currency": "GHS",
    "payoutMethodId": "pm_uuid"
  }'

202 Accepted

{
  "success": true,
  "data": {
    "id": "settlement_uuid",
    "status": "PROCESSING",
    "amount": "500.00",
    "currency": "GHS"
  }
}

400 Bad Request

{
  "success": false,
  "error": "Insufficient clearing balance.",
  "code": "payouts.momo.insufficient_balance",
  "requestId": "req_withdraw400"
}

Summary KPIs

GET /api/v1/merchant/summary?days=30&seriesDays=7 Returns volume, fees, status breakdowns, and time series for the resolved TEST or LIVE environment.

Getting started

Payments

Money movement

Account

Recurring and events

Public checkout

Catalog

Transactions

Endpoints

List transactions

Get transaction

Refund

Settlements and withdrawals

Summary KPIs

​Endpoints

​List transactions

​Get transaction

​Refund

​Settlements and withdrawals

​Summary KPIs

​Related

Endpoints

List transactions

Get transaction

Refund

Settlements and withdrawals

Summary KPIs

Related