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.

valU is the most powerful application in Egypt through which you can pay in more than 3,500 places and online. You can also gift it to anyone through To-U, the first e-gift card in Egypt.

It provides customers with an easier, more convenient, and faster approval process to buy everything they need and pay in installments over the period that suits them from six months to 60 months without a down payment and interest-free offers throughout the year.



Note ValU and all of our APMs are available ONLY via our hosted payment page



In this article you will be going to know about:

The Endpoint and Related Postman Collection


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


Post{{domain}}/payment/request


Please note that not using the proper endpoint URI {{domain}} will lead to authentication issues within your responses. To find the your proper domain you can read our What Is My (Region)/(endpoint URL)? solution article.



ValU Payment workflow


  1. Create a payment page for ValU.
  2. The customers will see a screen asking them to add their ValU phone number.
  3. After clicking on 'Pay Now', they will be taken to a screen where they can add the down payment/ToU/cashback values and choose the installment plan.
  4. The customer should then add the OTP and click 'Submit' to confirm the payment.



Note that you can manage ValU settings (down payment, ToU, and cashback) through your dashboard in the 'Developers' tab, as shown below.


The Minimum Required Parameters


To initiate a payment request using this integration type, there are minimum required parameters that need to be passed with valid information. The specification of these required parameters is clarified below.


Parameter 

Required 

Purpose 

profile_id 

✔ 

The merchant Profile ID you can get from your PayTavs dashboard. For more information please check our How to get your account information from PT2 Dashboard? solution article.


To know more about this parameter please click here.

tran_type 

✔ 

The identification of the type of transaction. To know more about these types please check our What is the "tran_type" (transaction type)? solution article. 


For this request, the transaction type MUST be "sale"

To know more about this parameter please click here.

tran_class 

✔ 

The identification of the category/class this transaction will follow, such as eCommerce, Recurring, etc. To know more about these types please check our What is the "tran_class" (transaction class)? solution article


For this request, the transaction class MUST be "ecom".


To know more about this parameter please click here.

cart_id 

✔ 

Indicates the cart/order id at the merchant end to easily relate the transaction to 


To know more about this parameter please click here.

cart_description 

✔ 

Indicates the cart/order description at the merchant end to easily relate the transaction to 


To know more about this parameter please click here.

cart_currency 

✔ 

Indicates the transaction currency, which the customer will be charged with 


To know more about this parameter please click here.

cart_amount 

✔ 

Indicates the amount 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 click here.


Now, In order to create a payment request through valu, you need - in addition to the above general required parameters - to pass valu within the payment_methods parameter. Find below the Additional required parameters for valu:



Parameter 

Required 

Purpose 

payment_methods 

✔ 

If you need to initiate the payment page for ValU

To initiate the payment page with one or more specific payment methods, which should be configured first in your profile. 

To know more about this parameter please click here.

For this request, you MUST pass "valu".


The Available Optional Parameters

Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, as same as the parameters of the hosted payment page, check it here.

The Request payload 


As the payment page is on your side (merchant side), you must send a payment request using the transaction API after receiving the card details from your payment page. You will need to include the customer details in the payment request.



{    
"profile_id": {{profile_id}},    
"tran_type": "sale",    
"tran_class": "ecom",    
"cart_id": "cart_1111111",    
"cart_description": "Description of the items/services",    
"cart_currency": "EGP",    
"cart_amount": 500,    
"payment_methods": 
[        
"valu"    
 ],    
"customer_details": {        
"name": "Mohamed Nasser",        
"email": "[email protected]",        
"phone": "01008606003",        
"street1": "address street",        
"city": "cairo",        
"state": "eg",        
"country": "EG",        
"zip": "12345"    
},    
"shipping_details": {         
"name": "Mohamed Nasser",        
"email": "[email protected]",        
"phone": "01008606003",        
"street1": "address street",        
"city": "cairo",        
"state": "eg",        
"country": "EG",        
"zip": "12345"    
},    
"paypage_lang": "en",    
"callback": "{{callback_url}}",    
"return": "{{return_url}}" 
}
Generic


