Smoovpay Integration

Updated on 2012/08/13 GMT +8 hours

Sign up for our sandbox account for a testing enviroment.


Login with your merchant account, under 'Tools', select 'Payment Link' and fill in the mandatory textfield.

Sample Screenshot

To learn more about the parameters, please check the 'Button parameters' table of 1. Embed the Payment Button.

  • Reference Id

    This ID can be served as the merchant reference ID. This ID should be unique in the merchant system.
  • Total Amount

    The total amount to be charged to the customer credit card. It should be the sum of the subtotal for each item, delivery charge, discounted amount and tax amount.
  • Success Page URL

    URL to go when users have completed the payment in SmoovPay page.
  • Cancel Page URL

    URL to go when users click 'Cancel' in SmoovPay page.
  • Items List

    Item : Title/name for item x (x can range from 1 to 20). Eg. $4.99 Voucher deal.
    Description : Description for the item x.
    Items Quantity : The quantity for item x.
    Items Amount : The unit price for item x.

To get started, add the following 'sample code' to your checkout page. For details of each parameter, look at the 'button parameters' table after the sample code.

Sample Code

<form action="https://sandbox.smoovpay.com/access" method="post" target="smoovpay" >
<!-- For actual LIVE account, use https://secure.smoovpay.com/access -->
    <input type="hidden" name="version" value="2.0" />
    <input type="hidden" name="action" value="pay" />
    <input type="hidden" name="merchant" value="your@email.com" />
    <input type="hidden" name="ref_id" value="" />
    <input type="hidden" name="item_name_1" value="item 1" />
    <input type="hidden" name="item_description_1" value="Description for item 1" />
    <input type="hidden" name="item_quantity_1" value="1" />
    <input type="hidden" name="item_amount_1" value="1.00" />
    <input type="hidden" name="item_name_2" value="item 2" />
    <input type="hidden" name="item_description_2" value="Description for item 2" />
    <input type="hidden" name="item_quantity_2" value="1" />
    <input type="hidden" name="item_amount_2" value="1.00" />
    <!--(Optional) input type="hidden" name="delivery_charge" value="0.00" />-->
    <!--(Optional) input type="hidden" name="tax_amount" value="0.00" />-->
    <!--(Optional) input type="hidden" name="tax_percentage " value="8.00" />-->
    <!--(Optional) input type="hidden" name="fulfilled_date_time " value="2016-05-05 22:22" />-->
    <input type="hidden" name="currency" value="SGD" />
    <input type="hidden" name="total_amount" value="2.00" />
    <input type="hidden" name="success_url" value="http://www.yourweb.com/SuccessPage" />
    <input type="hidden" name="cancel_url" value="http://www.yourweb.com" />
    <!--(Optional)<input type="hidden" name="str_url" value="http://www.yourweb.com/StrHandler" />-->
    <input type="hidden" name="signature" value="Replace with your Hashed Signature*" />
    <input type="hidden" name="signature_algorithm" value="sha1" />
    <input type="image" src="https://www.smoovpay.com/img/btn_smoovpay_v1.png" name="submit" alt="SmoovPay!" />
</form>

Button Parameters

Name Description
version Fixed. Please use '2.0'.
action The action of the current payment. Currently, SmoovPay supports only 'pay'
merchant Email address/user ID of the merchant account registered with Smoovpay.
ref_id This ID can be served as the merchant reference ID. This ID should be unique in the merchant system.
item_name_x Title/name for item x (x can range from 1 to 20).
Eg. $4.99 Voucher deal
item_description_x Description for the item x.
item_quantity_x The quantity for item x
item_amount_x The unit price for item x.
item_reference_x (optional) The product reference Id or SKU for item x.
delivery_charge (optional) The amount for delivery charge. (For display only, total amount will not be affected)
Default: 0.00 if not specified
discount_amount (optional) New!The discounted amount. (Eg. -2.50 for discount of $2.50) (For display only, total amount will not be affected)
Default: 0.00 if not specified
tax_amount (optional) The amount for tax. (For display only, total amount will not be affected)
Default: 0.00 if not specified
If specified, the parameter 'tax_percentage' must be specified.
tax_percentage (optional) The percentage of the tax. Eg. '8' (for 8%) (For display only, total amount will not be affected)
Default: 0 if not specified
If specified, the parameter 'tax_amount' must be specified.
fulfilled_date_time (optional) New!This value will be used to determine the voucher redemption eligibility. (Eg. 2016-05-05 22:22)
Default: Current Date Time if not specified
currency Currently, SmoovPay supports only 'SGD' and 'USD'.
Default: 'SGD'
total_amount The total amount to be charged to the customer credit card. It should be the sum of the subtotal for each item, delivery charge, discounted amount and tax amount.
success_url URL to go when users have completed the payment in SmoovPay page.
skip_success_page (optional) Use
'1' - Yes.
'0' - No (default)
If 'skip_success_page' flag is set to '1', customer will not see the SmoovPay success page after payment is made successfully. The customer will instead be redirected back to the provided 'success_url'.

Transaction response and payment details will be added to the 'success_url' and the details are:
- 'merchant'
- 'ref_id'
- 'reference_code'
- 'response_code'
- 'currency'
- 'total_amount'
- 'signature'
- 'signature_algorithm'
The description for each field is exactly the same as the STR fields. Please refer to the 'STR Parameters' section for more information.

Eg.
'success_url' = http://www.website.com/success
When the payment is made successfully, the customer will be redirected to the Url:
http://www.website.com/success?merchant=your@email.com&
ref_id=yourReference&reference_code=SmoovPayReference&
response_code=1&currency=SGD&total_amount=2.00&
signature=52Hoducpo254hoUfhac&signature_algorithm=sha1
cancel_url URL to go when users click 'Cancel' in SmoovPay page.
str_url (optional) SmoovPay Transaction Response Url. When a payment is successfully paid, SmoovPay Server will post a STR to this URL with the transaction details before the customer is redirected to the 'SmoovPay Success Page'.
customer_idd (optional) New!Customer country calling code (IDD) to be pre-populated into the Contact number field inside SmoovPay checkout page. (Ignore the '+' sign)
If specified, the parameter 'customer_contact' must be specified.
customer_contact (optional) New!Customer mobile number to be pre-populated into the Contact number field inside SmoovPay checkout page. (Exclude country calling codes)
If specified, the parameter 'customer_idd' must be specified.
customer_email (optional) New!Customer email address to be pre-populated into the Email field inside SmoovPay checkout page.
signature An unique signature generated using the 'Secret Key' found in your merchant setting page.
Concatenating the following fields:
- Note! Secret Key (Found in your merchant setting page)
- the form post 'merchant' value
- the form post 'action' value (Eg. 'pay')
- the form post 'ref_id' value
- the form post 'total_amount' value (Eg. '2.00')
- the form post 'currency' value (Eg. 'SGD')
For more information on the signature generation, please refer to the 'Signature Generation' section.
signature_algorithm Fixed. Please use 'sha1'.

The signature is used to protect the data exchanged between your server with SmoovPay server. The signature should be generated using the following two steps:

Concatenate the relevant parameters into a single string (Eg. signature for form post):

  • Secret Key (Found in your merchant setting page)
  • The form post 'merchant' value
  • The form post 'action' value (Eg. 'pay')
  • The form post 'ref_id' value
  • The form post 'total_amount' value (Eg. '2.00')
  • The form post 'currency' value (Eg. 'SGD')

Hash the concatenated string using SHA1 algorithm.

Sample codes: PHP

$dataToBeHashed = $secret_key
                . $merchant
                . $action
                . $ref_id
                . $total_amount
                . $currency;
$utfString = mb_convert_encoding($dataToBeHashed, "UTF-8");
$signature = sha1($utfString, false);

Sample codes: ASP .Net (C#)

string dataToBeHashed = SecretKey
                + MerchantEmail
                + Action
                + ReferenceId
                + TotalAmount
                + Currency;
var sha1 = new SHA1CryptoServiceProvider();
var passwordBytes = Encoding.UTF8.GetBytes(dataToBeHashed);
var passwordHash = sha1.ComputeHash(passwordBytes);
var signature = BitConverter.ToString(passwordHash).Replace("-", string.Empty).ToLowerInvariant();

Sample codes: Java

We recommend you to use Apache Commons Codec (version 1.7+) for the hash function.

String dataToBeHashed = SecretKey
                + MerchantEmail
                + Action
                + ReferenceId
                + TotalAmount
                + Currency;
String signature = DigestUtils.sha1Hex(dataToBeHashed);

In this method, server to server call is used. Hence the signature is not required in the POST form.
Usage / Flow:
1. Use
   - PHP : Curl
   - C# : HttpWebRequest/HttpWebResponse or WebClient or HttpClient
   to make a server to server POST to SmoovPay server.
2. SmoovPay will return a JSON response.
3. Decode the JSON response to retrieve the 'redirect_url'.
4. Redirect the customer to the 'redirect_url' to continue with the payment.

Sample Code

<form action="https://sandbox.smoovpay.com/redirecturl" method="post" >
<!-- For actual LIVE account, use https://secure.smoovpay.com/redirecturl -->
    <input type="hidden" name="version" value="2.0" />
    <input type="hidden" name="action" value="pay" />
    <input type="hidden" name="merchant" value="your@email.com" />
    <input type="hidden" name="ref_id" value="" />
    <input type="hidden" name="item_name_1" value="item 1" />
    <input type="hidden" name="item_description_1" value="Description for item 1" />
    <input type="hidden" name="item_quantity_1" value="1" />
    <input type="hidden" name="item_amount_1" value="1.00" />
    <input type="hidden" name="item_name_2" value="item 2" />
    <input type="hidden" name="item_description_2" value="Description for item 2" />
    <input type="hidden" name="item_quantity_2" value="1" />
    <input type="hidden" name="item_amount_2" value="1.00" />
    <!--(Optional) input type="hidden" name="delivery_charge" value="0.00" />-->
    <!--(Optional) input type="hidden" name="tax_amount" value="0.00" />-->
    <!--(Optional) input type="hidden" name="tax_percentage " value="8.00" />-->
    <!--(Optional) input type="hidden" name="fulfilled_date_time " value="2016-05-05 22:22" />-->
    <input type="hidden" name="currency" value="SGD" />
    <input type="hidden" name="total_amount" value="2.00" />
    <input type="hidden" name="success_url" value="http://www.yourweb.com/SuccessPage" />
    <input type="hidden" name="cancel_url" value="http://www.yourweb.com" />
    <!--(Optional)<input type="hidden" name="str_url" value="http://www.yourweb.com/StrHandler" />-->
    <input type="image" src="https://www.smoovpay.com/img/btn_smoovpay_v1.png" name="submit" alt="SmoovPay!" />
</form>

Please refer to Button Parameters for more parameter information and usage.
Note! The "signature" and "signature_method" parameters are not required in this method.

Sample Response (JSON)

{"status":1,"redirect_url":"https://sandbox.smoovpay.com/TokenAccess/47140d8b7eb58b3f1b6d923f4261cb9f","message":"Success"}
Name Type Description
status int 1 - Success
-1 - Failed
redirect_url string The url to be used to redirect the customer to immediately.
message string Contains success message or fail message

Whenever a payment is completed successfully, a SmoovPay Transaction Response (STR) will be sent to the URL in str_url if it's provided:

Sample code

STR handler scripts (PHP version):

<?php          
if ($_SERVER["REQUEST_METHOD"]=="POST") {              
    $secret_key = "MERCHANT SECRET KEY"; 
    $merchant = $_POST['merchant'];
    $ref_id = $_POST['ref_id']; 
    $reference_code = $_POST['reference_code']; 
    $response_code = $_POST['response_code']; 
    $currency = $_POST['currency'];
    $total_amount = $_POST['total_amount'];
    $signature = $_POST['signature'];
    $signature_algorithm = $_POST['signature_algorithm'];
    $dataToBeHashed = $secret_key
                    .$merchant
                    .$ref_id
                    .$reference_code
                    .$response_code
                    .$currency
                    .$total_amount;
    $utfString = mb_convert_encoding($dataToBeHashed, "UTF-8");
    $check_signature = sha1($utfString, false);
    if ($signature == $check_signature) {
        // signature matched
        // check response_code
        // check if ref_id has not been marked as paid before this
        // check if merchant is your merchant email
        // check if total_amount and currency are correct
        // process payment                  
    } else {
        // signature does not matched
        // log for investigation
    }
}
?>

STR parameters

Name Type Description
merchant string(70) Your account email address.
ref_id string(30) Your provided reference Id (the 'ref_id' field)
reference_code string(30) The SmoovPay reference Id
response_code int(1) 1 - Approved
2 - Declined
3 - Error
4 - Refunded
currency string(3) Currency used in the transaction
total_amount decimal(11,2) Amount paid by the customer using credit card.
signature string An unique signature generated using the 'Secret Key' found in your merchant setting page.
Generated by concatenating :
- Note! Secret Key (Found in your merchant setting page)
- the STR parameter 'merchant' value
- the STR parameter 'ref_id' value
- the STR parameter 'reference_code' value
- the STR parameter 'response_code' value (Eg. '1')
- the STR parameter 'currency' value (Eg. 'SGD')
- the STR parameter 'total_amount' value (Eg. '2.00')
For more information on the signature generation, please refer to the 'Signature Generation' section.
signature_algorithm string(5) Fixed, 'sha1'.