Non-Secure / 3D with Paybull

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

Method	URL	Content-Type
POST	< ACCESS_URL >/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_webhook_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'] = '[email protected]';

$invoice['sale_webhook_key'] = 'sale_webhook_key';// This key must be assigned on Paybull 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 paybull 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_webhook_key

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

order_type

If order_type=1 , Paybull 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 Paybull Merchant Panel against this key. Paybull 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 Paybull order id.

invoice_id

invoice_id is merchant invoice_id

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 Paybull. Also Order Status API confirms that the transaction is successful or Failed