Morapay Developer Docs

Payout methods are the saved destinations for clearing-balance withdrawals. Use Payout rails first to list banks, MoMo operators, and resolve account names. Base path: /api/v1/merchant/methods

Endpoints

Method	Path	Description
`GET`	`/methods`	List active payout methods
`POST`	`/methods`	Add MoMo or bank account
`PATCH`	`/methods/:id`	Update label or primary flag

Portal users need OWNER, ADMIN, or FINANCE role for mutating routes. Merchant API keys have full access.

List methods

GET /api/v1/merchant/methods

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

200 OK

{
  "success": true,
  "data": [
    {
      "id": "pm_uuid",
      "type": "MOBILE_MONEY",
      "label": "MTN MoMo",
      "isPrimary": true,
      "currency": "GHS",
      "details": {
        "phone": "233241234567",
        "provider": "MTN",
        "accountName": "JOHN DOE"
      }
    }
  ]
}

401 Unauthorized

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

Create method

POST /api/v1/merchant/methods

Field	Type	Required	Description
`type`	string	Yes	`BANK_ACCOUNT` or `MOBILE_MONEY`
`label`	string	No	Friendly name
`isPrimary`	boolean	No	Set as default withdrawal destination
`details`	object	Yes	Bank or MoMo fields from rails resolve

Example MoMo body:

{
  "type": "MOBILE_MONEY",
  "label": "MTN MoMo",
  "isPrimary": true,
  "details": {
    "phone": "233241234567",
    "provider": "MTN",
    "accountName": "JOHN DOE"
  }
}

curl -s -X POST "https://api.morapay.io/api/v1/merchant/methods" \
  -H "Content-Type: application/json" \
  -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
  -H "Morapay-Timestamp: $TIMESTAMP" \
  -H "Morapay-Signature: v1=$SIGNATURE" \
  -d '{
    "type": "MOBILE_MONEY",
    "label": "MTN MoMo",
    "isPrimary": true,
    "details": {
      "phone": "233241234567",
      "provider": "MTN",
      "accountName": "JOHN DOE"
    }
  }'

201 Created

{
  "success": true,
  "data": {
    "id": "pm_uuid",
    "type": "MOBILE_MONEY",
    "isPrimary": true
  }
}

400 Bad Request

{
  "success": false,
  "error": "Bank and Mobile Money payouts are not available for your region.",
  "code": "request.invalid",
  "requestId": "req_methods_region"
}

422 Unprocessable Entity

{
  "success": false,
  "error": "Account name could not be verified.",
  "code": "payouts.momo.account_not_found",
  "requestId": "req_methods422"
}

Update method

PATCH /api/v1/merchant/methods/:id Update label, isPrimary, or deactivate with { "isActive": false }.

Withdraw to a method

After saving a method, call POST /api/v1/merchant/settlements/withdraw with payoutMethodId. See Transactions.

Getting started

Payments

Money movement

Account

Recurring and events

Public checkout

Catalog

Payout methods

Endpoints

List methods

Create method

Update method

Withdraw to a method

​Endpoints

​List methods

​Create method

​Update method

​Withdraw to a method

​Related

Endpoints

List methods

Create method

Update method

Withdraw to a method

Related