Monnify Connector

Connector overview

Connector name: Monnify
Payment method type: ng_mfy_bank Instant Account Transfer (Monnify Pay with Bank Transfer). Category bank_transfer. The customer gets a one-time virtual bank account (account number, account name, bank name) and pushes a bank transfer to it from their own banking app, internet banking or USSD.
Gateway name: Monnify (gateway_rapyd_type_id / gc_type: monnify)
Supported countries and currencies: Nigeria (NG), NGN
Differences between countries: Single country (Nigeria) and single currency (NGN). No country differences.
Create payment calls Monnify directly in two steps: init-transaction, then bank-transfer init-payment. The customer is NOT redirected to a Monnify hosted page. The virtual account details are returned in textual_codes and shown by Rapyd Hosted Checkout.
Payment completion is asynchronous. The connector updates the payment from Monnify webhooks.
Minimum amount NGN 20. No maximum amount set.
Sandbox responses simulate Monnify account details.

Capabilities

API request	Endpoint	Unique capabilities	Limitations
Create payment	`POST /v1/payments`	Creates a one-time Monnify virtual account and returns account_number, account_name and bank_name in textual_codes (no redirect_url). Status starts as ACT. Overpayment and underpayment are accepted: the payment closes with amount = amount actually paid. A separate Monnify contract code is used when the merchant's gateway config allows over/underpayment.	NGN only, with a minimum of NGN 20; payments cannot be canceled.
Retrieve payment	`GET /v1/payments/{payment}`	Returns the stored payment with textual_codes, final status and, after a successful transfer, remitter_information (payer account name, account number, bank code). The connector keeps the status fresh through Monnify webhooks and polling; there is no live gateway call on retrieve.	Status reflects the last webhook or poll, with no live gateway lookup.
Create refund	`POST /v1/refunds`	Full and partial refunds through the Monnify Initiate Refund API. Refund is sent back to the payer's source bank account captured from the payment webhook. If no reason is given, a configured default reason is sent (Monnify requires refundReason). Final status arrives by Monnify refund webhook.	Completed payments only; the final refund status arrives later by webhook.

Header parameters: Standard Rapyd headers. No connector-specific headers.
Supported workflows
- Bank transfers: (Payment method category bank_transfer).
- Hosted Checkout: the virtual account details in textual_codes are shown on Rapyd Hosted Checkout with copy-to-clipboard.Create a Checkout Page
- Unique workflow: two-step virtual account creation (Monnify init-transaction, then bank-transfer init-payment). The customer leaves the Rapyd flow to make a push transfer from their own bank, and Rapyd confirms payment from the Monnify webhook or polling.
- Unique workflow: overpayment / underpayment. Payment closes as CLO with amount = amount actually paid (Monnify statuses OVERPAID, UNDERPAID, PARTIALLY_PAID).
- Refund workflow: POST /v1/refunds returns Pending; Monnify refund webhook SUCCESSFUL_REFUND/COMPLETED completes it, FAILED_REFUND/FAILED rejects it.

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	-	-	Minimum 20 (NGN). No maximum configured.	Amount to collect, in major units (naira).	5000	Merchant
`currency`	-	string	Required	-	NGN	ISO 4217. Only NGN is configured on the payment.	Payment currency.	NGN	Merchant
`type`	`payment_method`	string	Required	-	`ng_mfy_bank`	-	Payment method type for Monnify Instant Account Transfer.	`ng_mfy_bank`	Merchant
`fields`	`payment_method`	object	Optional	{}	-	No fields are defined for this payment.	Payment method fields. Send an empty object.	{}	Merchant
`customer`	-	string or object	Required	-	Customer ID (cus_...) or customer object	Must contain name and email.	Customer making the transfer.	cus_9761f0b9d1a1bd6e9a2e1e4b5f2a0c11	Merchant
`name`	`customer`	string	Required	-	-	Regex ^[0-9a-zA-Z ]{1,128}$. First and last name.	Customer full name.	Ada Obi	Merchant
`email`	`customer`	string	Required	-	-	Valid email, max 100 characters (regex in payment_options).	Customer email.	ada.obi@example.com	Merchant
`complete_payment_url`	-	string	Required	-	-	Regex .+.	URL the customer returns to after payment.	https://merchant.example.com/success	Merchant
`error_payment_url`	-	string	Required	-	-	Regex .+.	URL the customer returns to if an error occurs.	https://merchant.example.com/error	Merchant
`description`	-	string	Optional	-	-	-	Payment description.	Order 10045	Merchant
`merchant_reference_id`	-	string	Optional	-	-	-	Merchant's own order reference.	ORDER-10045	Merchant
`expiration`	-	number	Optional	-	-	Unix timestamp. Values beyond 1800 seconds from now are capped to 30 minutes.	Payment expiry time.	1760705400	Merchant
`metadata`	-	object	Optional	-	-	-	Merchant metadata.	{"order_id": "10045"}	Merchant

