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.

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,
            "include_payment_entity" => "1"
        );

        $data_string = json_encode($query);
                
        $ch = curl_init('https://ravesandboxapi.flutterwave.com/flwv3-pug/getpaidx/api/xrequery');                                                                      
        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');
    }

?>