Skip to main content

Documentation

Mono Connector
Connector overview

  • Connector name: Mono DirectPay open-banking account-to-account payment, reached through Mastercard Payment Gateway Services (MPGS) browser-payment API.

  • Payment method type: ng_mpgs_bank .MPGS Mono A2A. Nigeria bank redirect (category and flow type bank_redirect). The customer is redirected to the Mono DirectPay hosted page, picks their bank, logs in and authorizes the payment. This is the only payment method type linked to the mono gateway.

  • Gateway name: Mono (gateway rapyd type id 'mono'). Requests go to MPGS (Mastercard Gateway REST API version 100) with source of funds BROWSER_PAYMENT / MONO_DIRECT_PAY.

  • Supported countries and currencies: Nigeria (NG), NGN only.

  • Differences between countries: Not applicable. The connector serves Nigeria only.

  • MPGS source-of-funds type is BROWSER_PAYMENT / MONO_DIRECT_PAY.

  • Minimum amount: the connector rejects amounts below 200 (hard-coded), and also checks min/max returned by the MPGS payment options inquiry. Sandbox listing shows minimum 200 NGN and an expiry range of 0 to 30 minutes.

Capabilities

API request

Endpoint

Unique capabilities

Limitations

Create payment

POST /v1/payments

Bank redirect. Before creating the payment the connector calls the MPGS paymentOptionsInquiry and checks currency, amount min/max, country and mandatory payer data (FIRST_NAME, LAST_NAME) against what MPGS returns. It then sends INITIATE_BROWSER_PAYMENT and extracts the bank redirect URL from the returned redirect HTML. Payment is returned as ACT with a redirect_url. No payment_method.fields are needed.

NGN only, with a minimum amount of 200 and no capture option.

Retrieve payment

GET /v1/payments/{payment}

Returns the payment as stored by Rapyd. The final status is set by Rapyd polling the gateway (MPGS CONFIRM_BROWSER_PAYMENT lookup): SUCCESS sets CLO, FAILURE sets ERR with failure_code and failure_message, PENDING keeps ACT.

Status reflects the last gateway poll, with no live gateway lookup.

Create refund

POST /v1/refunds

Sends an MPGS REFUND for the requested amount against the original MPGS order. The refund amount is passed through as requested, so partial refunds are sent to the gateway. Refund status is set synchronously from the gateway response (Completed when approved).

Completed payments only; refund status is not updated after creation.

  • Header parameters: Standard Rapyd headers. No connector-specific headers.

  • Supported workflows

    • Bank redirect.

    • Status is confirmed by Rapyd polling the gateway, not by gateway webhooks. Merchants receive the normal Rapyd payment webhooks when the status changes.

    • Hosted checkout: the payment can be offered on the Rapyd hosted checkout page (POST /v1/checkout), as tested in sandbox.

    • Unique workflow: a payment options inquiry to MPGS is made on every create payment, so a gateway-side change to currency, country, amount limits or mandatory payer fields can reject a payment with a validation message.

Field mapping tables
Create Payment - Body parameters

Note

This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

Field name

Parent field

Data type

Required or optional

Default value

Accepted values (enum)

Constraints

Description

Example

Provided by

amount

-

number

Required

-

Positive number

Minimum 200 (connector check). Also must be within the min/max returned by MPGS for MONO_DIRECT_PAY.

Amount to charge in NGN, major units.

1000

Merchant

currency

-

string

Required

-

NGN

ISO 4217. Must be in MPGS supported currencies.

Currency of the payment.

NGN

Merchant

payment_method

-

object

Required

-

-

-

Payment method object.

{"type": "ng_mpgs_bank", "fields": {}}

Merchant

type

payment_method

string

Required

-

ng_mpgs_bank

-

Payment method type.

ng_mpgs_bank

Merchant

fields

payment_method

object

Optional

{}

Empty object

Payment has no required fields

No payment method fields are used.

{}

Merchant

customer

-

object

Required

-

-

Inline customer object

Customer details sent to MPGS.

-

Merchant

name

customer

string

Required

-

Letters and spaces

Regex ^[a-zA-ZÀ-ÿ ]{1,100}$ (sandbox showed this is not strictly enforced)

Customer full name.

Ada Okafor

Merchant

email

customer

string

Required

-

Valid email

Regex (?=.{4,100}$)[a-zA-Z0-9À-ÿ._%+-]+@[a-zA-Z0-9À-ÿ.-]+[.][a-zA-ZÀ-ÿ]{2,}$

