Guides

STC Pay

Embedded Payment

Suggest Edits

Introduction

STC Pay Embedded enables you to give your customers a better user experience when paying using STC Pay. It enables your customers to enter their card information directly on your checkout page instead of being redirected.

MyFatoorah STC Pay embedded payment is a Javascript library that provides a form for collecting the mobile number and OTP from the customer. This form can be placed and styled on your checkout page. When your customer enters the mobile number and his OTP, MyFatoorah will enable you to complete the payment using the ExecutePayment endpoint by following the below steps.

How it Works

👍

Before You start

Kindly refer to the prerequisite section in the Embedded Payment.

The following detailed steps will explain how to add the MyFatoorah Embedded STC Pay to your checkout page.

1. Call InitiateSession endpoint

After you call the InitiateSession endpoint, you will get a SessionId and the CountryCode.

{
    "IsSuccess": true,
    "Message": "Initiated Successfully!",
    "ValidationErrors": null,
    "Data": {
        "SessionId": "dfc6a3c3-df09-44cb-9c6a-0a6375752da6",
        "CountryCode": "KWT",
        "CustomerTokens": []
    }
}

2. Include the Javascript library

Choose the test or the live library according to your working environment.

// Test Environment
<script src="https://demo.myfatoorah.com/stcPay/v1/stcpay.js"></script> 

// Live Environment For Saudi Arabia
<script src="https://sa.myfatoorah.com/stcPay/v1/stcpay.js"></script>

3. Add the form

You need to define a div element with a unique id attribute. The form will be loaded inside this div after passing the div id to the configuration variable.

<div id="mf-stc-pay"></div>

4. STC Pay Configuration

Now you need to add the configuration variables. Place the following snippet in a new script tag after loading the library in step 1, and replace the sessionId parameter with the "SessionId" you receive from the InitiateSession Endpoint. You should call myFatoorahStc.init using the configuration variable that you created.

For the countyCode parameter check our list of ISO Lookups. You should add the CountryCode that you receive in the response of InitiateSession.

		var configStcPay = {
			sessionId: session, //Here you add the "SessionId" you receive from InitiateSession Endpoint.
			countryCode: country, //Here, add your "CountryCode" you receive from InitiateSession Endpoint.
			amount: amount,
			mobileNumber: "0557877988",
			containerId: "mf-stc-pay",
			callback: paymentSt
    }
myFatoorahStc.init(configStcPay);

This will load the STC Pay view on your checkout page.

Using your display of STC Pay:

MyFatoorah allows you to integrate STC Pay functionalities seamlessly into your application, enabling payments via STC Pay using your own custom user interface, without displaying MyFatoorah's view.

Steps:
  1. You must add a value for the mobileNumber and don't add a value for the containerId in the configuration variable. Then you call myFatoorahStc.init(configStcPay);. MyFatoorah then will trigger the sessionStarted function returning to you the SessionId and the expiryDuration for the OTP to display it to your customer, and sends the OTP to the customer.
		var configStcPay = {
			sessionId: session, //Here you add the "SessionId" you receive from InitiateSession Endpoint.
			countryCode: country, //Here, add your "CountryCode" you receive from InitiateSession Endpoint.
			amount: amount,
			mobileNumber: "0557877988",
      sessionStarted: sessionStarted,
			callback: paymentStc
    }
		function sessionStarted(response) 
		{ 
		<!-- Here you need to display the OTP UI to the customer -->
			var sessionId = response.sessionId; 
			console.log("response from SessionStarted >> ", response); 
		};
myFatoorahStc.init(configStcPay);


{
    "isSuccess": true,
    "sessionId": "f0b0e33f-3e3e-403c-855c-ef6a0c778ec5",
    "expiryDuration": 120
}
  1. You will collect the OTP on your user interface and send it to MyFatoorah in the function myFatoorahStc.submitOtp(value);. When you call the function, MyFatoorah again triggers the callback function giving you the SessionId. You will then use the SessionId to call ExecutePayment.
myFatoorahStc.submitOtp("1234");

{
    "isSuccess": true,
    "sessionId": "f0b0e33f-3e3e-403c-855c-ef6a0c778ec5"
}

5. Handle the Callback function

After the customer completes the payment details entry, MyFatoorah triggers the CallBack function and returns the SessionId to you. You should send the SessionId to your backend to call ExecutePayment to complete the payment.

function paymentStc(response) {
  if (response.isSuccess) {
    console.log(response);
    var sessionId = response.sessionId;
    console.log("SessionID >> ", sessionId);
  } else {
    console.log(response);
  }
}

6. Call the ExecutePayment Endpoint

Then, you need to send the SessionId to your server to process the actual transaction, which should be done in your backend environment using ExecutePayment endpoint.

❗️

Parameters conflict

Do not pass the PaymentMethodId parameter in the ExecutePayment request and use the SessionId parameter instead. As PaymentMethodId overwrite SessionId.

The "SessionId" you receive from InitiateSession Endpoint can not be used directly in ExecutePayment Endpoint.

You will get the PaymentURL in the Response Model. This payment URL is the 3D Secure page URL as this type of payment supports only the 3D Secure Flow. In this case, you should redirect the customer to this URL to complete the 3D Secure challenge.

{
   "SessionId":"8b521de0-4f92-4a17-b277-6f6f87435118",
   "InvoiceValue":10,
}

{
   "IsSuccess":true,
   "Message":"Invoice Created Successfully!",
   "ValidationErrors":null,
   "Data":{
      "InvoiceId":123456,
      "IsDirectPayment":false,
      "PaymentURL":"https://demo.MyFatoorah.com/En/KWT/PayInvoice/MpgsAuthentication?paymentId=0706104008982520266&sessionId=SESSION0002087297105E3203998J76",
      "CustomerReference":"",
      "UserDefinedField":null,
      "RecurringId":""
   }
}

👍

Payment Status

To update your system automatically instead of manually following up with your customers via your portal account, you can use the Webhook feature or/and set the CallBackURL/ErrorUrl parameter, that MyFatoorah will invoke once the payment is done.

Updated 8 days ago