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


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

 

Valid card details


To know more about this parameter please click here.

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. 


Learn more about the callback URL Parameter

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. 

Learn more about Token Management

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.


Learn more about The Custom Parameters

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": "[email protected]",
        "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": "[email protected]",
    "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": "[email protected]",
            "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.