Customer email.

ada.okafor@example.com

Merchant

complete_payment_url

-

string

Required

-

URL

Marked required in payment_options (sandbox accepted a request without it)

Where the customer returns after the bank payment.

https://merchant.example.com/payment/complete

Merchant

error_payment_url

-

string

Optional

-

URL

-

Where the customer goes if the payment fails.

https://merchant.example.com/payment/error

Merchant

merchant_reference_id

-

string

Optional

-

-

-

Merchant's own reference.

MERCHANT-REF-10045

Merchant

description

-

string

Optional

-

-

-

Payment description.

Order 10045

Merchant

metadata

-

object

Optional

-

-

-

Merchant metadata.

{}

Merchant

country

-

string

Optional

-

NG

-

Country of the payment method.

NG

Rapyd

Create Payment - Response parameters

Note

This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

Field name

Parent field

Data type

Values (enum)

Description

Example

Provided by

id

data

string

-

Rapyd payment ID. Also used as MPGS order id, order reference and reconciliation id.

payment_0123456789abcdef0123456789abcdef

Rapyd

status

data

string

ACT, CLO, ERR

ACT when MPGS accepts the initiate request (gateway code SUBMITTED, APPROVED, APPROVED_AUTO, APPROVED_PENDING_SETTLEMENT or PARTIALLY_APPROVED). ERR otherwise.

ACT

Rapyd

next_action

data

string

pending_confirmation

Customer must complete the bank redirect.

pending_confirmation

Rapyd

redirect_url

data

string

URL

Mono DirectPay hosted page where the customer selects their bank.

https://<mono-directpay-hosted-page>/<session>

Gateway

failure_code

data

string

MPGS gateway codes, e.g. DECLINED, BLOCKED, CANCELLED

Set when the payment fails.

DECLINED

Gateway

failure_message

data

string

-

Text for the failure.

Transaction declined due to insufficient funds

Gateway

original_amount

data

number

-

Requested amount.

1000

Carried over

amount

data

number

-

Paid amount. On success the connector sets it from the MPGS transaction amount.

1000

Gateway

currency_code

data

string

NGN

Currency.

NGN

Carried over

payment_method_type

data

string

ng_mpgs_bank

Payment used.

ng_mpgs_bank

Carried over

instructions

data

array

-

Static payment instructions from its configuration.

-

Rapyd

merchant_reference_id

data

string

-

Echo of merchant reference.

MERCHANT-REF-10045

Carried over

complete_payment_url / error_payment_url

data

string

-

Echo of return URLs.

https://merchant.example.com/payment/complete

Carried over

Retrieve Payment - Response parameters

Note

This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

Field name

Parent field

Data type

Values (enum)

Description

Example

Provided by

status

data

string

ACT, CLO, ERR

Current status, updated by Rapyd polling of MPGS.

CLO

Rapyd

paid

data

boolean

true, false

True when completed.

true

Rapyd

amount

data

number

-

Paid amount from the MPGS transaction.

1000

Gateway

failure_code

data

string

-

MPGS response.gatewayCode on failure.

DECLINED

Gateway

failure_message

data

string

-

MPGS response.acquirerMessage on failure.

Payment failed

Gateway

Create Refund - Body parameters

Note

This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

Field name

Parent field

Data type

Required or optional

Default value

Accepted values (enum)

Constraints

Description

Example

Provided by

payment

-

string

Required

-

-

Payment must be CLO

Rapyd payment ID to refund.

payment_0123456789abcdef0123456789abcdef

Merchant

amount

-

number

Optional

Full payment amount

-

Not more than the refundable balance

Refund amount.

1000

Merchant

currency

-

string

Optional

Payment currency

NGN

-

Refund currency.

NGN

Merchant

merchant_reference_id

-

string

Optional

-

-

-

Merchant reference for the refund.

REFUND-REF-10045

Merchant

reason

-

string

Optional

-

-

-

Reason for refund.

Customer request

Merchant

metadata

-

object

Optional

-

-

-

Merchant metadata.

{}

Merchant

Create Refund - Response parameters

Note

This table has many columns. Use the horizontal scroll bar below the table to move across and view all of the columns.

Field name

Parent field

Data type

Values (enum)

Description

Example

Provided by

id

data

string

-

Rapyd refund ID. Used as reconciliation id.

refund_0123456789abcdef0123456789abcdef

Rapyd

status

data

string

Completed, Error

Completed when MPGS gateway code is in the approved list (including SUBMITTED). Error otherwise.

