Ghana mobile money

Rave currently allows merchants to use two (2) payment methods in Ghana (card and mobile money).

We would show you how to accept payments using the mobile money method.

Pre-requisites for accepting payments in Ghana.

Sign-up for an account here .
set up a webhook to get notified on payments, to see more on webhooks visit the webhook section.
When trying to accept payment on a website you can use our inline js method and pass currency as GHS and country as GH, once you do this, the options for the card and mobile money would come up.
when accepting payments using our APIs please see how to accept mobile money payments via our APIs, see instructions on doing that on this page.
After getting a response for the transaction call the verification endpoint to confirm the final status of the transaction.

Step 1: Encrypt your payload.

📘
Vodafone.
You need to display instructions for your customers to dial a USSD short code to retrieve their voucher code, they would need to pass in the voucher code before they proceed to pay. See a example here.

{
  "PBFPubKey": "FLWPUBK-4e581ebf8372cd691203b27227e2e3b8-X",
  "currency": "GHS",
  "payment_type": "mobilemoneygh",
  "country": "GH",
  "amount": "50",
  "email": "[email protected]",
  "phonenumber": "054709929220",
  "network": "MTN",
  "firstname": "temi",
  "lastname": "desola",
  "voucher": "128373", // only needed for Vodafone users.
  "IP": "355426087298442",
  "txRef": "MC-" + Date.now(),
  "orderRef": "MC_" + Date.now(),
  "is_mobile_money_gh": 1,
  "redirect_url": "https://rave-webhook.herokuapp.com/receivepayment",
  "device_fingerprint": "69e6b7f0b72037aa8428b70fbe03986c"
}

{
  "PBFPubKey": "FLWPUBK-4e581ebf8372cd691203b27227e2e3b8-X",
  "currency": "GHS",
  "payment_type": "mobilemoneygh",
  "country": "GH",
  "amount": "50",
  "email": "[email protected]",
  "phonenumber": "054709929220",
  "network": "MTN",
  "firstname": "temi",
  "lastname": "desola",
  "subaccounts": [
    {
      "id": "RS_D87A9EE339AE28BFA2AE86041C6DE70E",
      "transaction_split_ratio": "2"
    },
    {
      "id": "RS_344DD49DB5D471EF565C897ECD67CD95",
      "transaction_split_ratio": "3"
    },
    {
      "id": "RS_839AC07C3450A65004A0E11B83E22CA9",
      "transaction_split_ratio": "5"
    }
  ],
  "voucher": "128373", // only needed for Vodafone users.
  "IP": "355426087298442",
  "txRef": "MC-" + Date.now(),
  "orderRef": "MC_" + Date.now(),
  "is_mobile_money_gh": 1,
  "redirect_url": "https://rave-webhook.herokuapp.com/receivepayment",
  "device_fingerprint": "69e6b7f0b72037aa8428b70fbe03986c"
}

{
  "PBFPubKey": "FLWPUBK-4e581ebf8372cd691203b27227e2e3b8-X",
  "currency": "GHS",
  "payment_type": "mobilemoneygh",
  "country": "GH",
  "amount": "50",
  "email": "[email protected]",
  "phonenumber": "054709929220",
  "network": "MTN",
  "firstname": "temi",
  "lastname": "desola",
  "subaccounts": [
    {
      "id": "RS_D87A9EE339AE28BFA2AE86041C6DE70E"
    }
  ],
  "voucher": "128373", // only needed for Vodafone users.
  "IP": "355426087298442",
  "txRef": "MC-" + Date.now(),
  "orderRef": "MC_" + Date.now(),
  "is_mobile_money_gh": 1,
  "redirect_url": "https://rave-webhook.herokuapp.com/receivepayment",
  "device_fingerprint": "69e6b7f0b72037aa8428b70fbe03986c"
}

Parameter Definition

