Create VIBAN Payment Request

PayTabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages.

Be Aware Of

Be aware that VIBAN MUST be enabled in your PayTabs profile in order to perform any payments using it, so kindly make sure to contact [email protected] or your account manager requesting to enable VIBAN.

VIBAN is a payment method that is supported only in Saudi Arabia, and its payment workflow is a little bit different from payments via credit/debit card workflow. In the article, we will walk you through the transaction API via VIBAN, for a better understanding of the request/response workflow.

---

The Endpoint and Related Postman Collection

In this tutorial, we will rely on the API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access fromKSA PayTabs Postman APIs Collection. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST	{{domain}}/payment/viban/new

Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

KSA

https://secure.paytabs.sa/payment/viban/new

---

Request Parameters

To initiate a direct payment request using this endpoint, there are minimum required parameters that need to be passed with valid information. The specification of both required parameters and all the other optional parameters/features that can be used are clarified below:

The Minimum Required Parameters

Parameter	Data Type	Min	Max	Required
profile_id	INT STRING	Accept only valid profile number.		✔
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article. To know more about this parameter please click here.
	{ "profile_id": 987654 }

Parameter	Data Type	Min	Max	Required
cart_id	STRING	1	64	✔
	Indicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to. To know more about this parameter please click here.
	{ "cart_id": "CART#10001" }

Parameter	Data Type	Min	Max	Required
cart_description	STRING	1	128	✔
	Indicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to. To know more about this parameter please click here.
	{ "cart_description": "Description of the items/services" }

Parameter	Data Type	Min	Max	Required
currency	STRING	1	128	✔
	Indicates the transaction currency, which the customer will be charged with. To know more about this parameter please .
	{ "currency": "SAR" }

Parameter	Data Type	Min	Max	Required
amount	INT | FLOAT	0.01	9999999999.99	✔
	Indicates the amount of the transaction the customer is about to be charged. Both min and max values are subjected to the merchant transaction limits. To know more about this parameter please .
	{ "amount": 500.99 }

---

Request & Response Payload Samples

This section is dedicated give you a sample API request payload using the above mentioned required parameters, along with showing you the response payload received upon using the request payload.

Required Parameters Sample Payloads

The below sample request payload will show you how you can pass the above-mentioned required parameter/s, which are needed to be passed with valid values to perform a request. Along with the response payload received after using this request payload.

Sample Request Payload

{                     
"profile_id": 106721, 
"cart_id":"89898", 
"cart_description":"new",  
"amount": 10,  
"currency": "SAR" 
 }

Sample Response Payload

{
"viban_ref": "VB000000020102", 
"viban": "SA4730100944000000000060", 
"profile_id": 106721, 
"status": 1, 
"currency": "SAR", 
"total_amount": "10.00", 
"paid_amount": "0.00", 
"cart_id": "89898", 
"cart_description": "new" 
}

---

The Payment Flow Experience

Reaching this stage, you are now able to initiate a VIBAN payment using the direct API request. Please note that the VIBAN payment flow differs from the standard payment process. Below is a clear breakdown of how it works:

1. Triggering the VIBAN Payment Process:
   1. The merchant’s system initiates the VIBAN payment request.
   2. The request must follow the specifications provided in theRequest & Response Payload Samples.


2. Receiving the VIBAN Number:Once the request is successfully processed, PayTabs returns the VIBAN details, including:
   "viban": "SA4730100944000000000060"


3. Sharing the VIBAN Number with the Customer:The merchant provides the VIBAN to the customer, typically displayed directly on screen.


4. Customer Completes the Payment:The customer uses their bank platform to transfer the payment to the provided virtual IBAN.

Summary of the Payment Flow:

1. The merchant’s system sends the VIBAN payment request.


2. PayTabs responds with a VIBAN Number.


3. The VIBAN Number is shared with the customer.


4. The customer completes the payment by transferring the amount to the provided VIBAN through their bank or any IBAN-enabled application.