Non-Secure / 3D with Sipay

Sipay admin would decide whether the payment from merchant website should be done using 2D or 3D. The following request should be sent to sipay payment integration system from merchant website. The CURL post request should be received at sipay with the following parameters:

Method URL Content-Type
POST /purchase/link application/x-www-form-urlencoded


Type Params Data Type Condition
Key merchant_key string Mandatory
Key invoice string Mandatory
Key currency_code string Mandatory
Key name string Mandatory
Key surname 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 max_installment int Optional
Key sale_web_hook_key string Optional

Request for Recurring

Type Params Data Type Condition
Key order_type string Mandatory
Key recurring_payment_number Integer Mandatory
Key recurring_payment_cycle String Mandatory
Key recurring_payment_interval Integer Mandatory
Key recurring_web_hook_key Integer Mandatory

merchant_key merchant_key is a unique key assigned to the merchant. It must be sent from merchant website.

invoice invoice is a json formated string combined with list of item name, quantity and unit price etc.

For example, if there are three products,

Product 1 #

Name: Item1, Qty: 2, Unit Price: 200

Product 2 #

Name: Item2, Qty: 1, Unit Price: 100

Product 3 #

Name: Item3, Qty: 2, Unit Price: 400

The invoice string will json string of the following array:

$invoice['invoice_id'] = “345345535”; // One unique id which will  be available in the return or cancel URL

$invoice['invoice_description'] = “ INVOICE  TEST DESCRIPTION” ;

$invoice['total'] =  1300

$invoice[discount] =  220 //The amount of coupon code or discount value

$invoice[coupon] =  “3XY8P”  //couponn code in  case applicable

$invoice['return_url'] =  “https://<your_success_url>”

$invoice['cancel_url'] =   “https://<your_fail_or_cancel_url>”

$invoice['items'] = array(

array(“name”=>”Item1”,”price”=>200,”qnantity”=>2,”description”=>”item1 description”),

array(“name”=>”Item2”,”price”=>100,”qnantity”=>1,”description”=>”item2 description”),

array(“name”=>”Item3”,”price”=>400,”qnantity”=>2,”description”=>”item3 description”),

);
//billing info

    $invoice['bill_address1'] = 'Address 1'; //should not more than 100 characters

    $invoice['bill_address2'] = 'Address 2'; //should not more than 100 characters
    $invoice['bill_city'] = 'Istanbul';

    $invoice['bill_postcode'] = '1111';

    $invoice['bill_state'] = 'Istanbul';

    $invoice['bill_country'] = 'TURKEY';

    $invoice['bill_phone'] = '008801777711111';

    $invoice['bill_email'] = 'demo@sipay.com.tr';

$invoice['sale_web_hook_key'] = 'sale_web_hook_key';// This key must be assigned on Sipay Merchant Panel

//Recurring info

    $invoice['order_type'] = 1; //order type 1 for recurring payment

    $invoice[' recurring_payment_number'] = 2; //must be integer value

    $invoice[' recurring_payment_cycle'] = 'M'; // D, M, Y

    $invoice[' recurring_payment_interval'] =  2;  //must be integer value

$invoice[' recurring_web_hook_key'] =  ‘key_name’;  // This key must be assigned in sipay merchant panel.

All taxes  and shipping charges will  be added as item in the invoice  items array.
The item  names should  be  “Tax” and “Shipping Charge” respectively  with quantity 1.

currency_code

currency_code is code of currency. For example USD, TRY, EUR etc.

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 an Sale web hook URL on Sipay Merchant Panel against this key.

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.

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.

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

max_installment It refers to the maximum number of installments to be shown to the user.

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.

Response

After successful request, server will provide a link to the CURL sender. Merchant website needs to redirect to the site to pay.

The following keys will be avilable in the response

Type Params Data Type
Key status string
Key success_message string
Key link string

status

status is result of the API request. “true” for success and “false” for failed.

success_message

success_message is a string describing status of the request

link

link is the URL where merchant website needs to redirect for branded 2d/3d payment processing.

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.

$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 and transaction_type == “Auth” // Transaction is successful and transaction amount is deducted from the card instantly.

Condition 2 : payment_status == 1 and transaction_type == “Pre-Authorization” //Process is successful and transaction amount will be deducted from the card later.

Condition 3 : payment_status == 0 //Transaction is failed

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