Parameter	Required	Description
`PBFPubKey`	True	This is a unique key generated for each button created on Rave’s dashboard. It starts with a prefix `FLWPUBK` and ends with suffix `X`.
`currency`	True (expected value: `GHS`)	This is the specified currency to charge in.
`country`	True (expected value: `GH`)	This is the pair country for the transaction with respect to the currency. See a list of Multicurrency support here Multicurrency Payments ]
`payment-type`	True (expected value: `mobilemoneygh`)	This specifies that the payment method being used is for mobile money payments
`amount`	True	This is the amount to be charged it is passed as - (“amount”:10). Minimum amount for GHS is `1 GHS`
`network`	True (possible values: `MTN`, `VODAFONE`, `TIGO`)	This is the customer's mobile money network provider.
`email`	True	This is the email address of the customer.
`phonenumber`	True	This is the phone number linked to the customer's mobile money account.
`firstname`	False	This is the first name of the card holder or the customer.
`lastname`	False	This is the last name of the card holder or the customer.
`subaccounts`	False	This is an `array` of objects containing the subaccount IDs to split the payment into.
`IP`	False	IP - Internet Protocol. This represents the current IP address of the customer carrying out the transaction.
`txRef`	True	This is a unique reference, unique to the particular transaction being carried out. It is generated by the merchant for every transaction.
`orderRef`	True	Unique ref for the mobilemoney transaction to be provided by the merchant.
`voucher`	True (only for Vodafone cash)	This is the voucher code generated by the customer. It is meant to be passed in the initial charge request.
`is_mobile_money_gh`	True (expected value: `1`)	This identifies that a mobile money transaction is being carried out.
`device_fingerprint`	False	This is the fingerprint for the device being used. It can be generated using a library on whatever platform is being used.

Sample encryption

<?php

function getKey($seckey){
  $hashedkey = md5($seckey);
  $hashedkeylast12 = substr($hashedkey, -12);

  $seckeyadjusted = str_replace("FLWSECK-", "", $seckey);
  $seckeyadjustedfirst12 = substr($seckeyadjusted, 0, 12);

  $encryptionkey = $seckeyadjustedfirst12.$hashedkeylast12;
  return $encryptionkey;

}



function encrypt3Des($data, $key)
 {
  $encData = openssl_encrypt($data, 'DES-EDE3', $key, OPENSSL_RAW_DATA);
        return base64_encode($encData);
 }




function payviamobilemoneygh(){ // set up a function to test card payment.
    
    error_reporting(E_ALL);
    ini_set('display_errors',1);
    
    $data = array('PBFPubKey' => 'FLWPUBK-e634d14d9ded04eaf05d5b63a0a06d2f-X',
    'currency' => 'GHS',
    'country' => 'GH',
    'payment_type' => 'mobilemoneygh',
    'amount' => '30',
    'phonenumber' => '054709929300',
    'firstname' => 'Eddy',
    'lastname' => 'Kwame',
    'network' => 'MTN',
    'email' => '[email protected]',
    'IP' => '103.238.105.185',
    'txRef' => 'MXX-ASC-4578',
    'orderRef' => 'MXX-ASC-90929',
    'is_mobile_money_gh' => 1,
    'device_fingerprint' => '69e6b7f0sb72037aa8428b70fbe03986c');
    
    $SecKey = 'FLWSECK-bb971402072265fb156e90a3578fe5e6-X';
    
    $key = getKey($SecKey); 
    
    $dataReq = json_encode($data);
    
    $post_enc = encrypt3Des( $dataReq, $key );

    var_dump($dataReq);
    
    $postdata = array(
     'PBFPubKey' => 'FLWPUBK-e634d14d9ded04eaf05d5b63a0a06d2f-X',
     'client' => $post_enc,
     'alg' => '3DES-24');
    
    $ch = curl_init();
    
    curl_setopt($ch, CURLOPT_URL, "https://api.ravepay.co/flwv3-pug/getpaidx/api/charge");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($postdata)); //Post Fields
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 200);
    curl_setopt($ch, CURLOPT_TIMEOUT, 200);
    
    
    $headers = array('Content-Type: application/json');
    
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $request = curl_exec($ch);
    
    if ($request) {
        $result = json_decode($request, true);
        echo "<pre>";
        print_r($result);
    }else{
        if(curl_error($ch))
        {
            echo 'error:' . curl_error($ch);
        }
    }
    
    curl_close($ch);
}

