paymatesApi 0.1.3

paymatesApi library is a REST API that consumes flutterwave API

paymatesAPI

paymatesApi app is a REST API that consumes fluterwave API.
In other words you don't need to create endpoints to consume fluterwave API, just install paymatesApi and you ready have endpoints to consume fluterwave API in your django project.

NOTE: At the moment this app is based on mobile money payments in Uganda. More features will be available in the upcoming versions

Installation

Use the package manager pip to install paymatesApi.

pip install paymatesApi

NOTE: The paymateAPI works together with django restframework, you have to install it first.

Usage

• Add paymatesApi app to your django project together with django restframework

INSTALLED_APPS = [
      ...
      "rest_framework",
      "paymatesApi",
  ]

• Include the paymatesApi URLconf in your project urls.py like this:

path('paymates-api/',include('paymatesApi.urls'))

Configuring the app

The app needs to be configured in the settings file of the django project. At the end of the settings file of the project create a variable like this:

PUBLIC_KEY = "your flutterwave public key"

End points to consume

• charge
• transaction-history/str:customerName
• verify

Charge end point

The charge end point is a POST end point that we call when we are initiating payment. Below is an example on how we can call the end point

http://127.0.0.1:8000/paymates-api/charge

Below is the body that has to be sent with this POST end point.

{
    "amount": 7000,
    "currency": "UGX",
    "phoneNumber": "07777777777",
    "email": "[e-mail]",
    "fullName": "Mugisha tester",
    "network": "Airtel",
    "redirect_url": "https://528e-41-210-145-113.ngrok.io/api/verify",
    "description": "this is for testing"
}

NOTE: redirect_url key value is the URL that recieves details of a transaction after it has been made. verify is the end point of paymate API. This is where you put webhook url if you have one.

After a POST request is made with the above body, the paymate API will communicate with the flutterwave API, and if there is nothing that has gone wrong, the below response is returned

{
    "status": "success",
    "message": "Charge initiated",
    "meta": {
        "authorization": {
            "redirect": "https://ravemodal-dev.herokuapp.com/captcha/verify/47563:a80c5eeb68739909397deb36921864dc",
            "mode": "redirect"
        }
    }
}

The meta.authorization object contains the details needed to complete the transaction. The mode is "redirect", meaning you should redirect your customer to the provided URL to complete the payment. To complete the payment, the customer authorizes it with their mobile money provider at the provided redirect URL. For example when you go to the redirect URL you get an inteface where you prompted to enter the OTP sent via SMS on your phone. For the testing case, you can use 123456 as your OTP.

When the payment is completed, a webhook notification is sent. Here's what the response looks like:

{
    "verificationStatus": true,
    "data": {
        "status": "success",
        "message": "Tx Fetched",
        "data": {
            "id": 3322850,
            "txRef": "a7e0374c-c6ec-11ec-9df1-40f02f8abbfe",
            "orderRef": "URF_MMGH_1651148068139_7747135",
            "flwRef": "flwm3s4m0c1651148068308",
            "redirectUrl": "http://127.0.0",
            "device_fingerprint": "N/A",
            "settlement_token": null,
            "cycle": "one-time",
            "amount": 6000,
            "charged_amount": 6000,
            "appfee": 180,
            "merchantfee": 0,
            "merchantbearsfee": 1,
            "chargeResponseCode": "00",
            "raveRef": null,
            "chargeResponseMessage": "Pending Payment Validation",
            "authModelUsed": "MOBILEMONEY",
            "currency": "UGX",
            "IP": "52.209.154.143",
            "narration": "elselearn",
            "status": "successful",
            "modalauditid": "f22aaae8ed2909caf903e23053a9fabb",
            "vbvrespmessage": "N/A",
            "authurl": "NO-URL",
            "vbvrespcode": "N/A",
            "acctvalrespmsg": "Approved",
            "acctvalrespcode": "00",
            "paymentType": "mobilemoneyug",
            "paymentPlan": null,
            "paymentPage": null,
            "paymentId": "N/A",
            "fraud_status": "ok",
            "charge_type": "normal",
            "is_live": 0,
            "retry_attempt": null,
            "getpaidBatchId": null,
            "createdAt": "2022-04-28T12:14:28.000Z",
            "updatedAt": "2022-04-28T12:14:31.000Z",
            "deletedAt": null,
            "customerId": 1605320,
            "AccountId": 101062,
            "customer.id": 1605320,
            "customer.phone": "07777777770",
            "customer.fullName": "Anonymous Customer",
            "customer.customertoken": null,
            "customer.email": "[e-mail]",
            "customer.createdAt": "2022-04-25T13:30:31.000Z",
            "customer.updatedAt": "2022-04-25T13:30:31.000Z",
            "customer.deletedAt": null,
            "customer.AccountId": 101062,
            "meta": [],
            "flwMeta": {}
        }
    }
}

From there, we can now verify the transaction by looking at key status value of the data object.

verify end point

verify is a GET request for paymatesAPI, which is made to return a response for verification after the completion of the transaction. This end point acts as a webhook if you set it in the redirect_url of the body of the charge end point

transaction-history end point

transaction-history is a GET request that you can use to call the paymateAPI like http://127.0.0.1:8000/paymates-api/transaction-history/[[fullname]] where [[fullname]] is a specific fullname of the person you are trying to retrieve. When you call that end point, a transaction history of the person named is returned in a json response.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change from paymates-repository.