Direct Payments

Overview

In this scheme, an online store has its own payment page to collect card data natively through its web site.

If you collect card data on your side and don't want it to be present on your server, you should use seToken (Self Encrypted Token) - a self-signed token used for secure card data transfer. If you use seToken, PCI DSS compliance is not required.

Please note that seToken can be generated via SDK.

Click here to get more information about seToken.

Integration scheme

1. A customer selects a product in the online store, and then clicks Buy.
   
   
2. The online store server receives a purchase request and opens a payment page.
   
   
3. The customer enters their card details on the online store payment page.
   
   
4. The online store server collects the card data.
   
   

5. Initiate payment. The online store server requests an order registration and initiates payment by sending the instantPayment.do API call to the payment gateway. This request must contain the amount parameter (the payment amount in minor currency units) and the backUrl parameter (the address to which the user will be redirected if the payment is successful in Step 10). It also passes the card data to the payment gateway.

   Request example:

   curl --request POST \
   --url  https://gateway-test.jcc.com.cy/payment/rest/instantPayment.do \
   --header 'content-type: application/x-www-form-urlencoded' \
   --data userName=test_user \
   --data password=test_user_password \
   --data amount=100 \
   --data currency=978 \
   --data description=my_first_order \
   --data orderNumber=1218637308 \
   --data pan=5000001111111115 \
   --data cvc=123 \
   --data expiry=203012 \
   --data cardHolderName="TEST CARDHOLDER" \
   --data language=en \
   --data backUrl=https%3A%2F%2Fmybestmerchantreturnurl.com \
   --data failUrl=https%3A%2F%2Fmybestmerchantreturnurl.com

   Response example (3-D Secure is required):

   {
   "errorCode": "0",
   "orderNumber": "1218637308",
   "orderId": "0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0",
   "info": "Your order is proceeded, redirecting...",
   "acsUrl": "https://gateway-test.jcc.com.cy/payment/rest/getwhitepageurl.do?mdOrder=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0&threeDsServerTransId=2aa43ebc-e997-4e54-9ddc-38228bc1d302",
   "paReq": "White page paReq",
   "termUrl": "White page termUrl",
   "orderStatus": {
       "expiration": "203012",
       "cardholderName": "TEST CARDHOLDER",
       "depositAmount": 0,
       "currency": "978",
       "authCode": 2,
       "ErrorCode": "0",
       "ErrorMessage": "Success",
       "OrderStatus": 0,
       "OrderNumber": "1218637308",
       "Pan": "500000**1115",
       "Amount": 100,
       "Ip": "10.99.50.35"
   },
   "is3DSVer2": false
   }

   Response example (3-D Secure is not used):

   {
   "errorCode": "0",
   "orderNumber": "1218637308",
   "orderId": "0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0",
   "info": "Your order is proceeded, redirecting...",
   "redirect": "https://mybestmerchantreturnurl.com/?orderId=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0&lang=en",
   "orderStatus": {
       "expiration": "203012",
       "cardholderName": "TEST CARDHOLDER",
       "depositAmount": 100,
       "currency": "978",
       "approvalCode": "123456",
       "authCode": 2,
       "rrn": "111111111111",
       "ErrorCode": "0",
       "ErrorMessage": "Success",
       "OrderStatus": 2,
       "OrderNumber": "1218637308",
       "Pan": "500000**1115",
       "Amount": 100,
       "Ip": "10.99.50.35"
   },
   "is3DSVer2": false
   }

6. If 3-D Secure is required (the acsUrl parameter is returned in Step 5), the payment gateway communicates with the Directory Server to reach the ACS. It returns all the data necessary for the ACS redirect to the online store.

   If 3-D Secure is not used, the Steps 7-9 are omitted and the customer is redirected to the payment confirmation page (Step 10). The redirect parameter is ignored in this case as the online store uses its own payment confirmation page.
   
   

7. The online store server requests simplified customer redirect to the ACS by sending the acsRedirect.do API call to the payment gateway. The orderId parameter (received in Step 5) is used in the request.

   Request example:

   https://gateway-test.jcc.com.cy/payment/acsRedirect.do?orderId=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0
   

   It is also possible to redirect a customer to ACS with a POST request (regular redirect). The description of this method can be found here.
   

8. The payment gateway redirects the customer to the ACS.
   
   

9. The cardholder confirms the order and the ACS redirects him or her to the payment gateway.
   
   

10. The customer returns to the online store page (to the URL specified during the order registration in Step 5) or closes the page.
    

    Redirect URL example:

    https://mybestmerchantreturnurl.com/?orderId=0179018d-8f96-7fbe-bc2b-4b7e00a7d8c0&lang=en
    
    

11. The payment gateway sends an asynchronous callback notification to the online store server (if callback notifications are enabled).
    
    

12. (Optional) The online store sends the getOrderStatusExtended.do request to the payment gateway to check the order status and make sure the order is really paid. The request contains the orderId parameter received in Step 5. In response, the payment gateway returns the order status in the orderStatus parameter. Status 2 means a successful payment, status 1 means a successful pre-authorization for two-phase payments (the amount needs to be captured in this case). Additionally, the actionCode parameter is returned - it contains the response code from the processing bank. See the list of response codes here.

    Find more details in the Getting the order status section.