payviamobilemoneygh();

Step 2: Call the charge endpoint with your encrypted data

https://api.ravepay.co/flwv3-pug/getpaidx/api/charge

Method: POST

$postdata = array(
     'PBFPubKey' => 'FLWPUBK-e634d14d9ded04eaf05d5b63a0a06d2f-X',
     'client' => $post_enc,
     'alg' => '3DES-24');
    
    $ch = curl_init();
    
    curl_setopt($ch, CURLOPT_URL, "https://api.ravepay.co/flwv3-pug/getpaidx/api/charge");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($postdata)); //Post Fields
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 200);
    curl_setopt($ch, CURLOPT_TIMEOUT, 200);
    
    
    $headers = array('Content-Type: application/json');
    
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $request = curl_exec($ch);
    
    if ($request) {
        $result = json_decode($request, true);
        echo "<pre>";
        print_r($result);
    }else{
        if(curl_error($ch))
        {
            echo 'error:' . curl_error($ch);
        }
    }
    
    curl_close($ch);
}

payviamobilemoneygh();

What happens after I call the charge endpoint?

When you call the charge endpoint you would need to display a prompt to the user depending on the mobile network in use, we give a detailed description on what to show for each network below:

MTN

Dial *170#
Choose option: 6) Wallet
Choose option: 3) My Approvals
Enter your MOMO pin to retrieve your pending approval list
Choose a pending transaction
Choose option 1 to approve
Tap button to continue

Tigo

Dial 5015# to approve your transaction.
Select the transaction to approve and click on send.
Select YES to confirm your payment.

Vodafone

Dial *110# to generate your transaction voucher.
Select option) 6 to generate the voucher.
Enter your PIN in next prompt.
Input the voucher generated in the payment modal.

Then we call your webhook once the transaction has been completed with a successful response.

📘
Handling Mobile money transactions
When the hook response comes for a mobile money transaction, you can call the Transaction verification ] endpoint to get more details on the transaction.
However, we advise merchants implement manual re-query into the system for edge cases and to deal with any failure point that might occur.
An example is when a customer says they have been debited for a transaction but the transaction returned an error or timeout from the processor. With a manual re-query, you can get the updated status at any time and give value to the customer.

{
  "id": 126090,
  "txRef": "rave-checkout-1523183226335",
  "flwRef": "flwm3s4m0c1523183355860",
  "orderRef": null,
  "paymentPlan": null,
  "createdAt": "2018-04-08T10:29:15.000Z",
  "amount": 2000,
  "charged_amount": 2000,
  "status": "successful",
  "IP": "197.149.95.62",
  "currency": "GHS",
  "customer": {
    "id": 22823,
    "phone": "0578922930",
    "fullName": "Anonymous Customer",
    "customertoken": null,
    "email": "[email protected]",
    "createdAt": "2018-04-08T10:28:01.000Z",
    "updatedAt": "2018-04-08T10:28:01.000Z",
    "deletedAt": null,
    "AccountId": 134
  },
  "entity": {
    "id": "NO-ENTITY"
  }
}

