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

Managed Form integration type is suitable for merchants with PCI SAQ A-EP. To know more about the Hosted Payment Page PCI DSS merchant requirements, please check this article.

In this article, we will go through the main parameters that are required for making the managed form requests; and we will clarify each parameter's purpose of use and whether it's required or not, as shown in the below table to assist you more in handling those parameters within your own code. We highly recommend that you and your team check our "3.1.2 - PT2 API Endpoints | Payment workflow | Managed Form" solution article first to understand the business/logic this configuration option relay on.

This is Part one of the two parts of understanding how to initiate a payment request via the Managed Form integration type as clarified in our Step 3.2.2  Managed Form | Initiating the Payment Request solution article. You can find the first part in Step 3.2.2.1 Managed Form | Initiating the payment | Frontend Side.

In this article, you will be going to know about:

• The Endpoint and Related Postman Collection
• The Minimum Required Parameters
• The Available Optional Parameters
• Sample Request Payload 
• Sample Response Payload
  • Via Non-3DSecure Cards
  • Via 3DSecured Cards

The Endpoint and Related Postman Collection

In this tutorial, we will rely on the ClickPay Hosted Payment Page API Endpoint, mentioned on ClickPay 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

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.

At the end of Step 3.2.2.1 Managed Form | Initiating the payment | Frontend Side, you will receive the payment token, which you will use along with the following parameters to initiate the server-side request that will be sent to ClickPay

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:

Now in order to create a payment request through a Managed Form, you will need - in addition to the general required parameters mentioned above-  to include new parameters required specific to the Managed Form. Find below the Additional required parameters for Manage Form:

Sample 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": "SAR",
    "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": "riyadh",
        "state": "riyadh",
        "country": "SA",
        "zip": "45555",
        "ip": "1.1.1.1"
    },
    "payment_token": "Dh4r8Jwt7x6tPMVzKgtk"
}

Sample 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, as shown below:

-Via Non-3DSecure Cards

Via 3DSecured Cards

• 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": "SAR",
      "cart_amount": "500.00",
      "tran_currency": "SAR",
      "tran_total": "500.00",
      "return": "none",
      "customer_details": {
          "name": "Mohammed EL Rayes",
          "email": "[email protected]",
          "phone": "+201234567890",
          "street1": "address street",
          "city": "Riyadh",
          "state": "C",
          "country": "SA",
          "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": 2022
      },
      "serviceId": 8,
      "profileId": 81784,
      "merchantId": 31237,
      "trace": "PMNT0403.638764BE.000037CC"
  }

  JavaScript

   
  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 the issuer required no 3DSecure, 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.clickpay.com.sa/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"
  }

  JavaScript

  
  Regarding Step 3.1.2 Managed 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 ClickPay 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.