3D

The paySmart3D API is used to submit order and credit card details information to SiPay payment integration system. The user will be redirected to the bank page after merchant website submits payment form. Payment would be verified by a SMS code at the bank gateway. Once, payment is successful, the user will be redirected back to merchant success URL, otherwise, it will be redirected to cancel URL set by merchant. In this payment API, there is no need to call getpos API like other payment api called.

Special Notes

1. Do not use ajax request to call paySmart3D api. It must be html form submission to “/api/paySmart3D”

2. Follow sample code given as example file.**
You Can Download Sample Code Here | PaySmart3D.zip

Method URL Content-Type
POST /api/paySmart3D application/x-www-form-urlencoded


Type Params Data Type Condition
KEY cc_holder_name string Mandatory
KEY cc_no string Mandatory
KEY expiry_month string Mandatory
KEY expiry_year string Mandatory
KEY cvv string Mandatory
KEY currency_code string Mandatory
KEY installments_number number Mandatory
KEY invoice_id string Mandatory
KEY invoice_description string Mandatory
KEY name string Mandatory
KEY surname string Mandatory
KEY total double Mandatory
KEY merchant_key string Mandatory
KEY items string Mandatory
KEY cancel_url string Mandatory
KEY return_url string Mandatory
KEY hash_key string Mandatory
KEY bill_address1 string Optional
KEY bill_address2 string Optional
KEY bill_city string Optional
KEY bill_postcode string Optional
KEY bill_state string Optional
KEY bill_country string Optional
KEY bill_email string Optional
KEY bill_phone string Optional
KEY card_program string Optional
KEY ip string Optional
KEY transaction_type string Optional


Duplicate Request

Type Params Data Type Condition
KEY sale_web_hook_key string Optional
KEY order_type Integer Mandatory
KEY recurring_payment_number Integer Mandatory
KEY recurring_payment_cycle string Mandatory
KEY recurring_payment_interval Integer Mandatory
KEY recurring_web_hook_key string Mandatory

Request for Agriculture/Tarim

Type Params Data Type Condition
KEY maturity_period Integer Mandatory
KEY payment_frequency Integer Mandatory

Notes

cancel_url cancel_url, is used to redirect when payment is failed and return_url is used to redirect when payment is successful.

Regardless of fail or success payment, the following keys are available in the query string with cancel and success url:

sipay_status, order_id ve invoice_id. For example, if the successs URL is https://<my-domain.com/, the after successful payment, sipay will redirect to https://<my-domain.com/?sipay_status=1&order_no=234234232&invoice_id=73434

In the query string, if the sipay_status = 1, the " /api/checkstatus " API must be called to clear cart and change order status to “Completed”

name

name First name of the person. For example, if the name of the person who is buying the product is “john Dao”, then name should be “john”

surname

surname Last name of the person. For example, if the name of the person who is buying the product is “john Dao”, then surname should be “Dao”.

sale_web_hook_key

sale_web_hook_key, is an optional key. When a purchase request is completed, Sipay sends a post request. So that merchant can perform an event on their site. Sipay validates this key must me exist in database. Merchant must assign Sale web hook URL on Sipay Merchant Panel against this key.

order_type

If order_type=1, Sipay validates payment for recurring. Then recurring_payment_number, recurring_payment_cycle, recurring_payment_interval keys should not be empty.

Card_program value must be one of following: "WORLD", "BONUS", "MAXIMUM", "BANKKART_COMBO", "PARAF", "AXESS", "ADVANT", "CARD_FNS".

transaction_type

For transaction_type “PreAuth”, a pending transaction is created in the system. But later it is converted to Completed by the merchant's confirmation.

recurring_payment_number

recurring_payment_number, defines installment count. If first_amount is $100 and recurring_payment_number is 5, then the total amount will be deducted as $100*5 = $500. (Cost of transaction may be added with each transaction)

recurring_payment_cycle

recurring_payment_cycle defines unit type of recurring_payment_interval parameter. Possible values: D / M / Y E.g : D: Days , M: Months, Y: Years

recurring_payment_interval

recurring_payment_interval , defines interval value. If recurring_payment_interval = 2 and recurring_payment_cycle = “M” then transaction will be occurred once in every 2 months.

recurring_web_hook_key

recurring_web_hook_key, defines merchant recurring web hook url . An URL must be assigned on Sipay Merchant Panel against this key. Sipay validates this key must me exist in database and it is a required value when payment is recurring.

maturity_period

An integer number have to be sent if transaction is made using agriculture card. Possible maturity_period values can be obtained by calling getpos API