{
  "status": "success",
  "message": "V-COMP",
  "data": {
    "id": 690055,
    "txRef": "MC-1520528216374",
    "orderRef": null,
    "flwRef": "FLWMM1522085245161",
    "redirectUrl": "http://127.0.0",
    "device_fingerprint": "69e6b7f0b72037aa8428b70fbe03986c",
    "settlement_token": null,
    "cycle": "one-time",
    "amount": 3,
    "charged_amount": 3,
    "appfee": 0.037500000000000006,
    "merchantfee": 0,
    "merchantbearsfee": 1,
    "chargeResponseCode": "02",
    "raveRef": null,
    "chargeResponseMessage": "pending charge processing",
    "authModelUsed": "MOBILEMONEY",
    "currency": "GHS",
    "IP": "::ffff:10.5.186.67",
    "narration": "Raver",
    "status": "success-pending-validation",
    "vbvrespmessage": "N/A",
    "authurl": "NO-URL",
    "vbvrespcode": "N/A",
    "acctvalrespmsg": null,
    "acctvalrespcode": null,
    "paymentType": "mobilemoneygh",
    "paymentPlan": null,
    "paymentPage": null,
    "paymentId": "N/A",
    "fraud_status": "ok",
    "charge_type": "normal",
    "is_live": 0,
    "createdAt": "2018-03-08T16:57:23.000Z",
    "updatedAt": "2018-03-08T16:57:26.000Z",
    "deletedAt": null,
    "customerId": 437599,
    "AccountId": 48,
    "customer": {
      "id": 437599,
      "phone": "5475309092",
      "fullName": "temi desola",
      "customertoken": null,
      "email": "[email protected]",
      "createdAt": "2018-03-08T16:57:23.000Z",
      "updatedAt": "2018-03-08T16:57:23.000Z",
      "deletedAt": null,
      "AccountId": 48
    },
    "validateInstructions": "pending charge processing"
  }
}

Great you are almost done, now you need to verify the transaction before giving value for this transaction.

Step 3: Verify the payment.

After charging a customer successfully, you need to verify that the payment was successful with Rave before giving value to your customer on your website.

Below are the important things to check for when validating the payment:

Verify the transaction reference.

Verify the data.status of the transaction to be successful.

Verify the currency to be the expected currency

Most importantly validate the amount paid to be equal to or at least greater than the amount of the value to be given.

Below is sample code of how to implement server side validation in different programming languages

curl --request POST \
  --url https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/verify \
  --header 'content-type: application/json' \
  --data '{"txref":"rave-checkout-1523183226335","SECKEY":"FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X"}'

<?php 

$result = array();

$postdata =  array( 
  'txref' => 'rave-checkout-1523183226335',
  'SECKEY' => 'FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X'
  );

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/verify");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($postdata));  //Post Fields
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$headers = [
  'Content-Type: application/json',
];

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$request = curl_exec ($ch);
$err = curl_error($ch);

if($err){
	// there was an error contacting rave
  die('Curl returned error: ' . $err);
}


curl_close ($ch);

$result = json_decode($request, true);

if('error' == $result->status){
  // there was an error from the API
  die('API returned error: ' . $result->message);
}

if('successful' == $result->data->status && '00' == $result->data->chargecode){
  // transaction was successful...
  // please check other things like whether you already gave value for this ref
  // If the amount and currency matches the expected amount and currency etc.
  // if the email matches the customer who owns the product etc
  // Give value
}

//Endpoint to verify transaction
    private final String VERIFY_ENDPOINT = "https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/verify"; 
    
    /**
     * 
     * Method to 
     * 
     * @param paymententity - <b>paymententity - set as a constant with default value as 1</b>
     * @param txref - <b>txref - is the unique payment reference generated by the merchant.</b>
     * @param secret - <b>secret - is the merchant secret key</b>
     * @return
     * @throws UnirestException 
     */
    public JSONObject verify(String flwRef, String secret, double amount, int paymententity) throws UnirestException, Exception {
        
        // This packages the payload
        JSONObject data = new JSONObject();
        data.put("txref", txref);
        data.put("SECKEY", secret)
        
        // end of payload
        
        // This sends the request to server with payload
        HttpResponse<JsonNode> response = Unirest.post(VERIFY_ENDPOINT)
                .header("Content-Type", "application/json")
                .body(data)
                .asJson();
        
        // This get the response from payload
        JsonNode jsonNode = response.getBody();
        
        // This get the json object from payload
        JSONObject responseObject = jsonNode.getObject();
        
        // check of no object is returned
        if(responseObject == null)
            throw new Exception("No response from server");
        
        // This get status from returned payload
        String status = responseObject.optString("status", null);
        
        // this ensures that status is not null
        if(status == null)
            throw new Exception("Transaction status unknown");
        
        // This confirms the transaction exist on rave
        if(!"success".equalsIgnoreCase(status)){
            
            String message = responseObject.optString("message", null);
            
            throw new Exception(message);
        }
        
        data = responseObject.getJSONObject("data");
        
        // This get the amount stored on server
        double actualAmount = data.getDouble("amount");
        
        // This validates that the amount stored on client is same returned
        if(actualAmount != amount)
            throw new Exception("Amount does not match");
        
        
        // now you can give value for payment.
       
    }

