STC Pay

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:

1. The user clicks on the
2. OTP form is presented to the user.
3. The user enters the OTP they receive from STC pay and verifies it.
4. Payment details are sent securely to Moyasar servers and then processed.
5. 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:

1. Sign up for a Moyasar test account at Moyasar's dashboard
2. 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

JSON | POST 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"
  }
}

JSON | POST Response

{
  "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

POST Request

JSON | 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
}

On success, it returns the paid status payment object. If none of the requirements is met, the status will be failed.

JSON | GET/POST 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"
  }
}