Initialize Transaction

This endpoint allows you to initialize a transaction on Monnify and it returns a checkout URL which you can load within a browser to display the payment form to your customer. The checkout URL has an expiry time of 40 minutes.

This endpoint is protected with OAuth 2.0 Bearer token. To find out more about authorization for Monnify endpoints, check Here

Endpoint URL: {{base_url}}/api/v1/merchant/transactions/init-transaction

The {{base_url}} for test is https://sandbox.monnify.com but when you go live, it changes to the live url

HTTP Method: POST

Sample Request

curl --location --request POST 'https://sandbox.monnify.com/api/v1/merchant/transactions/init-transaction' \
--data-raw '{
  "amount": 100.00,
  "customerName": "Stephen Ikhane",
  "customerEmail": "stephen@ikhane.com",
  "paymentReference": "123031klsadkad",
  "paymentDescription": "Trial transaction",
  "currencyCode": "NGN",
  "contractCode":"32904822812",
  "redirectUrl": "https://my-merchants-page.com/transaction/confirm",
  "paymentMethods":["CARD","ACCOUNT_TRANSFER"]
}'

Sample Response

{
  "requestSuccessful": true,
  "responseMessage": "success",
  "responseCode": "0",
  "responseBody": {
    "transactionReference": "MNFY|20190915200044|000090",
    "paymentReference": "1568577644707",
    "merchantName": "Test Limited",
    "apiKey": "MK_TEST_VR7J3UAACH",
    "enabledPaymentMethod": [
      "ACCOUNT_TRANSFER",
      "CARD"
    ],
    "checkoutUrl": "https://sandbox.sdk.monnify.com/checkout/MNFY|20190915200044|000090"
  }
}

Initialize Transaction with Sub Account: You can also add split payment configuration when initializing a transaction. Click here for help on creating sub accounts.

curl --location --request POST 'https://sandbox.monnify.com/api/v1/merchant/transactions/init-transaction' \
--data-raw '{
  "amount": 100.00,
  "customerName": "Stephen Ikhane",
  "customerEmail": "stephen@ikhane.com",
  "paymentReference": "123031klsadkad",
  "paymentDescription": "Trial transaction",
  "currencyCode": "NGN",
  "contractCode":"32904822812",
  "redirectUrl": "https://my-merchants-page.com/transaction/confirm",
  "paymentMethods":["CARD","ACCOUNT_TRANSFER"],
  "incomeSplitConfig": [
    	{
    		"subAccountCode": "MFY_SUB_319452883228",
    		"feePercentage": 10.5,
    		"splitAmount": 20,
    		"feeBearer": true
    	}
    ],
   "metaData": {
                    "name": "John Doe",
                    "age": 45
                    }
}

Sample Response

Field Parameters

Field	Mandatory or Optional	Description

Field	Mandatory or Optional	Description
checkoutUrl	O	A URL which can be used to display the Monnify payment interface where the customer can then pay for the transaction via bank transfer or card.
paymentMethods	O	Array of payment methods enabled for the merchant. If not specified, the default payment methods enabled in the contract detail will apply.
incomeSplitConfig	O	Object containing specifications on how payments to this reserve account should be split.
subAccountCode	M	The unique reference for the sub account that should receive the split.
feeBearer	O	Boolean to determine if the sub account should bear transaction fees or not
feePercentage	O	The percentage of the transaction fee to be borne by the sub account
splitPercentage	O	The percentage of the amount paid to be split into the sub account.
merchantName	O	Name of the merchant
redirectUrl	O	A URL which user will be redirected to, on completion of the payment.
amount	M	The amount to be paid by the customer
currencyCode	M	The currency of the transaction being initialized. "NGN"
paymentReference	M	Merchant's Unique reference for the transaction.
transactionReference	O	Unique reference generated for the transaction by Monnify.
paymentDescription	M	Description for the transaction. Will be returned as part of the account name on name enquiry for transfer payments.
customerName	M	Full name of the customer
customerEmail	M	Email address of the customer
contractCode	M	Merchant's contract code (Can be found on the Monnify dashboard)