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)