STC Pay


Introduction

Moyasar API provides the required facilities for adding STCPay payment method to your website or system. STCPay 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 STCPay into your system.

The process of making STCPay payment is composed of two steps, once the customer enters the mobile number and payment is initialized, he should authorize the transaction by entering an OTP code that will send to his mobile number.

On this page

Before Starting

Before you start integrating with Moyasar API, make sure you complete these steps:

  1. Sign up for a Moyasar test account at https://dashboard.moyasar.com/
  2. Get your API Key. To authenticate your API request.

For more, refer to Get started with Moyasar.


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 about 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.

User will provide the mobile number for proceeding charging:

Parameter Description
source[mobile] Provided by the customer starting with 05
Request JSON
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"
  }
}
Response JSON
{
  "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 OTP value enterd by user for proceed the payemnt by either send GET or POST request.

Parameter Description
otp_value Sent to customer by SMS.
GET Request JSON
GET
https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM
&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
}
Response JSON

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

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

Last Modified : Jul 2020