payment_frequency

An integer number have to be sent if transaction is made using agriculture card. Possible payment_frequency values can be obtained by calling getpos API

hash_key

hash_key is declared to secure the payment. End user may change product price before going to bank. Here is the algorithm to write hash key given below.

ip

Represents the ip address the user logged in.

hash_key

hash_keyis declared to secure the payment. End user may change the product price before going to the bank.
Here is the algorithm to write the hash key given below.

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;
}

Response Redirect

After Payment process, the end user is redirected to the merchant website using parameters given below. For response validation we send a hash_key parameter. Merchant can compare request parameter with hash_key decrypted value that is described in 11.5

$params = [
    'payment_status' => $status,
    'order_no' => $order_id,
    'invoice_id' => invoice_id,
    'status_code' => $error_code,
    'status_description' => $status_message,
    'payment_method' => $payment_type,
    'transaction_type' => $transaction_type,
    'error_code' => $error_code,
    'error' => $status_message,
    'hash_key' => $hash_key,

];

payment_status

payment_status = 0/1

0=Failed, 1=Completed

order_id

order_id is Sipay order id.

invoice_id

invoice_id is merchant invoice_id

Response Parameter Explanation

Key Explanation
payment_status payment_staus can be 1/0. 1=success, 0=fail
order_no Sipay order no
invoice_id merchant invoice id
status_code Sipay Status code, 100 is success code
status_description Transaction explanation
payment_method 1= Credit Card, 2= Mobile, 3= Wallet
transaction_type transaction_type == “Auth” //transaction amount is deducted from the card instantly.transaction_type == “Pre-Authorization” transaction amount will be deducted from the card later.
error_code The value of status_code parameter
error The value of status_description parameter
hash_key To Validate the request comes from Sipay

Validate Response:

Condition 1 : payment_status == 1 ve transaction_type == “Auth” // Transaction successful and transaction amount deducted from the card.

Condition 2 : payment_status == 1 ve transaction_type == “Pre-Authorization” // Transaction successful, transaction amount blocked from the credit card. For complete the payment with blocked amount /api/confirmPayment API should call.

hash_key hash_key should be validated on the merchant side to confirm the request comes from Sipay. Also " Order Status "API confirms that the transaction is successful or Failed.

Condition 3 : payment_status == 0 // Transaction fail.

URL

URL
https://provisioning.sipay.com.tr/ccpayment/api/paySmart3D

Request

'cc_holder_name' => 'John Dao',
'cc_no' => '535576595454545',
'expiry_month' => '06',
'expiry_year' => '2022',
'currency_code' => 'TRY',
'installments_number' => '1',
'invoice_id' => '34546434353',
'invoice_description' => 'INVOICE TEST DESCRIPTION',
'total' => '5.00',
'merchant_key' => '$2y$10$w/ODdbTmfubcbUCUq/ia3OoJFMUmkM1UVNBiIQIuLfUlPmaLUT1he',
'items' => '[{"name":"Item3","price":5.00,"qnantity":1,"description":"item3 description"}]',
'name' => 'John',
'surname' => 'Dao',
'hash_key' => '661ebbf2acc9d8bc:cb27:47tnM4SnmuVWRq9YMaHo2npFjXr7Nfe04poc_ri3g_R1NylhHZcj0Zu3Eul4K
7tPmEV2kRxpiDUa8If4xgxAHyM6j+mJaLGL73FFFxoEEJcwhqr5GYOTbQbT7+G2TtnU',
'return_url' => 'http://merchant-domain.com?success.php',
'cancel_url' => 'http://merchant-domain.com?fail.php'

Success Response

{
"sipay_status":"1",
"order_no":"162632108393105",
"invoice_id":"1626321081825",
"status_code":"100",
"status_description":"success",
"sipay_payment_method":"1",
"credit_card_no":"535576****7226",
"transaction_type":"Auth",
"payment_status":"1",
"payment_method":"1","error_code":"100",
"error":"success","hash_key":"a18ed8083e2872ce:e760:dDnLrAvPKQ51rTj3sE2rhfjIf27AAJn3RMKkGDfJWIP7JbCMUoiutBVp9muzqnNp"
}

Failed Response

{
    "sipay_status": "0",
    "order_no": null,
    "invoice_id": "1626326298459",
    "status_code": "102",
    "status_description": "Pos was not defined",
    "sipay_payment_method": "1",
    "credit_card_no": null,
    "transaction_type": "Auth",
    "payment_status": "0",
    "payment_method": "1",
    "error_code": "102",
    "error": "Pos was not defined"
}