HomeAPI ReferenceAPI Documentation
Dashboard

Rave Standard

This shows you how to accept payments super fast with Rave

Suggest Edits

Accept payment quickly and securely using the standard method by calling the hosted/pay endpoint. When you call the endpoint we return a response with a payment link, do a redirect to the link and a secure payment form would be loaded for your customer to enter their payment details.

When the transaction is completed we would call your redirect_url and append the payment response as query parameters.

📘

Endpoint: https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/hosted/pay

Step 1: Collect payment details.

Collect the customer's email and currency if they are not paying in NGN, if customers are required to enter amount collect that as well. You need to make sure emails are unique per customer.

Rave Standard Parameters

ParameterRequiredDescription
PBFPubKeytrueYour merchant public key, see how to get your API Keys
integrity_hashfalseThis is a sha256 hash of your getpaidSetup values, it is used for passing secured values to the payment gateway. See our Checksum page for more information.
txreftrueYour Unique transaction reference.
payment_optionsfalseThis allows you to select the payment option you want for your users, see Choose Payment Methods for more info.
payment_planfalseThis is the payment plan ID used for Recurring billing ].
subaccountsfalseThis is an array of objects containing the subaccount IDs to split the payment into.
amounttrueAmount to charge.
currencyfalseCurrency to charge in. Defaults to NGN. Check our International Payments section for more on international currencies
countryfalseroute country. Defaults to NG
customer_emailtrueEmail of the customer.
customer_phonetruephone number of the customer.
customer_firstnamefalsefirst name of the customer.
customer_lastnamefalselast name of the customer.
pay_button_textfalseText to be displayed on the Rave Checkout Button.
custom_titlefalseText to be displayed as the title of the payment modal.
custom_descriptionfalseText to be displayed as a short modal description.
redirect_urltrueURL to redirect to when a transaction is completed. This is useful for 3DSecure payments so we can redirect your customer back to a custom page you want to show them.
custom_logofalseLink to the Logo image.
onclose: function()falseA function to be called when the pay modal is closed.
callback: function(b)falseA function to be called on successful card charge. Users can always be redirected to a successful or failed page supplied by the merchant here based on the response.
meta:[{metaname:‘flightid’,metavalue:‘93849-MK5000’}]falseAny other custom data you wish to pass.

Step 2: Initialise the payment

After collecting payment details initialise the payment by calling our API with the payment details, see an example below.

curl --request POST \
  --url https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/hosted/pay \
  --header 'content-type: application/json' \
  --data '{"txref":"MC-1520443531487","PBFPubKey":"<ADD YOUR PUBLIC KEY HERE>", "customer_email": "[email protected]", "amount": 1000, "currency": "NGN", "redirect_url": "https://your-website.com/urltoredirectto"}'

<?php
$curl = curl_init();

$customer_email = "[email protected]";
$amount = 3000;  
$currency = "NGN";
$txref = "rave-29933838"; // ensure you generate unique references per transaction.
$PBFPubKey = "<YOUR PUBLIC KEY>"; // get your public key from the dashboard.
$redirect_url = "https://your-website.com/urltoredirectto";
$payment_plan = "pass the plan id"; // this is only required for recurring payments.


curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/hosted/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount'=>$amount,
    'customer_email'=>$customer_email,
    'currency'=>$currency,
    'txref'=>$txref,
    'PBFPubKey'=>$PBFPubKey,
    'redirect_url'=>$redirect_url,
    'payment_plan'=>$payment_plan
  ]),
  CURLOPT_HTTPHEADER => [
    "content-type: application/json",
    "cache-control: no-cache"
  ],
));

$response = curl_exec($curl);
$err = curl_error($curl);

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

$transaction = json_decode($response);

if(!$transaction->data && !$transaction->data->link){
  // there was an error from the API
  print_r('API returned error: ' . $transaction->message);
}

// uncomment out this line if you want to redirect the user to the payment page
//print_r($transaction->data->message);


// redirect to page so User can pay
// uncomment this line to allow the user redirect to the payment page
header('Location: ' . $transaction->data->link);

What happens when the user completes the transaction on the page?

When the user enter's their payment details, rave would validate then charge the card. Once the charge is completed we would:

  1. Call your redirect url and post the response to you, we also append your reference and our unique reference as query params to the url.

  2. Call your hook url (if one is set).

  3. Send an email to you and your customer on the successful payment. If email to customers is turned off we wouldn't send emails.

Before you give value to the customer, please make a server-side call to our verification endpoint to confirm the status and properties of the transaction.

Step 3: Handling payment response / verifying transaction.

When a transaction is completed we send an event to your hook url and also append the reference to your redirect url you can use either of both responses to verify payment and give value to the customer.

📘

Remember to check

  • if using .htaccess, remember to add the trailing / to the url you set.
  • Do a test post to your URL and ensure the script gets the post body.
  • Only set a publicly available url (http://localhost cannot receive!)

You can pick up the reference or use the post body send to your redirect url to verify transaction and give value. In this example we would use the reference from the url.

<?php

// Retrieve the request's body
$body = @file_get_contents("php://input");

// retrieve the signature sent in the reques header's.
$signature = (isset($_SERVER['verif-hash']) ? $_SERVER['verif-hash'] : '');

/* It is a good idea to log all events received. Add code *
 * here to log the signature and body to db or file       */

if (!$signature) {
    // only a post with rave signature header gets our attention
    exit();
}

// Store the same signature on your server as an env variable and check against what was sent in the headers
$local_signature = getenv('SECRET_HASH');

// confirm the event's signature
if( $signature !== $local_signature ){
  // silently forget this ever happened
  exit();
}

http_response_code(200); // PHP 5.4 or greater
// parse event (which is json string) as object
// Give value to your customer but don't give any output
// Remember that this is a call from rave's servers and 
// Your customer is not seeing the response here at all
$response = json_decode($body);
if ($response->body->status == 'successful') {
    # code...
    // TIP: you may still verify the transaction
    		// before giving value.
}
exit();

<?php
    if (isset($_GET['txref'])) {
        $ref = $_GET['txref'];
        $amount = ""; //Correct Amount from Server
        $currency = ""; //Correct Currency from Server

        $query = array(
            "SECKEY" => "Your Secret Key",
            "txref" => $ref
        );

        $data_string = json_encode($query);
                
        $ch = curl_init('https://api.ravepay.co/flwv3-pug/getpaidx/api/v2/verify');                                                                      
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);                                              
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));

        $response = curl_exec($ch);

        $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
        $header = substr($response, 0, $header_size);
        $body = substr($response, $header_size);

        curl_close($ch);

        $resp = json_decode($response, true);

      	$paymentStatus = $resp['data']['status'];
        $chargeResponsecode = $resp['data']['chargecode'];
        $chargeAmount = $resp['data']['amount'];
        $chargeCurrency = $resp['data']['currency'];

        if (($chargeResponsecode == "00" || $chargeResponsecode == "0") && ($chargeAmount == $amount)  && ($chargeCurrency == $currency)) {
          // transaction was successful...
  			 // please check other things like whether you already gave value for this ref
          // if the email matches the customer who owns the product etc
          //Give Value and return to Success page
        } else {
            //Dont Give Value and return to Failure page
        }
    }
		else {
      die('No reference supplied');
    }

?>

Updated almost 4 years ago

Next Steps