Completed

Rapyd

amount

data

number

-

Refund amount.

1000

Carried over

payment

data

string

-

Original payment ID.

payment_0123456789abcdef0123456789abcdef

Carried over

failure_reason

data

string

-

Message for the MPGS gateway code when declined.

Transaction could not be processed

Gateway

Migrating from PayU

This section shows how PayU Africa (Magellan API) fields, values and behavior relate to the Rapyd fields in the field mapping tables.

Migration notes

  • The payment method name ng_mpgs_bank is intentional even though it looks like the MPGS card prefix.

  • Under PayU, Mono was offered only through the PayU hosted payment page.

Field mapping (Rapyd field to original PayU field)
Create Payment - Body parameters

Rapyd field name

Original PayU field

amount

Basket.amountInCents (cents) - EFT_PRO

currency

Basket.currencyCode

payment_method

AdditionalInformation.supportedPaymentMethods (EFT_PRO)

type

AdditionalInformation.supportedPaymentMethods = EFT_PRO (Nigeria store)

fields

None (new in Rapyd)

customer

Customer

name

Customer.firstName + Customer.lastName

email

Customer.email

complete_payment_url

AdditionalInformation.returnUrl

error_payment_url

AdditionalInformation.cancelUrl

merchant_reference_id

AdditionalInformation.merchantReference

description

Basket.description

metadata

None (new in Rapyd)

country

None (PayU used the store processor country config)

Accepted values mapping

Field name

Original PayU value

Rapyd value

payment_method.type

EFT_PRO (Nigeria store)

ng_mpgs_bank

amount

amountInCents 500000

5000

Create Payment - Response parameters

Rapyd field name

Original PayU field

id

payUReference

status

transactionState / successful (getTransaction, IPN)

next_action

None (new in Rapyd)

redirect_url

None (PayU setTransaction returned only payUReference; shopper went to PayU /rpp.do)

failure_code

resultCode (EFTPRO_003, EFTPRO_004)

failure_message

resultMessage

original_amount

Basket.amountInCents

amount

paymentMethodsUsed (xsi:type eft).amountInCents

currency_code

Basket.currencyCode

payment_method_type

paymentMethodsUsed (xsi:type eft)

instructions

None (new in Rapyd)

merchant_reference_id

merchantReference

complete_payment_url / error_payment_url

AdditionalInformation.returnUrl / cancelUrl

Accepted values mapping

Field name

Original PayU value

Rapyd value

status

PROCESSING / AWAITING_PAYMENT

ACT

status

SUCCESS / SUCCESSFUL (ResultCode 00, EFTPRO_002)

CLO

status

FAILED (EFTPRO_003)

ERR

status / failure_code

EFTPRO_004 Transaction Cancelled (MPGS009)

ERR, failure_code CANCELLED or ABORTED

Retrieve Payment - Response parameters

Rapyd field name

Original PayU field

status

getTransaction transactionState

paid

successful

amount

basket.amountInCents

failure_code

resultCode

failure_message

resultMessage

Create Refund - Body parameters

Rapyd field name

Original PayU field

payment

AdditionalInformation.payUReference (original PAYMENT), TransactionType CREDIT

amount

Credit.amountInCents or Basket.amountInCents (cents)

currency

Basket.currencyCode

merchant_reference_id

AdditionalInformation.merchantReference

reason

None (new in Rapyd)

metadata

None (new in Rapyd)

Create Refund - Response parameters

Rapyd field name

Original PayU field

id

payUReference (of the CREDIT)

status

successful / resultCode

amount

Credit.AmountInCents

payment

payUReference

failure_reason

resultMessage

Accepted values mapping

Field name

Original PayU value

Rapyd value

status

Manual refund (PayU did not use Mono refund API)

Completed / Error