Create Payment / 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
`id`	-	string	-	Rapyd payment ID.	payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b	Rapyd
`status`	-	string	ACT, CLO, EXP, ERR	Payment status.	ACT	Gateway
`amount`	-	number	-	Amount. After completion this is the amount actually paid.	5000	Gateway
`original_amount`	-	number	-	Amount requested by the merchant.	5000	Merchant
`currency_code`	-	string	NGN	Currency.	NGN	Merchant
`payment_method_type`	-	string	`ng_mfy_bank`	Payment method type.	`ng_mfy_bank`	Carried over
`payment_method_type_category`	-	string	bank_transfer	Payment category.	bank_transfer	Rapyd
`account_number`	`textual_codes`	string	-	Virtual account number the customer must pay into.	5000123456	Gateway
`account_name`	`textual_codes`	string	-	Name on the virtual account.	Merchant Store - Ada Obi	Gateway
`bank_name`	`textual_codes`	string	-	Bank that holds the virtual account.	Wema bank	Gateway
`instructions`	-	array	-	Static payment steps configured on the payment.	-	Rapyd
`redirect_url`	-	string	-	Not used for this payment.	-	Rapyd
`expiration`	-	number	-	Payment expiry time.	1760705400	Rapyd
`paid`	-	boolean	true, false	Whether the payment is completed.	false	Gateway
`paid_at`	-	number	-	Time of payment.	0	Gateway
`failure_code`	-	string	-	Gateway failure code.	-	Gateway
`failure_message`	-	string	-	Gateway failure message.	-	Gateway
`name`	`remitter_information`	string	-	Name on the payer's bank account.	ADA OBI	Gateway
`account_id`	`remitter_information`	string	-	Payer's bank account number.	0123456789	Gateway
`bank_code`	`remitter_information`	string	-	Payer's bank code.	058	Gateway
`merchant_reference_id`	-	string	-	Merchant reference.	ORDER-10045	Merchant
`customer_token`	-	string	-	Customer ID.	cus_9761f0b9d1a1bd6e9a2e1e4b5f2a0c11	Rapyd
`complete_payment_url`	-	string	-	Return URL.	https://merchant.example.com/success	Merchant
`error_payment_url`	-	string	-	Error URL.	https://merchant.example.com/error	Merchant

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	-	-	Must be a completed (CLO) `ng_mfy_bank` payment.	ID of the payment to refund.	payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b	Merchant
`amount`	-	number	Optional	Full remaining amount	-	Cannot exceed the remaining refundable amount.	Refund amount. Partial refunds are supported.	2000	Merchant
`currency`	-	string	Optional	Payment currency	NGN	-	Refund currency.	NGN	Merchant
`reason`	-	string	Optional	Configured default refund reason	-	-	Reason for the refund.	Customer returned item	Merchant
`merchant_reference_id`	-	string	Optional	-	-	-	Merchant refund reference.	REFUND-10045	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`	-	string	-	Rapyd refund ID.	refund_7a1c2e3f4b5d6e7f8a9b0c1d2e3f4a5b	Rapyd
`payment`	-	string	-	Refunded payment ID.	payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b	Merchant
`amount`	-	number	-	Refund amount.	2000	Merchant
`currency`	-	string	NGN	Refund currency.	NGN	Merchant
`status`	-	string	Pending, Completed, Rejected	Refund status.	Pending	Gateway
`reason`	-	string	-	Refund reason.	Customer returned item	Merchant
`merchant_reference_id`	-	string	-	Merchant refund reference.	REFUND-10045	Merchant
`failure_reason`	-	string	-	Gateway failure message when the refund fails at creation.	-	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.

Note

Payment method type ng_mfy_bank: In PayU Africa this method was called PAY_BY_REFERENCE.

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Rapyd field name	Original PayU field
`amount`	`Basket.amountInCents` (setTransaction)
`currency`	`Basket.currencyCode`
`type`	`AdditionalInformation.supportedPaymentMethods` = PAY_BY_REFERENCE
`fields`	None
`customer`	`Customer` block
`name`	`Customer.firstName` + `Customer.lastName`
`email`	`Customer.email`
`complete_payment_url`	`AdditionalInformation.returnUrl`
`error_payment_url`	`AdditionalInformation.cancelUrl`
`description`	`Basket.description`
`merchant_reference_id`	`AdditionalInformation.merchantReference`
`expiration`	None (PayU store setting Monnify Expiry Time, 40 minutes)
`metadata`	None

Accepted values mapping

Field name	Original PayU value	Rapyd value
`payment_method.type`	PAY_BY_REFERENCE	`ng_mfy_bank`
`currency`	NGN	NGN
`amount`	Basket.amountInCents 500000	5000

Create Payment / Retrieve Payment - Response parameters

Rapyd field name	Original PayU field
`id`	None
`status`	`transactionState` (getTransaction)
`amount`	`Basket.amountInCents`
`original_amount`	`Basket.amountInCents`
`currency_code`	`Basket.currencyCode`
`payment_method_type`	PAY_BY_REFERENCE
`payment_method_type_category`	None
`account_number`	None (shown on the PayU payment page)
`account_name`	None (shown on the PayU payment page)
`bank_name`	None (shown on the PayU payment page)
`instructions`	None
`redirect_url`	None
`expiration`	None
`paid`	(getTransaction)
`paid_at`	None
`failure_code`	`resultCode`
`failure_message`	`resultMessage`
`name`	`paymentMethodsUsed` `bank_name`
`account_id`	`paymentMethodsUsed` `account_number`
`bank_code`	None
`merchant_reference_id`	`AdditionalInformation.merchantReference`
`customer_token`	`Customer` block
`complete_payment_url`	`AdditionalInformation.returnUrl`
`error_payment_url`	`AdditionalInformation.cancelUrl`

Accepted values mapping

Field name	Original PayU value	Rapyd value
`status`	SUCCESSFUL	CLO
`status`	EXPIRED (result code EXPIRED)	EXP
`status`	EXPIRED (result code USER_CANCELLED)	CAN
`status`	FAILED (result code PROCESSED_FAILURE)	REV
`status`	PROCESSING	NEW or other unrecognized status

Create Refund - Body parameters

Rapyd field name	Original PayU field
`payment`	`payUReference` (doTransaction CREDIT)
`amount`	`Basket.amountInCents` (CREDIT)
`currency`	`Basket.currencyCode`
`reason`	None
`merchant_reference_id`	`AdditionalInformation.merchantReference`
`metadata`	None

Create Refund - Response parameters

Rapyd field name	Original PayU field
`id`	None
`payment`	`payUReference` (original)
`amount`	`Basket.amountInCents`
`currency`	`Basket.currencyCode`
`status`	`transactionState` (CREDIT result)
`reason`	None
`merchant_reference_id`	`AdditionalInformation.merchantReference`
`failure_reason`	None

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_key>' \
  -H 'salt: <random_salt>' \
  -H 'signature: <calculated_signature>' \
  -H 'timestamp: <unix_timestamp>' \
  --data '{
  "amount": 5000,
  "currency": "NGN",
  "payment_method": {
    "type": "ng_mfy_bank",
    "fields": {}
  },
  "customer": "cus_9761f0b9d1a1bd6e9a2e1e4b5f2a0c11",
  "description": "Order 10045",
  "merchant_reference_id": "ORDER-10045",
  "complete_payment_url": "https://merchant.example.com/success",
  "error_payment_url": "https://merchant.example.com/error"
}'

Response

{
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "<operation_id>"
  },
  "data": {
    "id": "payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b",
    "amount": 5000,
    "original_amount": 5000,
    "currency_code": "NGN",
    "status": "ACT",
    "paid": false,
    "paid_at": 0,
    "description": "Order 10045",
    "merchant_reference_id": "ORDER-10045",
    "customer_token": "cus_9761f0b9d1a1bd6e9a2e1e4b5f2a0c11",
    "payment_method_type": "ng_mfy_bank",
    "payment_method_type_category": "bank_transfer",
    "payment_method_data": {},
    "redirect_url": "",
    "complete_payment_url": "https://merchant.example.com/success",
    "error_payment_url": "https://merchant.example.com/error",
    "expiration": 1760705400,
    "instructions": [
      {
        "name": "instructions",
        "steps": [
          {
            "step1": "Instant Account Transfer is a payment service that allows you to pay into the Merchant's Account via your bank's USSD, Internet banking or Mobile banking.",
            "step2": "Transfer into the Merchant's Account via your bank's USSD, Internet Banking or Mobile banking.",
            "step3": "Please ensure the exact amount stated is paid, paying below the stated amount will result in transaction failure",
            "step4": "Please note that this payment option will expire if the transfer is not completed in time."
          }
        ]
      }
    ],
    "textual_codes": {
      "account_number": "5000123456",
      "account_name": "Merchant Store - Ada Obi",
      "bank_name": "Wema bank"
    },
    "visual_codes": {},
    "failure_code": "",
    "failure_message": "",
    "remitter_information": {},
    "metadata": {}
  }
}

Retrieve payment after the transfer (`GET /v1/payments/{payment}`)

Request

curl -X GET 'https://sandboxapi.rapyd.net/v1/payments/payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b' \
  -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": "<operation_id>"
  },
  "data": {
    "id": "payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b",
    "amount": 5000,
    "original_amount": 5000,
    "currency_code": "NGN",
    "status": "CLO",
    "paid": true,
    "paid_at": 1760704100,
    "description": "Order 10045",
    "merchant_reference_id": "ORDER-10045",
    "customer_token": "cus_9761f0b9d1a1bd6e9a2e1e4b5f2a0c11",
    "payment_method_type": "ng_mfy_bank",
    "payment_method_type_category": "bank_transfer",
    "payment_method_data": {},
    "redirect_url": "",
    "complete_payment_url": "https://merchant.example.com/success",
    "error_payment_url": "https://merchant.example.com/error",
    "expiration": 1760705400,
    "instructions": [
      {
        "name": "instructions",
        "steps": [
          {
            "step1": "Instant Account Transfer is a payment service that allows you to pay into the Merchant's Account via your bank's USSD, Internet banking or Mobile banking.",
            "step2": "Transfer into the Merchant's Account via your bank's USSD, Internet Banking or Mobile banking.",
            "step3": "Please ensure the exact amount stated is paid, paying below the stated amount will result in transaction failure",
            "step4": "Please note that this payment option will expire if the transfer is not completed in time."
          }
        ]
      }
    ],
    "textual_codes": {
      "account_number": "5000123456",
      "account_name": "Merchant Store - Ada Obi",
      "bank_name": "Wema bank"
    },
    "visual_codes": {},
    "failure_code": "",
    "failure_message": "",
    "remitter_information": {
      "name": "ADA OBI",
      "account_id": "0123456789",
      "bank_code": "058"
    },
    "metadata": {}
  }
}

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_key>' \
  -H 'salt: <random_salt>' \
  -H 'signature: <calculated_signature>' \
  -H 'timestamp: <unix_timestamp>' \
  --data '{
  "payment": "payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b",
  "amount": 2000,
  "currency": "NGN",
  "reason": "Customer returned item",
  "merchant_reference_id": "REFUND-10045"
}'

Response

{
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "<operation_id>"
  },
  "data": {
    "id": "refund_7a1c2e3f4b5d6e7f8a9b0c1d2e3f4a5b",
    "payment": "payment_3f1b7f0c2a9d4e5f8a6b1c2d3e4f5a6b",
    "amount": 2000,
    "currency": "NGN",
    "status": "Pending",
    "reason": "Customer returned item",
    "merchant_reference_id": "REFUND-10045",
    "payment_method_type": "ng_mfy_bank",
    "failure_reason": "",
    "metadata": {},
    "created_at": 1760704500
  }
}

In this section:

Documentation

Monnify Connector

Connector overview

Capabilities

Field mapping tables

Create Payment - Body parameters

Note

Create Payment / Retrieve Payment - Response parameters

Note

Create Refund - Body parameters

Note

Create Refund - Response parameters

Note

Migrating from PayU

Note

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Accepted values mapping

Create Payment / Retrieve Payment - Response parameters

Accepted values mapping

Create Refund - Body parameters

Create Refund - Response parameters

API samples

Create payment (`POST /v1/payments`)

Retrieve payment after the transfer (`GET /v1/payments/{payment}`)

Create refund (`POST /v1/refunds`)

Search results

Documentation

Monnify Connector

Connector overview

Capabilities

Field mapping tables

Create Payment - Body parameters

Note

Create Payment / Retrieve Payment - Response parameters

Note

Create Refund - Body parameters

Note

Create Refund - Response parameters

Note

Migrating from PayU

Note

Field mapping (Rapyd field to original PayU field)

Create Payment - Body parameters

Accepted values mapping

Create Payment / Retrieve Payment - Response parameters

Accepted values mapping

Create Refund - Body parameters

Create Refund - Response parameters

API samples

Create payment (POST /v1/payments)

Retrieve payment after the transfer (GET /v1/payments/{payment})

Create refund (POST /v1/refunds)

Search results

Create payment (`POST /v1/payments`)

Retrieve payment after the transfer (`GET /v1/payments/{payment}`)

Create refund (`POST /v1/refunds`)