STC Pay

Use this library to integrate Paylink payments into your app and grow your business with Paylink APIs to proceed with easy payment and generate customer invoices.

Step1: Getting token

From the server side, programmatically generate a token from the backend server using the Paylink Auth method. Client-side code will use this token.

Step2: Referring to javascript SDK.

On the client side, refer to the paylink.js SDK library file as follows:

Call Sript

<script src="https://paylink.sa/assets/js/paylink.js"></script>

Step3: Creating payment javascript object.

Create Paylink Payments javascript object from paylink.js SDK library. Use the parameters as follows:

Payment

let payment = new PaylinkPayments({mode: 'test', defaultLang: 'ar', backgroundColor: '#EEE'});

Parameter Name	Description	Values	Default Value
mode	Choose the environment of the Paylink system, either "production" for the production environment or "test" for the testing environment. The default value here is "production".	production test	production
defaultLang	Choose the language of the payment user interface, either " en" for English or "ar" for Arabic. The default value here is "en".	en ar	en
backgroundColor	This field will contain the background color of the Paylink payment popup window. The default color is #EEE.	hex color value	EEE

Step 4: Creating Order javascript object.

On the client side, create the order details for the buyer as follows:

Order

let order = new Order({
            callBackUrl: 'http://example.com/any_call_back_method.php', // callback page URL (for example http://localhost:6655 processPayment.php) in your site to be called after payment is processed. (mandatory)
            clientName: 'John Smith', // the name of the buyer. (mandatory)
            clientMobile: '0509200900', // the mobile of the buyer. (mandatory)
            amount: 50, // the total amount of the order (including VAT or discount). (mandatory). NOTE: This amount is used regardless of total amount of products listed below.
            orderNumber: 'ANY_UNIQUE_ORDER', // the order number in your system. (mandatory)
            clientEmail: '[email protected]', // the email of the buyer (optional)
            products: [ // list of products (optional)
                {title: 'Dress 1', price: 120, qty: 2},
                {title: 'Dress 2', price: 120, qty: 2},
                {title: 'Dress 3', price: 70, qty: 2}
            ],
        });

The provided code creates a new Order object and sets several properties using an object literal. The properties of the Order object are used to provide information about the order being processed. The table above lists the properties and their descriptions.

The callBackUrl, clientName, clientMobile, amount, and orderNumber properties are mandatory, meaning they must be specified when creating a new Order object. The clientEmail and products properties are optional.

The callBackUrl property represents the URL of the callback page that will be called after the payment is processed. This property is mandatory because the payment gateway needs to know where to redirect the user after completing the payment.

The clientName property is a string that represents the buyer's name. This property is mandatory because the payment gateway needs to know who is making the payment.

The clientMobile property is a string that represents the buyer's mobile phone number. This property is mandatory because the payment gateway may need to contact the buyer for verification.

The amount property is a numeric value representing the total amount of the order, including any applicable VAT or discounts. This property is mandatory because the buyer will be charged the total amount.

The orderNumber property is a string that represents the unique order number in the seller's system. This property is mandatory because it is used to identify the order within the seller's records.

The clientEmail property is a string that represents the buyer's email address. This property is optional because it is not always necessary to have the buyer's email address to process a payment.

The products property is an array of objects representing the individual products included in the order. Each object in the collection has a title property (a string representing the name of the product), a price property (a numeric value representing the price of the product), and a qty property (a numeric value representing the quantity of the product ordered). This property is optional because not all payment gateways require a list of products to process a payment.

Step 5: Send OTP to STCPay client phone

The method sendStcPayOtp uses a Promise from the "payment" object, passing it "token," "order," "mobileCountryCode," and "mobile" as arguments and returning a Promise that will resolve with the response.

JavaScript

 let stcpayOtpResponse = await payment.sendStcPayOtp(token, order, mobileCountryCode, mobile);

Developers are advised to use "async" and "await" when using this method to simplify the handling of the Promise and the response data, as "await" allows the Promise to resolve.

The response is to be stored in "stcpayOtpResponse" before proceeding to the next step of passing the same object to the "processStcPayPayment" method, along with an "otp" value, to initiate and complete a payment transaction via the STC Pay payment gateway.

Step 6: Process the STCPay payment.

The "processStcPayPayment" method is often used to process a payment transaction and confirm the receipt of a one-time password (OTP). The OTP is typically required as an additional security measure to verify the identity of the user making the payment, and the method will not proceed without a valid OTP.

👍

NOTE

Developer need to pass the same response object received from "sendStcPayOtp" with the OTP received by the buyer.

Proceed

await payment.processStcPayPayment(otp, stcpayOtpResponse);

The provided code uses the "await" keyword to call the "processStcPayPayment" method from the "payment" object, passing it "otp" and "stcpayOtpResponse" as arguments and storing the response in "stcpayPaymentResponse."

If the transaction is successful, the buyer will be redirected to the callback URL of the merchant. However, suppose an error occurs during the transaction. In that case, an error object will be returned instead, containing information about the cause of the error and any relevant details that may be useful in diagnosing and resolving the issue.

Step7: Handling Payment process response.

Finally, from the server side, programmatically process the payment response sent by Paylink after the payment process finishes. This step is crucial for security reasons; carefully follow Get Invoice to handle the payment result from Paylink.

❗️

Important

Merchant's application must call GetInvoice (here) endpoint immediately after the payment from the server side. First, check the integrity of the price by checking the payment status "orderStatus" and the amount paid "amount". Then proceed with the order processing of the client as paid or not. Otherwise, avoid using the endpoint GetInvoice and checking the amount and status will jeopardize the security of the payment.

Sample code

You can download a sample of the code written in PHP from here.