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 is code of currency. For example USD, TRY, EUR etc.


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


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 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 , defines unit type of recurring_payment_interval parameter. Possible values: D / M / Y e.g: D: Days , M: Months , Y: Years


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.


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


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 is result of the API request. “true” for success and “false” for failed.


success_message is a string describing status of the request


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 = 0/1 0=Failed, 1=Completed


order_id is Paybull order 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