var data = new {txref = "rave-checkout-1523183226335", SECKEY = "FLWSECK-e6db11d1f8a6208de8cb2f94e293450e-X"};
            var client = new HttpClient();
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            var responseMessage = client.PostAsJsonAsync("https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/verify", data).Result;
            var responseStr = responseMessage.Content.ReadAsStringAsync().Result;
            var response = Newtonsoft.Json.JsonConvert.DeserializeObject<ResponseData>(responseStr);
            if (response.data.status == "successful" && response.data.amount == amount && response.data.chargecode == "00")
            {
              
              System.Console.WriteLine("Payment Successful then give value");
               
            }

When you successfully verify a completed payment see sample response below:

{
  "status": "success",
  "message": "Tx Fetched",
  "data": 
    {
      "txid": 126088,
      "txref": "rave-checkout-1523183226335",
      "flwref": "flwm3s4m0c1523183281767",
      "devicefingerprint": "9f04df238ec44e48babdd6f02bf3dfec",
      "cycle": "one-time",
      "amount": 2000,
      "currency": "GHS",
      "chargedamount": 2000,
      "appfee": 0,
      "merchantfee": 0,
      "merchantbearsfee": 1,
      "chargecode": "00",
      "chargemessage": "Pending Payment Validation",
      "authmodel": "MOBILEMONEY",
      "ip": "197.149.95.62",
      "narration": "Synergy Group",
      "status": "successful",
      "vbvcode": "N/A",
      "vbvmessage": "N/A",
      "authurl": "NO-URL",
      "acctcode": "00",
      "acctmessage": "Approved",
      "paymenttype": "mobilemoneygh",
      "paymentid": "N/A",
      "fraudstatus": "ok",
      "chargetype": "normal",
      "createdday": 0,
      "createddayname": "SUNDAY",
      "createdweek": 14,
      "createdmonth": 3,
      "createdmonthname": "APRIL",
      "createdquarter": 2,
      "createdyear": 2018,
      "createdyearisleap": false,
      "createddayispublicholiday": 0,
      "createdhour": 10,
      "createdminute": 28,
      "createdpmam": "am",
      "created": "2018-04-08T10:28:01.000Z",
      "customerid": 22823,
      "custphone": "0578922930",
      "custnetworkprovider": "UNKNOWN PROVIDER",
      "custname": "Anonymous Customer",
      "custemail": "[email protected]",
      "custemailprovider": "COMPANY EMAIL",
      "custcreated": "2018-04-08T10:28:01.000Z",
      "accountid": 134,
      "acctbusinessname": "Synergy Group",
      "acctcontactperson": "Desola Ade",
      "acctcountry": "NG",
      "acctbearsfeeattransactiontime": 1,
      "acctparent": 1,
      "acctvpcmerchant": "N/A",
      "acctalias": "temi",
      "acctisliveapproved": 0,
      "orderref": null,
      "paymentplan": null,
      "paymentpage": null,
      "raveref": null,
      "amountsettledforthistransaction": 2000
    }
}

Ghana mobile money

Pre-requisites for accepting payments in Ghana.

Step 1: Encrypt your payload.

📘
Vodafone.

Parameter Definition

Sample encryption

Step 2: Call the charge endpoint with your encrypted data

What happens after I call the charge endpoint?

MTN

Tigo

Vodafone

📘
Handling Mobile money transactions

Step 3: Verify the payment.

Pre-requisites for accepting payments in Ghana.

Step 1: Encrypt your payload.

📘Vodafone.

Parameter Definition

Sample encryption

Step 2: Call the charge endpoint with your encrypted data

What happens after I call the charge endpoint?

MTN

Tigo

Vodafone

📘Handling Mobile money transactions

Step 3: Verify the payment.

📘
Vodafone.

📘
Handling Mobile money transactions