Pay with Bank Transfer

This endpoint allows you get virtual account details for a transaction using the transactionReference of an initialized transaction. This is useful if you want to control the payment interface. There are a lot of UX considerations to keep in mind if you choose to do this so we recommend you read this.

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/bank-transfer/init-payment

HTTP Method: POST

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

To get the account details you simply need to pass the transaction reference to the endpoint above. You can also pass a bank code and we will return the USSD string to dial for that bank.

Pay with Bank Transfer Request

{
  "transactionReference": "{{transactionReference}}",
  "bankCode": "058"
}

You can make this request multiple times. Each time you make the request, we will return the response below which specifies how many more seconds the account will be valid for. The validity period for an account is 2400 seconds (40 minutes). You can also specify a different bank code each time and you will get a different USSD string in ussdPayment

Pay with Bank Transfer Response

{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "accountNumber": "7727632865",
        "accountName": "Trial transaction",
        "bankName": "Providus Bank",
        "bankCode": 101,
        "accountDurationSeconds": 600,
        "ussdPayment": "*737*2*100*7727632865#",
        "requestTime": "2019-09-15T21:36:58.16",
        "transactionReference": "MNFY|20190915200044|000090",
        "paymentReference": "1568577644707",
        "amount": 100.00,
        "fee": 10.00,
        "totalPayable": 100.00
    }
}

Field Reference

^(M) indicates fields that are mandatory in the request body. ^(m) Indicates fields that are mandatory only if the parent object is not empty.

Field	Description

Field	Description
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	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. This will be prefixed with the merchants name.
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)
checkoutUrl	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.
enabledPaymentMethod	Array of payment methods enabled for the merchant
incomeSplitConfig	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	Boolean to determine if the sub account should bear transaction fees or not
feePercentage	The percentage of the transaction fee to be borne by the sub account
splitPercentage	The percentage of the amount paid to be split into the sub account.
merchantName	Name of the merchant
accountNumber	Virtual Account number generated for that transaction. This is the account number the customer should transfer to when he wants to pay.
accountName	Name to be displayed during name enquiry. This will be prefixed with the merchants name.
bankName	Name of the bank where the virtual account was generated
bankCode	Bank code of the bank where the virtual account was generated
accountDurationSeconds	Number of seconds left till the account expires
ussdPayment	USSD string the customer can dial to make payment from his bank. Only returned when a bank code is specified will be null otherwise.
requestTime	Time the request was made
fee	Transaction fee to be charged by Monnify
totalPayable	Total amount to be paid by the customer. Will include fees if customer is to bear charges otherwise it will be the same as the amount

Pay with Bank Transfer Request

Pay with Bank Transfer Response

Field Reference

Related Articles