Sending an OTP API

The API endpoint for sending an OTP for STCPay payment.

API Endpoint

The API endpoint for sending an OTP for STCPay payment.

Production vs. Testing Server

The API has two server endpoints: one for production and one for testing. Use the production server for actual transactions and the testing server for development and testing purposes.

📘

Production server:

https://order.paylink.sa/rest/pay/stcpay/sendOtp

📘

Testing server:

https://orderpilot.paylink.sa/rest/pay/stcpay/sendOtp

API Authentication

This API does not require any authentication.

API Usage

To use this API, send an HTTP POST request to the API endpoint with the following JSON-encoded body parameters:

Parameter Name	Data Type	Required	Description
stcpayMobile	string	Yes	The STCPay mobile number to send the OTP to.
orderNumber	string	Yes	The unique order number for the transaction. It is the transactionNo generated from the addInvoice endpoint.
stcpayMobileCountryCode	string	Yes	The country code for the STCPay mobile number.
total	number	Yes	The total amount for the transaction.

👍

Parameter orderNumber value

orderNumber can be received from the transactionNo field of the response of addInvoice API.

Example Request

Here is an example curl command for sending an OTP request:

cURL

curl --location 'https://orderpilot.paylink.sa/rest/pay/stcpay/sendOtp' \
--header 'Content-Type: application/json' \
-X POST
--data '{
    "stcpayMobile": "551234567",
    "stcpayMobileCountryCode": "966",
    "orderNumber": "1679123751896",
    "total": 10
}'

Success Response

If the OTP request is successful, the API will return a JSON-encoded response with the following parameters:

Parameter Name	Data Type	Description
stcMobile	string	The STC mobile number is associated with the transaction.
paymentSessionId	string	The unique ID for the payment session. It will be passed to the processPayment endpoint.
signature	string	The signature for the transaction. It will be passed to the processPayment endpoint.
stcpayMobile	string	The STCPay mobile number the OTP was sent to. It will be passed to the processPayment endpoint.
signedBase64Data	string	The signed base64-encoded data for the transaction. It will be passed to the processPayment endpoint.

Here is an example success response:

JSON

{
    "stcMobile": "551234567",
    "paymentSessionId": "641c1fec04e8e7793ca21f35",
    "signature": "NTkzMjU2MzFhYmIwNGY4YzZmZDRkMjUzNDUyZjU0YzUwOTlmMjRiNDYwNWVlZjNmNzMwYjhkNmQwMjZlNjc1Mw==",
    "stcpayMobile": "551234567",
    "signedBase64Data": "NTk5OTI1NDc3NjQxYzFmZWMwNGU4ZTc3OTNjYTIxZjM1"
}

Failure Response

If the OTP request fails, the API will return a JSON-encoded response with the following parameters:

Parameter Name	Data Type	Description
timestamp	number	The timestamp for the error.
status	number	The HTTP status code for the error.
error	string	The error message.
path	string	The API path for the request that caused the error.

Here is an example failure response:

JSON

{
    "timestamp": 1679566267336,
    "status": 500,
		"error": "Internal Server Error",
		"path": "/rest/pay/stcpay/sendOtp"
}

Error Codes

The API may return the following HTTP status codes:

Status Code	Description
200	OK. The request was successful.
400	Bad Request. The request parameters were invalid.
401	Unauthorized. The request did not include valid authentication credentials.
404	Not Found. The requested resource was not found.
500	Internal Server Error. An unexpected error occurred on the server.