The Rave By Flutterwave Developer Documentation

We have put together comprehensive guidelines and documentation to help you get right into integrating any of our products quickly. You can also get support when you need help!

Get Started    Discussions

Rave Standard

This shows you how to accept payments super fast with Rave

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.

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 Inline Parameters

Parameter Required Description
PBFPubKey true Your merchant public key, see how to get your API Keys
integrity_hash false This is a sha256 hash of your getpaidSetup values, it is used for passing secured values to the payment gateway.
txref true Your Unique transaction reference.
payment_options false This allows you to select the payment option you want for your users, see Choose Payment Methods for more info.
payment_plan false This is the payment plan ID used for Recurring billing ].
subaccounts false This is an array of objects containing the subaccount IDs to split the payment into.
amount true Amount to charge.
currency false currency to charge in. Defaults to NGN
country false route country. Defaults to NG
customer_email true Email of the customer.
customer_phone true phone number of the customer.
customer_firstname false first name of the customer.
customer_lastname false last name of the customer.
pay_button_text false Text to be displayed on the Rave Checkout Button.
custom_title false Text to be displayed as the title of the payment modal.
custom_description false Text to be displayed as a short modal description.
redirect_url false URL 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_logo false Link to the Logo image.
onclose: function() false A function to be called when the pay modal is closed.
callback: function(b) false A 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’}] false Any 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://ravesandboxapi.flutterwave.com/flwv3-pug/getpaidx/api/v2/hosted/pay \
  --header 'content-type: application/json' \
  --data '{"txref":"MC-1520443531487","PBFPubKey":"<ADD YOUR PUBLIC KEY HERE>", "customer_email": "user@example.com", "amount": 1000, "currency": "NGN", "redirect_url": "https://your-website.com/urltoredirectto"}'
<?php
$curl = curl_init();

$customer_email = "user@example.com";
$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://ravesandboxapi.flutterwave.com/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://ravesandboxapi.flutterwave.com/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');
    }

?>