Generic
Note that the minimum amount to initiate a payment via ValU is 500 EGP.



The Response payload


Once the request is validated and initiated, you will receive the following response.

{    
"tran_ref": "TST2314301602395",    
"tran_type": "Sale",    
"cart_id": "cart_1111111",    
"cart_description": "Description of the items/services",    
"cart_currency": "EGP",    
"cart_amount": "500.00",    
"tran_currency": "",    
"tran_total": "0",    
"callback": "https://webhook.site/aa67fd12-a275-4ba9-ad4b-2f14ae8d6720",    
"return": "none",    
"redirect_url": "https://secure-egypt.paytabs.com/payment/wr/5E9FBC5982E465C13B536C6DAC0675E01515AAFD3CA038FCD4E21B33",    
"customer_details": {        
"name": "Mohamed Nasser",        
"email": "[email protected]",        
"phone": "0100 860 6003",        
"street1": "address street",        
"city": "cairo",        
"state": "C",        
"country": "EG",        
"zip": "12345",        
"ip": "41.187.92.43"    
},    
"shipping_details": {        
"name": "Mohamed Nasser",        
"email": "[email protected]",        
"phone": "01008606003",        
"street1": "address street",        
"city": "cairo",        
"state": "C",        
"country": "EG",        
"zip": "12345"    
},    
"serviceId": 2,    
"profileId": {{profile_id}},    
"merchantId": {{merchant_id}},    
"trace": "PMNT0403.646C7940.00041806" 
}
Generic

 

The Callback response payload


Once the customer has paid, you will receive the following as a POST request to the configured IPN.


To know more about managing IPNs please check our How to configure Instant payment notification (IPN)? solution article.



{  
"tran_ref": "TST2314301602395",  
"merchant_id": {{merchant_id}},  
"profile_id": {{profile_id}},  
"cart_id": "cart_1111111",  
"cart_description": "Description of the items/services",  
"cart_currency": "EGP",  
"cart_amount": "500.00",  
"tran_currency": "EGP",  
"tran_total": "500.00",  
"tran_type": "Sale",  
"tran_class": "ECom",  
"customer_details": {    
"name": "Mohamed Nasser",    
"email": "[email protected]",    
"phone": "01008606003",    
"street1": "address street",    
"city": "cairo",    
"state": "C",    
"country": "EG",    
"zip": "12345",    
"ip": "41.187.92.43" 
},  
"shipping_details": {    
"name": "Mohamed Nasser",    
"email": "[email protected]",    
"phone": "01008606003",    
"street1": "address street",    
"city": "cairo",    
"state": "C",    
"country": "EG",    
"zip": "12345"  
},  
"payment_result": {    
"response_status": "A",    
"response_code": "230523288452135",    
"response_message": "Authorised",    
"acquirer_message": "SUCCESS",    
"acquirer_rrn": "CL230523934052",    
"cvv_result": " ",    
"avs_result": " ",    
"transaction_time": "2023-05-23T08:30:31Z"  
},  
"payment_info": {    
"payment_method": "ValU",    
"card_scheme": "",    
"payment_description": "ValU",    
"issuerCountry": "EG",    
"issuerName": "ValU"  
},  
"valU": {    
"loan_number": "CL230523934052",    
"first_emi_due_date": "01/07/2023",   
"last_installment_date": "01/12/2023",    
"tenure": 6,    
"product_price": "500.00",    
"discount": "0.00",    
"expense": "0.00",    
"due_amount": "0.00",    
"emi": "93.00",    
"down_payment": "0.00",    
"admin_fees": "25.00",    
"financed_amount": "500.00"  
},  
"ipn_trace": "IPNS0004.646C79A7.0000D5B3" 
}
Generic