API samples
Create payment (POST /v1/payments)

    • Request

      • curl -X POST 'https://sandboxapi.rapyd.net/v1/payments' \
  -H 'access_key: <your_access_key>' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: <unique_idempotency_key>' \
  -H 'salt: <random_salt>' \
  -H 'signature: <calculated_signature>' \
  -H 'timestamp: <unix_timestamp>' \
  --data '{
  "amount": 1000,
  "currency": "NGN",
  "description": "Order 10045",
  "merchant_reference_id": "MERCHANT-REF-10045",
  "payment_method": {
    "type": "ng_mpgs_bank",
    "fields": {}
  },
  "customer": {
    "name": "Ada Okafor",
    "email": "ada.okafor@example.com"
  },
  "complete_payment_url": "https://merchant.example.com/payment/complete",
  "error_payment_url": "https://merchant.example.com/payment/error"
}'

    • Response

      • {
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "11111111-2222-3333-4444-555555555555"
  },
  "data": {
    "id": "payment_0123456789abcdef0123456789abcdef",
    "amount": 0,
    "original_amount": 1000,
    "currency_code": "NGN",
    "country_code": "NG",
    "status": "ACT",
    "next_action": "pending_confirmation",
    "paid": false,
    "redirect_url": "https://<mono-directpay-hosted-page>/<session>",
    "complete_payment_url": "https://merchant.example.com/payment/complete",
    "error_payment_url": "https://merchant.example.com/payment/error",
    "merchant_reference_id": "MERCHANT-REF-10045",
    "description": "Order 10045",
    "payment_method_type": "ng_mpgs_bank",
    "payment_method_type_category": "bank_redirect",
    "payment_method_data": {},
    "instructions": [
      {
        "name": "instructions",
        "steps": [
          {
            "step1": "The customer will be redirected to the gateways hosted page to select their bank and login to complete the payment.",
            "step2": "After the customer completes the payment on the gateway hosted page, they will be redirected back to the checkout page",
            "step3": "The customer will receive a notification of the payment status on the checkout page and be directed to the merchant"
          }
        ]
      }
    ],
    "failure_code": "",
    "failure_message": "",
    "expiration": 1760000000,
    "metadata": {}
  }
}
Retrieve payment (GET /v1/payments/{payment})

    • Request

      • curl -X GET 'https://sandboxapi.rapyd.net/v1/payments/payment_0123456789abcdef0123456789abcdef' \
  -H 'access_key: <your_access_key>' \
  -H 'Content-Type: application/json' \
  -H 'salt: <random_salt>' \
  -H 'signature: <calculated_signature>' \
  -H 'timestamp: <unix_timestamp>'

    • Response

      • {
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "11111111-2222-3333-4444-555555555555"
  },
  "data": {
    "id": "payment_0123456789abcdef0123456789abcdef",
    "amount": 1000,
    "original_amount": 1000,
    "currency_code": "NGN",
    "country_code": "NG",
    "status": "CLO",
    "next_action": "not_applicable",
    "paid": true,
    "redirect_url": "https://<mono-directpay-hosted-page>/<session>",
    "complete_payment_url": "https://merchant.example.com/payment/complete",
    "error_payment_url": "https://merchant.example.com/payment/error",
    "merchant_reference_id": "MERCHANT-REF-10045",
    "description": "Order 10045",
    "payment_method_type": "ng_mpgs_bank",
    "payment_method_type_category": "bank_redirect",
    "payment_method_data": {},
    "instructions": [
      {
        "name": "instructions",
        "steps": [
          {
            "step1": "The customer will be redirected to the gateways hosted page to select their bank and login to complete the payment.",
            "step2": "After the customer completes the payment on the gateway hosted page, they will be redirected back to the checkout page",
            "step3": "The customer will receive a notification of the payment status on the checkout page and be directed to the merchant"
          }
        ]
      }
    ],
    "failure_code": "",
    "failure_message": "",
    "expiration": 1760000000,
    "metadata": {},
    "paid_at": 1760000300
  }
}
Create refund (POST /v1/refunds)

    • Request

      • curl -X POST 'https://sandboxapi.rapyd.net/v1/refunds' \
  -H 'access_key: <your_access_key>' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: <unique_idempotency_key>' \
  -H 'salt: <random_salt>' \
  -H 'signature: <calculated_signature>' \
  -H 'timestamp: <unix_timestamp>' \
  --data '{
  "payment": "payment_0123456789abcdef0123456789abcdef",
  "amount": 1000,
  "currency": "NGN",
  "merchant_reference_id": "REFUND-REF-10045",
  "reason": "Customer request"
}'

    • Response

      • {
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "66666666-7777-8888-9999-000000000000"
  },
  "data": {
    "id": "refund_0123456789abcdef0123456789abcdef",
    "amount": 1000,
    "currency": "NGN",
    "payment": "payment_0123456789abcdef0123456789abcdef",
    "payment_method_type": "ng_mpgs_bank",
    "merchant_reference_id": "REFUND-REF-10045",
    "reason": "Customer request",
    "status": "Completed",
    "failure_reason": "",
    "metadata": {}
  }
}
In this section: