PayBolt API Integration

PayBolt Integration

For Developers

1. Embed the Payment Button

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://api.pboltdev.com/pay" method="post">
<!-- For actual LIVE account, use https://api.paybolt.com/pay -->
<input type="hidden" name="version" value="1" />
<input type="hidden" name="action" value="capture" />
<input type="hidden" name="merchant_id" value="0001283733" />
<input type="hidden" name="merchant_reference_id" value="" />
<input type="hidden" name="currency" value="USD" />
<input type="hidden" name="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="skip_success_page" value="0" />-->
<!--(Optional)<input type="hidden" name="ptr_url" value="http://www.yourweb.com/PtrHandler" />-->
<input type="hidden" name="signature" value="Replace with your Hashed Signature*" />
<input type="hidden" name="signature_algorithm" value="sha1" />
<input type="submit" name="submit" value=" PayBolt" alt="PayBolt" />
</form>

Button Parameters

Name	Description
version	Fixed. Please use '1'.
action	The action of the current payment. Currently, PayBolt supports only 'capture'

Name	Description
merchant_id	Merchant ID provided by PayBolt.
merchant_reference_id	This ID can be served as the merchant reference ID. This ID should be unique in the merchant system.
currency	Currently, PayBolt supports only 'USD'. Default: 'USD'
amount	The total amount to be charged to the customer. 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 PayBolt page.
cancel_url	URL to go when users click 'Cancel' in PayBolt 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 PayBolt 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_id' 'merchant_reference_id' 'paybolt_reference_id' 'response_code' 'currency' 'amount' 'signature' 'signature_algorithm' The description for each field is exactly the same as the PTR fields. Please refer to the ‘PTR 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_id=0001283733& merchant_reference_id=yourReference&paybolt_reference_id= PayBoltReference

Name	Description
	response_code=1&currency=USD&amount=2.00& signature=52Hoducpo254hoUfhac&signature_algorithm=sha1
ptr_url (optional)	PayBolt Transaction Response Url. When a payment is successfully paid, PayBolt Server will post a PTR to this URL with the transaction details before the customer is redirected to the ' PayBolt Success 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_id' value the form post 'action' value (Eg. 'capture') the form post 'merchant_reference_id' value the form post 'amount' value (Eg. '2.00') the form post 'currency' value (Eg. 'USD') For more information on the signature generation, please refer to the 'Signature Generation' section.
signature_algorithm	Fixed. Please use 'sha1'.

1. Signature Generation

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

Step 1

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_id' value
·         The form post 'action' value (Eg. 'capture')
·         The form post 'merchant_reference_id' value
·         The form post 'amount' value (Eg. '2.00')
·         The form post 'currency' value (Eg. 'USD')

Step 2

Hash the concatenated string using SHA1 algorithm.

Sample codes: PHP

$dataToBeHashed = $secret_key
. $merchant_id
. $action
. $merchant_reference_id
. $amount
. $currency;
$utfString = mb_convert_encoding($dataToBeHashed, "UTF-8");
$signature = sha1($utfString, false);

Sample codes: ASP .Net (C#)

string dataToBeHashed = SecretKey
+ MerchantId
+ Action
+ MerchantReferenceId
+ Amount
+ 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
+ MerchantId
+ Action
+ MerchantReferenceId
+ Amount
+ Currency;
String signature = DigestUtils.sha1Hex(dataToBeHashed);

Redirect Method (Signature is not required)

New!

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 PayBolt server.

1. PayBolt will return a JSON response.

2. Decode the JSON response to retrieve the 'redirect_url'.

3. Redirect the customer to the 'redirect_url' to continue with the payment.

Sample Code

<form action="https://api.pboltdev.com/pay/url" method="post" >
<!-- For actual LIVE account, use https://api.paybolt.com/pay/url -->
<input type="hidden" name="version" value="1" />
<input type="hidden" name="action" value="capture" />
<input type="hidden" name="merchant_id" value="0001283733" />
<input type="hidden" name="merchant_reference_id" value="Order01" />
<input type="hidden" name="currency" value="USD" />
<input type="hidden" name="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="ptr_url" value="
http://www.yourweb.com/PtrHandler
" />-->
<input type="submit" name="submit" value="PayBolt" alt="PayBolt" />
</form>

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

Sample Response (JSON)

{"status":1,"redirect_url":"https://gateway.paybolt.com/pay?sid=47140d8b7eb58b3f1b","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

4. [Optional] PayBolt Transaction Response (PTR) Parameters

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

Sample code

PTR handler scripts (PHP version):

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

PTR parameters

Name	Type	Description
merchant_id	string(70)	Your account email address.
merchant_reference_id	string(30)	Your provided reference Id (the 'merchant_reference_id' field)
paybolt_reference_id	string(30)	The PayBolt reference Id
response_code	int(1)	- Completed - Declined

Name	Type	Description
		- Error - Refunded
currency	string(3)	Currency used in the transaction
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 PTR parameter 'merchant_id' value the PTR parameter 'merchant_reference_id' value the PTR parameter 'paybolt_reference_id' value the PTR parameter 'response_code' value (Eg. '1') the PTR parameter 'currency' value (Eg. 'USD') the PTR parameter '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'.