Create 3D Secure Payment
paySmart3D API is used to send order and credit card detail information to Paybull payment integration system.
After the merchant website sends the payment form, the user will be directed to the bank page.
The payment will be verified with an SMS code on the bank gateway. After successful payment, the user will be redirected to the merchant's success URL,
Otherwise, the member will be directed to the cancellation URL determined by the merchant.
Do not send AJAX request to /api/paySmart3D
URL. It should be a normal form submission.
Enpoint, Headers and Request information is given below.
Method |
API Endpoint |
Content-Type |
POST |
/api/paySmart3D |
application/x-www-form-urlencoded |
Parameter |
Condition |
Content-Type |
Authorization |
Mandatory |
Bearer |
Parameter |
Data Type |
Condition |
Description |
cc_holder_name |
string |
Mandatory |
Name and Surname on the Card. |
cc_no |
string |
Mandatory |
Card number. |
expiry_month |
string |
Mandatory |
Card expiration month. |
expiry_year |
string |
Mandatory |
Card expiration year. 2030 |
cvv |
string |
Mandatory |
3-digit security code, 4 digits for foreign cards. |
currency_code |
string |
Mandatory |
Currency code. USD , TRY , EUR |
installments_number |
number |
Mandatory |
Number of Installments. |
invoice_id |
string |
Mandatory |
Unique invoice number. |
invoice_description |
string |
Mandatory |
Cart description. |
name |
string |
Mandatory |
Name of the person who purchased the product. |
surname |
string |
Required |
Last name of the person who purchased the product. |
total |
double |
Mandatory |
Amount to be paid. 1000.44 |
merchant_key |
string |
Mandatory |
Unique Member Merchant Key that you received through PayBull |
items |
string |
Mandatory |
Items in cart |
cancel_url |
string |
Mandatory |
Failed payment URL. |
return_url |
string |
Mandatory |
Successful payment URL. |
response_method |
string |
Optional |
POST / GET parameters are passed. |
hash_key |
string |
Mandatory |
Unique key. Ensures that the user cannot make changes to the payment before the transaction reaches the bank and that the payment is completed securely. see Hash Key Generation |
payment_completed_by |
string |
Optional |
app If it is sent, the transaction is sent directly to the bank. / merchant If it is sent, the payment is confirmed/canceled after card verification. see:3D Model Payment Completion |
bill_address1 |
string |
Optional |
1st Address Line of the person who purchased the product. |
bill_address2 |
string |
Optional |
2nd Address Line of the person who purchased the product . |
bill_city |
string |
Optional |
City of the person who purchased the product. |
bill_postcode |
string |
Optional |
Postcode of the person who purchased the product. |
bill_state |
string |
Optional |
County of the person who purchased the product. |
bill_country |
string |
Optional |
Country of the person who purchased the product. |
bill_email |
string |
Optional |
Email address of the person who purchased the product. |
bill_phone |
string |
Optional |
Phone number of the person who purchased the product. |
card_program |
string |
Optional |
One of the values WORLD , BONUS , MAXIMUM , BANKKART_COMBO , PARAF , AXESS , ADVANT , CARD_FNS is sent. |
ip |
string |
Optional |
Represents the ip address of the person who purchased the product. |
transaction_type |
string |
Optional |
PreAuth / Auth parameter is passed. If PreAuth is passed, the transaction must be completed or canceled within 20 days, otherwise it is automatically canceled. |
sale_web_hook_key |
string |
Optional |
Used to receive notification of the successful or failed status of the transaction. Must assign the Sales webhook URL in the Paybull Merchant Panel. |
PARAMETERS FOR AGRICULTURAL CARD PROCESSING
Parameter |
Data Type |
Condition |
Description |
maturity_period |
Integer |
Mandatory |
An integer must be sent if the transaction is agricultural. |
payment_frequency |
Integer |
Mandatory |
An integer must be sent if the transaction is agricultural. |
HASH KEY CREATION
function generateHashKey($total, $installment, $currency_code, $merchant_key, $invoice_id, $app_secret)
{
$data = $total . '|' . $installment . '|' . $currency_code . '|' . $merchant_key . '|' . $invoice_id;
$iv = substr(sha1(mt_rand()), 0, 16);
$password = sha1($app_secret);
$salt = substr(sha1(mt_rand()), 0, 4);
$saltWithPassword = hash('sha256', $password . $salt);
$encrypted = openssl_encrypt("$data", 'aes-256-cbc', "$saltWithPassword", null, $iv);
$msg_encrypted_bundle = "$iv:$salt:$encrypted";
$msg_encrypted_bundle = str_replace('/', '__', $msg_encrypted_bundle);
return $msg_encrypted_bundle;
}
public static string GenerateHashKey(string total,string installment,string currency_code,string merchant_key,string invoice_id,string app_secret){
var data = total + '|'+installment+'|'+currency_code+'|'+merchant_key+'|'+invoice_id;
var sha1 = new SHA1Managed();
Random rnd = new Random();
var iv = sha1.ComputeHash(Encoding.UTF8.GetBytes(rnd.ToString())));
var password = sha1.ComputeHash(Encoding.UTF8.GetBytes(app_secret)).ToString();
rnd = new Random();
var shaSalt = sha1.ComputeHash(Encoding.UTF8.GetBytes(rnd.ToString())).ToString();
var salt = shaSalt.Substring(0, 4);
var sha256 = new SHA256Managed();
var saltWithPassword = sha256.ComputeHash(Encoding.UTF8.GetBytes(password+salt));
var encrypted = EncryptString(data,saltWithPassword,iv);
var msg_encrypted_bundle = iv + ":" + salt + ":" + encrypted;
msg_encrypted_bundle = msg_encrypted_bundle.Replace("/","__");
return msg_encrypted_bundle;
}
public static string EncryptString(string plainText, byte[] key, byte[] iv){
Aes encryptor = Aes.Create();
encryptor.Mode = CipherMode.CBC;
encryptor.Key = key;
encryptor.IV = iv;
MemoryStream memoryStream = new MemoryStream();
ICryptoTransform aesEncryptor = encryptor.CreateEncryptor();
CryptoStream cryptoStream = new CryptoStream(memoryStream, aesEncryptor, CryptoStreamMode.Write);
byte[] plainBytes = Encoding.ASCII.GetBytes(plainText);
cryptoStream.Write(plainBytes, 0, plainBytes.Length);
cryptoStream.FlushFinalBlock();
byte[] cipherBytes = memoryStream.ToArray();
memoryStream.Close();
cryptoStream.Close();
string cipherText = Convert.ToBase64String(cipherBytes, 0, cipherBytes.Length);
return cipherText;
}
function generateHashKey(total , installment , currency_code , merchant_key , invoice_id , app_secret) {
var data = total + "|" + installment + "|" + currency_code + "|" + merchant_key + "|" + invoice_id;
var randNumIv = Math.floor(Math.random() * (99999999999999999 - 10000000000000000) + 10000000000000000);
var hashNumIv = sha1(randNumIv);
hashNumIv = hashNumIv.create();
var iv = hashNumIv.slice(0,16);
var hashPass = sha1(app_secret);
hashPass = hashPass.create();
var password = hashPass.hex();
var randNumSalt = Math.floor(Math.random() * (99999999999999999 - 10000000000000000) + 10000000000000000);
var hashNumSalt = sha1(randNumIv);
hashNumSalt = hashNumSalt.create();
var salt = hashNumSalt.hex();
var strPassSalt = password + salt;
var hashStr = sha1(strPassSalt);
strPassSalt.create();
var saltWithPassword = strPassSalt.hex();
var encrypted = "";
var msg_encrypted_bundle = iv + ":" + salt + ":" + encrypted;
msg_encrypted_bundle = msg_encrypted_bundle.replaceAll("/" , "_");
return msg_encrypted_bundle;
}
import random
from Crypto.Hash import SHA1
from Crypto.Hash import SHA256
def generateHashKey(total, installment, currency_code, merchant_key, invoice_id , app_secret) :
data = total + "|" + installment + "|" + currency_code + "|" + merchant_key + "|" + invoice_id
randNumIv = str(random.randint(10000000000000000,99999999999999999))
hashNumIv = SHA1.new()
hashNumIv.update(randNumIv.encode("UTF-8"))
hashNumber = hashNumIv.hexdigest()
iv = hashNumber[:16]
hashAppSec = SHA1.new()
hashAppSec.update(app_secret.encode("UTF-8"))
password = hashAppSec.hexdigest()
randNumSalt = str(random.randint(10000000000000000,99999999999999999))
hashNumSalt = SHA1.new()
hashNumSalt.update(randNumSalt.encode("UTF-8"))
hashSalt = hashNumSalt.hexdigest()
salt = hashSalt[:4]
strPassSalt = password + salt
hashStr = SHA256.new()
hashStr.update(strPassSalt.encode("UTF-8"))
saltWithPassword = hashStr.hexdigest()
encrypted = ""
msg_encrypted_bundle = iv + ":" + salt + ":" + encrypted
msg_encrypted_bundle = msg_encrypted_bundle.replace("/" , "_")
return msg_encrypted_bundle
SAMPLE CODE
payment_status = 1 Completed ,payment_status = 0 Failed
<form target="_top" action="https://test.paybull.com/ccpayment/api/paySmart3D" method="post" id="three_d_form">
<input type="hidden" name="cc_holder_name" value="John Dao"/>
<input type="hidden" name="cc_no" value="4508034508034509"/>
<input type="hidden" name="expiry_month" value="12"/>
<input type="hidden" name="expiry_year" value="26"/>
<input type="hidden" name="cvv" value="000"/>
<input type="hidden" name="currency_code" value="TRY"/>
<input type="hidden" name="installments_number" value="1"/>
<input type="hidden" name="invoice_id" value="PAYBULL-INVOICE-1"/>
<input type="hidden" name="invoice_description" value="INVOICE TEST DESCRIPTION"/>
<input type="hidden" name="name" value="John"/>
<input type="hidden" name="surname" value="Dao"/>
<input type="hidden" name="total" value="10.00"/>
<input type="hidden" name="merchant_key" value="$2y$10$w/ODdbTmfubcbUCUq/ia3OoJFMUmkM1UVNBiIQIuLfUlPmaLUT1he"/>
<input type="hidden" name="cancel_url" value="FAIL URL"/>
<input type="hidden" name="return_url" value="SUCCES URL"/>
<input type="hidden" name="hash_key" value="32d54deec44e1d10:b45b:FCi9MQ...."/>
<input type="hidden" name="items" value='[{"name": "ITEM", "price":10.00, "quantity":1, "description": "DESCRIPTION"}]'/>
<input type="submit" value="Pay" />
</form>
{
"order_no": 167879639814398,
"order_id": 167879639814398,
"invoice_id": "1678796401PAYBULL",
"status_code": 100,
"status_description": "Payment Successfully Completed",
"credit_card_no": "540667****5403",
"transaction_type": "auth",
"payment_status": 1,
"payment_method": 1,
"error_code": 100,
"error": "Payment Successfully Completed",
"auth_code": 262818,
"merchant_commission": 0,
"user_commission": 0,
"merchant_commission_percentage": 0,
"merchant_commission_fixed": 0,
"installment": 1,
"amount": 10,
"hash_key": "6781df462c7582b9:b645:3ExMA6uvr6y3h3L7MXjhGFLSpPVP8ox2bx__tqx8__shp2MlEQLOkfo9Y0ceHySRVX",
"md_status": 1,
"original_bank_error_code": "",
"original_bank_error_description": ""
}
{
"order_no": "167879630753329",
"order_id": "167879630753329",
"invoice_id": "1678796307PAYBULL",
"status_code": "41",
"status_description": "N-status/Challenge authentication via ACS: https://emvacs.bkm.com.tr/acs/creq",
"credit_card_no": "540667****5403",
"transaction_type": "auth",
"payment_status": 0,
"payment_method": 1,
"error_code": 41,
"error": "N-status/Challenge authentication via ACS: https://emvacs.bkm.com.tr/acs/creq",
"auth_code": "",
"merchant_commission": 0,
"user_commission": 0,
"merchant_commission_percentage": 0,
"merchant_commission_fixed": 0,
"installment": 1,
"amount": 10,
"hash_key": "166d91df38bcd714:720e:HMFSjSLvbicqoHJUu1p+wDZ8oqBSR3YsTjqa2q3nW8dHqePOYhH78yypXOO0Oe5l",
"md_status": 0,
"original_bank_error_code": 99,
"original_bank_error_description": "Authentication failed"
}
{
"order_no": "",
"order_id": "",
"invoice_id": "1678797131PAYBULL",
"status_code": 68,
"status_description": "Invalid hash key",
"credit_card_no": "",
"transaction_type": "auth",
"payment_status": 0,
"payment_method": 1,
"error_code": 68,
"error": "Invalid hash key",
"auth_code": "",
"hash_key": "f37135dd8bc6ebca:4042:8lWRu9cq4cDTVGN0HrclX+Uz+x78LxrIWdsHWX16CvI="
})