PayBolt API Integration

PayBolt Integration

For Developers

  1. 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.
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. 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. 1.
    Use
  • PHP : Curl
  • C# : HttpWebRequest/HttpWebResponse or WebClient or HttpClient to make a server to server POST to PayBolt server.
  1. 1.
    PayBolt will return a JSON response.
  2. 2.
    Decode the JSON response to retrieve the 'redirect_url'.
  3. 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)
  1. 1.
    - Completed
  2. 2.
    - Declined
Name
Type
Description
  1. 1.
    - Error
  2. 2.
    - 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'.