Versions Compared

Old Version 11

changes.mady.by.user Kelechi Okwuriki

Saved on

compared with

New Version Current

changes.mady.by.user Benjamin Ononogbu

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

To be granted access to this API, you will be required to be PCI-DSS certified. For further inquiries, please reach out to integrations@monnify.com

Charge

...

Cards

Monnify allows you to charge your customers who make one-time payments through the use of their cards. To charge a card you will need to make a request to the endpoint below:

Info

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/cards/charge

...

This endpoint is protected by Bearer Token

HTTP Method: POST

Info

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

Sample Request Body (with no OTP)

Code Block
languagejson
{
    "transactionReference": "MNFY|20190514172736|000001",
    "collectionChannel": "API_NOTIFICATION",
    "card": {
        "number": "4111111111111111",
        "expiryMonth": "10",
        "expiryYear": "2022",
        "pin": "1234",
        "cvv": "122"
    }
}

Sample Response (with no OTP)

Code Block
{,
     "requestSuccessfuldeviceInformation": true,{
        "responseMessagehttpBrowserLanguage": "successen-US",
        "responseCodehttpBrowserJavaEnabled": "0",false,
        "responseBodyhttpBrowserJavaScriptEnabled":true,
{         "statushttpBrowserColorDepth":24,
"SUCCESS"       "httpBrowserScreenHeight":1203,
        "messagehttpBrowserScreenWidth": "Transaction Successful"2138,
        "transactionReferencehttpBrowserTimeDifference": "MNFY|54|20210429142557|000206",
        "paymentReferenceuserAgentBrowserValue": "1619702756719",
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko)    "authorizedAmount": 2000.00
 Chrome/105.0.0.0 Safari/537.36"
   }
}

Charge Card with OTP

Info

Endpoint
POST: https://sandbox.monnify.com/api/v1/merchant/cards/charge

This endpoint is protected by basic authentication

Sample Request Body (with OTP)

...

The response that will be gotten depends on the kind of card used for the transaction. There are cards charged with the use of an OTP, without an OTP, and also with 3DS Secure Authentication. See sample response for each scenario. An extra mandatory object parameter(deviceInformation) is required to capture the user’s device information.

Info

For test card details, you can use the following;

Pan: 4111111111111111, cvv:1234, expiryYear:2024 and expiryMonth:10

...

Sample Response (with no OTP)

Code Block
languagejson
{
    "transactionReference"requestSuccessful": true,
    "responseMessage": "MNFY|54|20210429142945|000208success",
    "collectionChannelresponseCode": "API_NOTIFICATION0",
    "cardresponseBody": {
        "numberstatus": "5061040000000000215SUCCESS",
        "expiryMonthmessage": "09Transaction Successful",
        "expiryYeartransactionReference": "2022MNFY|54|20210429142557|000206",
        "pinpaymentReference": "12341619702756719",
        "cvvauthorizedAmount": "122"2000.00
    }
}

...

Sample Response (with OTP)

Code Block
languagejson
{
    "requestSuccessful": true,
    "responseMessage": "success",
    "responseCode": "0",
    "responseBody": {
        "status": "OTP_AUTHORIZATION_REQUIRED",
        "message": "OTP Authorization required",
        "otpData": {
            "id": "2000.00-e944ba213f0acbc90a16b292ba353b2f",
            "message": "Please enter OTP. Use 123456 as token"
        },
        "transactionReference": "MNFY|54|20210429142945|000208",
        "paymentReference": "1619702984105",
        "authorizedAmount": 1000
    }
}

...

info
Endpoint 
POST: https://sandbox.monnify.com/api/v1/merchant/cards/otp/authorize
This endpoint is protected by basic authentication
...
Sample RequestSample Response (For 3DS Secure Authentication)
 Code Block
languagejson
{
    "transactionReferencerequestSuccessful": "MNFY|20190512185357|000002"true,
    "collectionChannelresponseMessage": "API_NOTIFICATIONsuccess",
    "tokenIdresponseCode": "12345678900",
    "tokenresponseBody": "123456" }
Sample Response
 Code Block
{
    "requestSuccessful": true,     "responseMessagestatus": "successBANK_AUTHORIZATION_REQUIRED",
    "responseCode": "0",     "responseBodysecure3dData": {

       "status": "SUCCESS",         "messageid": "Transaction Successful929852951",
        "transactionReference": "MNFY|54|20210429142945|000208",
        "paymentReferenceredirectUrl": "1619702984105https://centinelapi.cardinalcommerce.com/V2/Cruise/StepUp",
        "authorizedAmount": 2000.00     }
}
3DS Secure Authentication Transaction
 Info
 Code Block
