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_webhook_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.

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="
})

Create 3D Secure Payment

PARAMETERS FOR AGRICULTURAL CARD PROCESSING

HASH KEY CREATION

SAMPLE CODE