Custom Payments
STC Pay

9min
Introduction
Moyasar API provides the required facilities for adding STC pay payment methods to your website or system. STC pay is a digital wallet service that will allow users to utilize wallets to pay for Merchants.
Overview
This guide ensures an easy process for how to integrate STC pay into your system.
The process of making an STC pay payment is composed of the following steps:
The user clicks on the
OTP form is presented to the user.
The user enters the OTP they receive from STC pay and verifies it.
Payment details are sent securely to Moyasar servers and then processed.
The user is redirected back to the URL specified in callback_url when the payment
Before Starting
Before you start integrating with Moyasar API, make sure you complete these steps:
Sign up for a Moyasar test account at Moyasar's dashboard﻿
﻿Get your API key to authenticate your API request.
﻿
Specifications
Step 1: initiate payment
Set up the payment form with an input for mobile number in your website checkout page and send a POST request to Moyasar API to initiate the payment
Include the endpoint required attributes from your side as a merchant:
Parameter
Description
amount
Should be in the smallest currency unit. eg: 100 Halals to charges 1 Riyal.
currency optional
3-letter ISO code for currency. (default: SAR)
publishable_api_key
To authenticate the payment.
description optional
This may include a description of the merchandise or the service that your customer is billed for.
source[type]
The value should be stcpay.
source[cashier] optional
The cashier ID.
source[branch] optional
The branch ID.
The user will provide the mobile number for proceeding to charge:
Parameter
Description
source[mobile]
Provided by the customer starting with 05
POST Request JSON
Request
POST
https://api.moyasar.com/v1/payments
Content-Type: application/json

{
  "publishable_api_key": "`your api key here`",
  "amount": 5000,
  "currency": "SAR",
  "description": "Description",
  "source": {
    "type":"stcpay",
    "mobile": "0123456789",
    "cashier": "cashier_1_id"
  }
}
POST
https://api.moyasar.com/v1/payments
Content-Type: application/json

{
  "publishable_api_key": "`your api key here`",
  "amount": 5000,
  "currency": "SAR",
  "description": "Description",
  "source": {
    "type":"stcpay",
    "mobile": "0123456789",
    "cashier": "cashier_1_id"
  }
}
﻿
Resoponse
{
  "id": "760878ec-d1d3-5f72-9056-191683f55872",
  "status": "initiated",
  "amount": 5000,
  "fee": 0,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": null,
  "captured": 0,
  "captured_at": null,
  "voided_at": null,
  "description": "Description",
  "amount_format": "50.00 SAR",
  "fee_format": "0.00 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": null,
  "ip": null,
  "callback_url": null,
  "created_at": "2020-07-03T17:04:17.000Z",
  "updated_at": "2020-07-03T17:04:17.000Z",
  "source": {
    "type": "stcpay",
    "mobile": "0123456789",
    "reference_number": "1017224325884",
    "branch": null,
    "cashier": null,
    "transaction_url": "https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM",
    "message": null
  }
}
{
  "id": "760878ec-d1d3-5f72-9056-191683f55872",
  "status": "initiated",
  "amount": 5000,
  "fee": 0,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": null,
  "captured": 0,
  "captured_at": null,
  "voided_at": null,
  "description": "Description",
  "amount_format": "50.00 SAR",
  "fee_format": "0.00 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": null,
  "ip": null,
  "callback_url": null,
  "created_at": "2020-07-03T17:04:17.000Z",
  "updated_at": "2020-07-03T17:04:17.000Z",
  "source": {
    "type": "stcpay",
    "mobile": "0123456789",
    "reference_number": "1017224325884",
    "branch": null,
    "cashier": null,
    "transaction_url": "https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM",
    "message": null
  }
}
﻿
Step 2: confirm payment
Once the payment is initiated successfully, handle the JSON response and then use transaction_url to pass the OTP value entered by the user to proceed with the payment by sending a GET/POST request.
Parameter
Description
otp_value
Sent to the customer by SMS.
GET Request JSON
GET Request
GET
https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM
&otp_value=12345
GET
https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM
&otp_value=12345
﻿
POST Request
POST
https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM
Content-Type: application/json

{
  "otp_value": 12345
}
POST
https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM
Content-Type: application/json

{
  "otp_value": 12345
}
﻿
On success, it returns the paid status payment object. If none of the requirements is met, the status will be failed.
Response
{
  "id": "760878ec-d1d3-5f72-9056-191683f55872",
  "status": "paid",
  "amount": 5000,
  "fee": 0,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": null,
  "captured": 0,
  "captured_at": null,
  "voided_at": null,
  "description": "Description",
  "amount_format": "50.00 SAR",
  "fee_format": "0.00 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": null,
  "ip": null,
  "callback_url": null,
  "created_at": "2020-07-03T17:04:17.000Z",
  "updated_at": "2020-07-03T17:05:16.547",
  "source": {
    "type": "stcpay",
    "mobile": "0123456789",
    "reference_number": "1017224325884",
    "branch": "1",
    "cashier": "cashier_1_id",
    "transaction_url": "https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM",
    "message": "Paid"
  }
}
{
  "id": "760878ec-d1d3-5f72-9056-191683f55872",
  "status": "paid",
  "amount": 5000,
  "fee": 0,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": null,
  "captured": 0,
  "captured_at": null,
  "voided_at": null,
  "description": "Description",
  "amount_format": "50.00 SAR",
  "fee_format": "0.00 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": null,
  "ip": null,
  "callback_url": null,
  "created_at": "2020-07-03T17:04:17.000Z",
  "updated_at": "2020-07-03T17:05:16.547",
  "source": {
    "type": "stcpay",
    "mobile": "0123456789",
    "reference_number": "1017224325884",
    "branch": "1",
    "cashier": "cashier_1_id",
    "transaction_url": "https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM",
    "message": "Paid"
  }
}
﻿
﻿
Parameter	Description
amount	Should be in the smallest currency unit. eg: 100 Halals to charges 1 Riyal.
currency optional	3-letter ISO code for currency. (default: SAR)
publishable_api_key	To authenticate the payment.
description optional	This may include a description of the merchandise or the service that your customer is billed for.
source[type]	The value should be stcpay.
source[cashier] optional	The cashier ID.
source[branch] optional	The branch ID.
Parameter	Description
source[mobile]	Provided by the customer starting with 05
Parameter	Description
otp_value	Sent to the customer by SMS.
Updated 07 Sep 2024
Did this page help you?
Credit Cards
Apple Pay on Websites