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.
The Own-Form integration type is suitable for merchants with SAQ D. To know more about the Own-Form PCI DSS merchant requirements; please check this article.
In this article, we will walk you through how to initiate a payment request via this integration type. You will be introduced to the required parameters that need to be passed to initiate the request, along with all the possible optional parameters as well. We highly recommend that you and your team check the "Step 3.1.3 - Own Form | Payment Workflow" solution article first to understand the business/logic this integration type relay on.
In this article, you will be going to know about:
- The Endpoint and Related Postman Collection
- The Minimum Required Parameters
- The Available Optional Parameters
- The Request payload
- The Response payload
The Endpoint and Related Postman Collection
In this tutorial, we will rely on the PayTabs Own-Form 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.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 |
✔ | 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. | |
✔ | 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. To know more about this parameter please click here. | |
✔ | 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 To know more about this parameter please click here. | |
✔ | Indicates the cart/order id at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
✔ | Indicates the cart/order description at the merchant end to easily relate the transaction to To know more about this parameter please click here. | |
✔ | Indicates the transaction currency, which the customer will be charged with To know more about this parameter please click here. | |
✔ | Indicates the amount the customer is about to be charged. To know more about this parameter please click here. |
Now in order to create a payment request through the Own Form, you need - in addition to the general required above parameters - to include new parameters required specifically for the Own Form. Find below the Additional required parameters for Own Form:
Parameter | Required | Purpose |
✔ | ||
card_details.pan | ✔ | |
card_details.cvv | ✔ | |
card_details.expiry_month | ✔ | |
card_details.expiry_year | ✔ | |
✔ | Indicates the customer details for this payment. To know more about this parameter please click here. | |
customer_details.name | ✔ | |
customer_details.email | ✔ | |
customer_details.phone | ✔ | |
customer_details.street1 | ✔ | |
customer_details.city | ✔ | |
customer_details.state | ✔ | |
customer_details.country | ✔ | |
customer_details.zip | ✔ | |
customer_details.ip | ✔ |
The Available Optional Parameters
Besides the above-mentioned required parameters, PayTabs provides you with several optional parameters, each of which empowers you with a different feature and the ability to customize your payment request as much as possible it could be. The specification of these optional parameters is clarified below:
Parameter | Required | Purpose |
callback | ❌ | The callback response is a server-to-server POST response that is sent (to a pre-defined HTTPS URL) with the full detailed transaction information once the payment process has ended (whether the customer cancels, paid, or failed to pay). It does not depend on the customer's actions; the response will be sent anyway.
|
shipping_details | ❌ | Indicates the shipping details for this payment. If provided, the payment page will be prefilled with the provided data. Learn more about The Shipping Details |
shipping_details.name | ❌ | |
shipping_details.email | ❌ | |
shipping_details.phone | ❌ | |
shipping_details.street1 | ❌ | |
shipping_details.city | ❌ | |
shipping_details.state | ❌ | |
shipping_details.country | ❌ | |
shipping_details.zip | ❌ | |
tokenise | ❌ | The tokenization format the generated token should follow. |
user_defined | ❌ | For more customizations, you can pass to the Transaction API request your own "user-defined fields" up to 9 fields, and accordingly, you would receive those fields in the callback response.
|
user_defined.udf1 | ❌ | |
user_defined.udf2 | ❌ | |
user_defined.udf3 | ❌ | |
user_defined.udf4 | ❌ | |
user_defined.udf5 | ❌ | |
user_defined.udf6 | ❌ | |
user_defined.udf7 | ❌ | |
user_defined.udf8 | ❌ | |
user_defined.udf9 | ❌ |
The Request payload
The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request.
{
"profile_id": "987654",
"tran_type": "sale",
"tran_class": "ecom",
"cart_id": "CART#1001",
"cart_currency": "USD",
"cart_amount": 500,
"cart_description": "Description of the items/services",
"customer_details": {
"name": "Mohammed EL Rayes",
"email": "elrayes@paytabs.com",
"phone": "+201234567890",
"street1": "address street",
"city": "Cairo",
"state": "CAI",
"country": "EG",
"zip": "45555",
"ip": "1.1.1.1"
},
"card_details": {
"pan": "4111111111111111",
"cvv": "123",
"expiry_month": 12,
"expiry_year": 2023
}
}The Response payload
Once the managed form request is validated and initiated, you will receive the following response, There are two scenarios that would change the workflow:
Via Non-3DSecure Cards
If the card does NOT require 3DSecure authentication from the cardholder and issuer side, You will receive a response like the following:{ "tran_ref": "TST2233401397769", "tran_type": "Sale", "cart_id": "CART#1001", "cart_description": "Description of the items/services", "cart_currency": "USD", "cart_amount": "500.00", "tran_currency": "USD", "tran_total": "500.00", "return": "none", "customer_details": { "name": "Mohammed EL Rayes", "email": "elrayes@paytabs.com", "phone": "+201234567890", "street1": "address street", "city": "Cairo", "state": "C", "country": "EG", "zip": "45555", "ip": "1.1.1.1" }, "payment_result": { "response_status": "A", "response_code": "G17534", "response_message": "Authorised", "transaction_time": "2022-11-30T14:12:14Z" }, "payment_info": { "payment_method": "Visa", "card_type": "Credit", "card_scheme": "Visa", "payment_description": "4111 11## #### 1111", "expiryMonth": 12, "expiryYear": 2023 }, "serviceId": 8, "profileId": 81784, "merchantId": 31237, "trace": "PMNT0403.638764BE.000037CC" }
You can notice that the payment is already made, A transaction has been created, and you are already receiving the payment results, unlike the following scenario, since no 3DSecure was required by the issuer, and the transaction had been created.
Via 3DSecured Cards
If the card does require the 3DSecure authentication from the cardholder and issuer side, You will receive a response like the following:{ "tran_ref": "TST2233401397780", "tran_type": "Sale", "cart_id": "CART#1001", "cart_description": "Description of the items/services", "cart_currency": "USD", "cart_amount": "500.00", "tran_currency": "USD", "tran_total": "500.00", "return": "none", "redirect_url": "https://secure-egypt.paytabs.com/payment/page/5974A26182E411E56CCD5245D4EBC0787AF379E9E450E3D8B8E555CF/redirect", "customer_details": { "name": "Mohammed EL Rayes", "email": "elrayes@paytabs.com", "phone": "+201234567890", "street1": "address street", "city": "Cairo", "state": "C", "country": "EG", "zip": "45555", "ip": "1.1.1.1" }, "payment_info": { "payment_method": "Visa", "card_type": "Credit", "card_scheme": "Visa", "payment_description": "4000 00## #### 0002", "expiryMonth": 12, "expiryYear": 2022 }, "serviceId": 8, "profileId": 81784, "merchantId": 31237, "trace": "PMNT0404.63876778.00003813" }Regarding the "Step 3.1.3 - Own Form | Payment Workflow", by initiating the payment, and if the card is 3DSecured, you will receive the redirect URL (redirect_url) within the response. Use this URL to redirect your client browser to the issuer 3DSecure page.
Once the cardholder authenticates using the card (E.G., via OTP), the customer will be redirected back to the return page if it had been set or to the Paytabs default transaction result page if no return page was set. To check more about this, you can navigate to the return URL parameter solution article.
⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The PT2 API Endpoints Integration Manual" solution article.
⇦ And to get familiar with the rest of the steps regarding the previous step "Step 2 - Configure the integration method" kindly click here.
⇦ And to get familiar with the rest of the steps regarding the current step "Step 3 - Initiating the payment" click here.
⇨ And to navigate to the next step in the integration process "Step 4 - Accepting the payment" kindly click here.