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.
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
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. See our Checksum page for more information. |
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. Check our International Payments section for more on international currencies |
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 | true | 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://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:
-
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. -
Call your hook url (if one is set).
-
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 over 4 years ago