(Go to the Facebook App or Sandbox App)

Download PHP 5 Client Library

SocialMints Integration Guide

Increase your revenues from the new social currency paradigm. Use SocialMints^TM as a way for your users to spend their social currency on your application. We have done most of the work for you.

Overview

The sequence below depicts simple and secure 'one click pay' on your facebook app

             User clicks

                      Payment Complete!!

Implementation in 4 Steps

To start with, we recommend application developers first test their integration in our sandbox environment. Once things are working to satisfaction, follow a simple process to roll over to production.

1. Apply for merchant secret key for SANDBOX environment by applying for one here. Once you have applied, you will be instantly provided with merchant id, application id and secret key which you will need for integration

2. Call the charge_user() function to charge the user a specified amount with a callback URL

3. Verify the transaction on the callback page with confirm_charge() function.

4. Once you have the sandbox env working, please reapply for merchant account in PRODUCTION ENV. Please note that we have to manually approve you before you can run transactions in production. This is for security reasons. In the code, change the merchant id, application id and secret key to production values and make $is_sandbox = false;

Here's the FAQ if you run into issues and FINAL CHECKLIST before announcing 'Mission Accomplished'.

[optional] you can use any of these buttons in your website to invite users to pay

Charge Request

This method will redirect the user to the bank for confirmation of payment and then bring him back to the callback URL specified. To send the the charge request to SocialMints, you need to call the charge user with the following parameters

Example: pay.php

<?php
require_once('api/socialmints.php');
require_once('client/facebook.php');


$is_sandbox     = true;	// true when you are testing.
$sm_merchant_id = 11111111111;
$sm_app_id      = 11111111111; 
$sm_app_secret  = 'XXXXXXXXXXXXXXXXXXXXXXXX';
$amount         = 10; // 10 mints to be charged to user

//STEP 1: get an object with merchant id, sercret, app id and the callback
$socialmints = new SocialMints($sm_merchant_id, $sm_app_id, $sm_app_secret, $is_sandbox);
$socialmints->set_callback('http://apps.facebook.com/socialmintsapp/callback.php');

//STEP 2: charge the user.

// params: user id, amount, description

// custom (optional) any other data you want to be returned along with callback. 

// If there is more than one, then serialize the array

// we base64_encode both the desc and custom params, so you dont have to

$url = $socialmints->get_charge_user_url($user, $amount, $product_desc, $custom);
$facebook->redirect($url);
 
?>

Table 1.1 Charge User parameters used in the API and sent to SocialMints

Callback Received

After the transaction completes, the bank will redirect the user back to the app through the callback URL specified. In the callback page you can verify the transaction using confirm_charge() function.

confirm_charge()

This method is used by the merhcant to verify the parameters returned in the callback and to send a call to SocailMints to verify the transaction ID.

This method automatically uses the parameters set in the equest ($_REQUEST) verifies the signature and sends a verification call to SocialMints. Example below:

Example: callback.php


<?php
require_once('api/socialmints.php');
require_once('client/facebook.php');

$is_sandbox     = true;	// true when you are testing.
$sm_merchant_id = 111111111111;
$sm_app_id      = 111111111111;
$sm_app_secret  = 'XXXXXXXXXXXXXXXXXXXXXX';
   
$socialmints = new SocialMints($sm_merchant_id, $sm_app_id, $sm_app_secret, $is_sandbox);

// result code
$result_code = $_GET['result'];

if ($result_code != 0) {
	// show error and take him to another page
}

if ($socialmints->confirm_charge()) {
	// Show success!

	// use function get_params() to retrieve var in custom (if you used custom)
	$sm_params = $socialmints->get_params();
	$custom = $sm_params['custom'];
	
	// transaction id
	$transaction_id = $sm_params['trans_id'];

} else {
	//Show error!
} 

?>

Table 1.2 Callback Parameters returned by SocialMints API

Table 1.2.1 Result Codes returned and their meanings

Buttons

FAQ

1. If you receive errors when "Pay by Mints" button is clicked like below

"Action: The error I get is "Incomplete request"
"The request for payment is not complete. Please go back to the app and try again."

then it is most probably because either the account is not yet activated (send us a harsh note) or you are using sandbox keys in production or vice versa.