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.

Aman is one of the oldest digital wallets which PayTabs offers to its merchants as an alternative payment method to provide consumers/buyers with a faster and more convenient way to make purchases. To know more please check their official site. 


Aman is a payment method that is supported only in Egypt, 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 Aman, for a better understanding of the request/response workflow.



Note Aman 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.



Aman Payment workflow


Unlike the other APMs, Aman has a different workflow, here are the workflow steps:

  1. Create a payment page for Aman.
  2. Once the customer opens the payment page a transaction of the "Payment request" type will be created on your dashboard with a "Pending" status.
  3. The customer will see a screen displaying the reference number and will receive an SMS containing the same reference number
  4. The customer should make the payment using the reference number within 24 hours, either through any Aman POS or their Aman wallet.
  5. Within 30 minutes after the customer pays, a new transaction of the "Sale" type will be created on your dashboard with an "Authorized" status and the old transaction status will be "Authorized" as well.


For more check the last section here

Note if the payment didn't paid within 24 hours, the status of the first transaction will change to "Expired"

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 Aman, you need - in addition to the above general required parameters - to pass Aman within the payment_methods parameter. Find below the Additional required parameters for Aman:



Parameter 

Required 

Purpose 

payment_methods

✔ 

If you need to initiate the payment page for Aman

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 "aman".


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_111111", 
"cart_currency": "EGP", 
"cart_amount": "500", 
"cart_description": "Description of the items/services",  
"payment_methods": [
 "aman" 
],
"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": "https://webhook.site/53aba5b2-2e8d-4104-af30-34976b2fd57d",
"return": "https://webhook.site/53aba5b2-2e8d-4104-af30-34976b2fd57d"
}
Generic


The Response payload


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

{
"tran_ref": "TST2314201601814", 
"tran_type": "Sale",
"cart_id": "cart_111111",
"cart_description": "Description of the items/services",
"cart_currency": "EGP",
"cart_amount": "500.00",
"tran_currency": "",    
"tran_total": "0",    
"callback": "https://webhook.site/6dbfec66-8b66-468f-908a-4cf7636d34b2",    
"return": "none",    
"redirect_url": "https://secure-egypt.paytabs.com/payment/wr/5E98BB6782E4496454058D3E3D8C9C9287CD503C94AA8F84BC4A74DE",   
 "customer_details": {        
"name": "Mohamed Nasser",        
"email": "[email protected]",        
"phone": "0100 860 6003",        
"street1": "address street",        
"city": "cairo",        
"state": "C",        
"country": "EG",        
"zip": "12345",        
"ip": "196.132.79.37"    
},    
"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": "PMNT0404.646B7E7E.00037D9F"  
}
Generic

 

Aman Payment Workflow In Details


Customer User-Experience


Once you created the payment request as clarified above and redirect your customer to the sent payment page "redirect_url", he will experience a payment page as shown below, and he will have to go to any Aman POS station/store to pay for the provided.



Also, according to the Aman process, your customer will immediately receive an SMS like this:

"Please use code# 9133849621 to pay 1,002 LE for GOT Store before 24-12-2021, 04:29 PM ,via Aman (Service code 788)"


The SMS will be sent to the number registered on customer details, NOT the number on shipping details.

Merchant User-Experience


Merchant Initiating Payments' Notifications


  • via The Dashboard

    Once the customer opens the payment page a "Payment Request" transaction will be created on your dashboard with a "Pending" status as shown below, and only then you will be able to identify that your customer navigated successfully to your payment page:

 


  • via the Callback 

    If you passed a callback URL within your first request payload, only then a callback like the shown below would be sent to this provided callback URL to notify your system that your customer has navigated (opened) to the payment page successfully as well:
    {  
"tran_ref": "PTE2**********68",  
"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": "Payment Request",  
"tran_class": "ECom",  
"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"
},
"payment_result": {    
"response_status": "P",   
"response_code": "9133849621",    
"response_message": "Pending",    
"cvv_result": " ",    
"avs_result": " ",    
"transaction_time": "2021-12-23T14:30:02Z"  
},  
"payment_info": {    
"payment_method": "Aman",    
"card_scheme": "",    
"payment_description": "Aman",    
"issuerCountry": "EG",    
"issuerName": "Aman" 
 },  
"ipn_trace": "IPNS0003.********.00000DB5" 
}
    Generic




Merchant Post-Payment Notifications


Merchants can be notified as well post the payment whether the payment was paid successfully, or expired without being paid as clarified below:


  • Expired Payments

    In this case, the payment hasn't been paid till it exceeds the expiry date and becomes no longer valid

    • via The Dashboard

      The status of the previously initiated "Payment Request" transaction on the Paytabs dashboard will be updated to "Expired" as shown below:


    • via the Callback

      If you passed a callback URL within your first request payload, only then a new callback would be triggered/sent with the new transaction status which is expired
      {  
"tran_ref": "PTE21**********8",  
"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": "Payment Request",  
"tran_class": "ECom",  
"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"
},  
"payment_result": {    
"response_status": "X",    
"response_code": "9133849621",    
"response_message": "Expired",    
"cvv_result": " ",    
"avs_result": " ",    
"transaction_time": "2021-12-23T14:30:02Z"  
},  
"payment_info": {    
"payment_method": "Aman",    
"card_scheme": "",    
"payment_description": "Aman",    
"issuerCountry": "EG",    
"issuerName": "Aman"  
},  
"ipn_trace": "IPNS0004.********.00000C54" 
}
      HTML


It's worth mentioning that the expiry date can be calculated regarding the transaction date and time + the expiry period subjected to the agreed one on the onboarding documents.



  • Successfully Paid Payments

    In this case, the payment has been done successfully via one of the Aman POS stations/stores.

    • via The Dashboard

      1- The status of the previously initiated "Payment Request" transaction on the Paytabs dashboard will be updated to "Authorized" as shown below:


      2- A new transaction will be initiated/created with the type "Sale" and will be marked as "Authorized" as a status, coping all its proprieties from the previous transaction as shown below:

  • via the Callback

    If you passed a callback URL within your first request payload, only then a new callback would be triggered/sent with the new "Sale" transaction that has been created as shown below:
    {  
"tran_ref": "PTE2**********9",  
"previous_tran_ref": "PTE21**********8",  
"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": "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"
}, 
"payment_result": {    
"response_status": "A",    
"response_code": "9133849621",    
"response_message": "Authorised",    
"cvv_result": " ",    
"avs_result": " ",    
"transaction_time": "2021-12-23T14:30:02Z" 
},  
"payment_info": {    
"payment_method": "Aman",    
"card_scheme": "",    
"payment_description": "Aman",    
"issuerCountry": "EG",    
"issuerName": "Aman" 
},  
"ipn_trace": "IPNS0004.********.00000C55" 
}
    Generic