languagejson
Endpoint 
POST: 
"callBackUrl": "https://
sandbox
webpay.
monnify
interswitchng.com/collections/api/v1/
merchant/cards/charge
This endpoint is protected by basic authentication
Sample Request
 {pay/cardinalCallBack",
      "transactionReference": "MNFY|19|20210430115705|000243",     "collectionChanneleciFlag": "API_NOTIFICATION07",
    "card": {         "cvvtermUrl": "123",https://webpay.interswitchng.com/collections/api/v1/pay/cardinalCallBack",
            "expiryMonthacsUrl": "12https://centinelapi.cardinalcommerce.com/V2/Cruise/StepUp",
            "expiryYeartransactionId": "2022AUABZBg92SV1NvdaJH40",
        "number": "4000000000000002",         "pin"paymentId": "1234929852951",
    }
}
Sample Response
 Code Block
languagejson
{        "requestSuccessfulmethod": true"POST",
    "responseMessage": "success",        "responseCodejwt": "0eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxZDQwYjdlYi1kZTI4LTQzMmQtYTUyOS0zMmQxMWYwNjY5YmUiLCJpYXQiOjE2NzAzMDY5MzQsImlzcyI6IjYyZGI3ZTdkMDFjYWU2MzcxOWM2ZGEwYiIsIk9yZ1VuaXRJZCI6IjVkYzJhN2Q2NjY1NmMyMDU0MDllOTc4MiIsIlJldHVyblVybCI6Imh0dHBzOi8vd2VicGF5LmludGVyc3dpdGNobmcuY29tL2NvbGxlY3Rpb25zL2FwaS92MS9wYXkvY2FyZGluYWxDYWxsQmFjayIsIlJlZmVyZW5jZUlkIjoiTU5GWXw4MXwyMDIyMTIwNjA3MDgyOXwwNzg1NTciLCJQYXlsb2FkIjp7IkFDU1VybCI6Imh0dHBzOi8vYXV0aGVudGljYXRpb24uY2FyZGluYWxjb21tZXJjZS5jb20vVGhyZWVEU2VjdXJlL1YyXzFfMC9DUmVxIiwiUGF5bG9hZCI6ImV5SnRaWE56WVdkbFZIbHdaU0k2SWtOU1pYRWlMQ0p0WlhOellXZGxWbVZ5YzJsdmJpSTZJakl1TVM0d0lpd2lkR2h5WldWRVUxTmxjblpsY2xSeVlXNXpTVVFpT2lJMU9UQTFOemd4TmkwNU5qa3hMVFExTURNdE9EWXdOeTA1TURBNVl6YzNabVpoTkRFaUxDSmhZM05VY21GdWMwbEVJam9pTldKbE9HSTVNVFV0T1RWbFpTMDBPREU0TFdJd01tVXROVEF4TTJFMVlURmpZelkxSWl3aVkyaGhiR3hsYm1kbFYybHVaRzkzVTJsNlpTSTZJakF5SW4wIiwiVHJhbnNhY3Rpb25JZCI6IkFVQUJaQmc5MlNWMU52ZGFKSDQwIn0sIk9iamVjdGlmeVBheWxvYWQiOnRydWV9.P4Tw91_mzfwFtHnYZYjFT564j-K7E4iJVPUhaICFx3I",
    "responseBody": {         "statusmd": "BANK_AUTHORIZATION_REQUIRED929852951",
        "message": "3D Secure Authorization required"},
        "secure3dDatatransactionReference": {
   "MNFY|20190514172736|000001",
        "idpaymentReference": "2000.00-59077a3e5157fae7ca9dd260d911ccbbuk--p9lloo99-jj00000000",
   
        "redirectUrlauthorizedAmount": "http://localhost:10001"20.0
      }
 }
 Info
From the above response, the redirectUrl similar to the ascUrl is the url that takes the user to the VISA card website that has an input form to enter OTP sent to the user's phone number.
For those using the API method, the backend sends the ascUrl, TermUrl,md and the jwt response parameters to the frontend which runs an onload html form that redirects the user to VISA website.
 Code Block
languagehtml
<body onload ='form1.submit()'>
    <form  id="transactionReference": "MNFY|19|20210430115705|000243",form1" action=ACSUrl method="post">
      <input  name="paymentReference": "1619780224192",
TermUrl" value={TermUrl}>
      <input name="MD" value={MD}>
      <input name="authorizedAmountJWT": 1000 value={jwt}>
    }
}</form>
</body>
Frontend posts an Html form that redirects to the VISA card website to collect OTP sent to the user’s phone. After the OTP verification is completed on the VISA card endpoint, it makes a post request to the callback URL, which is similar to what is given in the TermUrl(It’s also possible to replace the TermUrl with your own URL so as to know when OTP verification process ends).
Finally, to authorize the charge on the user’s card, you make an authenticated post request (containing your transaction reference, collection channel, api key, and card details) to the authorized endpoint. Check 3DS Secure Authentication on how to authorize the charge.
...
Field Parameters
Field
Description
transactionReference
Unique reference generated for the transaction by Monnify
collectionChannel
"API_NOTIFICATION" only enabled merchants can access resource
card
Object containing card information 
number
Card number
expiryMonth
Card expiration month
expiryYear
Card expiration year
pin
Card pin from card owner
cvv
Security code behind card
tokenId
Token id from the request response (otpData.id)
token
OTP from card owner (use 12345 for test card)
...