Morapay Developer Docs

Merchant payout rails endpoints live under /api/v1/merchant/rails/*. They require signed requests. Use these to build withdrawal forms: bank dropdowns, MoMo operator lists, and account-name preview before saving a payout method.

Endpoints

Method	Path	Description
`GET`	`/rails/meta`	Business country and fiat rail availability
`GET`	`/rails/banks`	Bank institutions for merchant country
`GET`	`/rails/mobile-providers`	MoMo operators for merchant currency
`GET`	`/rails/resolve`	Preview account holder name

Payout rails meta

GET /api/v1/merchant/rails/meta Returns the business country, fiat currency, and whether local fiat rails are available.

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

{
  "success": true,
  "data": {
    "fiatRailsSupported": true,
    "payoutCurrencyFiat": "GHS",
    "businessCountry": "GH"
  }
}

List banks

GET /api/v1/merchant/rails/banks Returns bank institutions for the merchant’s country. Requires fiatRailsSupported: true from meta.

200 OK

{
  "success": true,
  "data": {
    "banks": [
      {
        "id": 76,
        "name": "Absa Bank Ghana Ltd",
        "code": "030100",
        "slug": "absa-bank-ghana-ltd",
        "type": "ghipss",
        "currency": "GHS"
      }
    ]
  }
}

400 Bad Request

{
  "success": false,
  "error": "Fiat payout rails are not available for this business.",
  "code": "request.invalid",
  "requestId": "req_banks400"
}

List mobile money operators

GET /api/v1/merchant/rails/mobile-providers Returns MoMo operators for the merchant’s fiat currency such as GHS, NGN.

{
  "success": true,
  "data": {
    "providers": [
      { "name": "MTN", "code": "MTN", "slug": "mtn-mobile-money" },
      { "name": "Telecel", "code": "VOD", "slug": "vod-mobile-money" }
    ]
  }
}

Resolve account name

GET /api/v1/merchant/rails/resolve Preview the account holder name before creating a payout method.

Query parameters

Parameter	Type	Required	Description
`type`	string	Yes	`BANK_ACCOUNT` or `MOBILE_MONEY`
`bank_code`	string	Bank	Bank or provider code
`account_number`	string	Bank	6–20 digit account number
`phone`	string	MoMo	Mobile number
`provider_hint`	string	MoMo	e.g. `MTN`, `VOD`, `ATL`

curl -s "https://api.morapay.io/api/v1/merchant/rails/resolve?type=BANK_ACCOUNT&bank_code=030100&account_number=0123456789" \
  -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
  -H "Morapay-Timestamp: $TIMESTAMP" \
  -H "Morapay-Signature: v1=$SIGNATURE"

200 OK

{
  "success": true,
  "data": {
    "accountName": "JOHN DOE"
  }
}

422 Unprocessable Entity

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

Public validation for checkout

For payer-facing checkout flows, use the unsigned public validation endpoints:

Endpoint	Method	Purpose
`/api/public/validate/momo`	POST	Validate MoMo number
`/api/public/validate/bank`	POST	Validate bank account
`GET /api/public/validate/banks?country=gha`	GET	Bank list for Ghana (`gha`) or Nigeria (`nga`)

Example MoMo validate body:

{
  "receiver": "233241234567",
  "provider": "MTN",
  "currency": "GHS"
}

Errors

HTTP	Typical cause
401	Missing or invalid signed headers
403	LIVE action blocked by KYB tier
404	Unknown bank code or unresolved account
422	Invalid phone, account number, or provider hint

401 Unauthorized

{
  "success": false,
  "error": "Invalid API key or signature.",
  "code": "auth.keys.invalid",
  "requestId": "req_rails401"
}

400 Bad Request

{
  "success": false,
  "error": "Fiat payout rails are not available for this business.",
  "code": "request.invalid",
  "requestId": "req_rails400"
}

422 Unprocessable Entity

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

Getting started

Payments

Money movement

Account

Recurring and events

Public checkout

Catalog

Payout rails API

Endpoints

Payout rails meta

List banks

List mobile money operators

Resolve account name

Query parameters

Public validation for checkout

Errors

​Endpoints

​Payout rails meta

​List banks

​List mobile money operators

​Resolve account name

​Query parameters

​Public validation for checkout

​Errors

​Related

Endpoints

Payout rails meta

List banks

List mobile money operators

Resolve account name

Query parameters

Public validation for checkout

Errors

Related