PayBolt API Integration
PayBolt Integration
- 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>
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:
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¤cy=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:
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:
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')
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);
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);
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.
{"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:
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
}
}
?>
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) |
|
Name | Type | Description |
| |
|
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 :
For more information on the signature generation, please refer to the 'Signature Generation' section. |
signature_algorithm | string(5) | Fixed, 'sha1'. |