---
title: "Custom UI"
description: "Build a custom STC Pay checkout with the Moyasar API, covering payment initiation, OTP verification, and the redirect callback flow."
---

# Custom UI

> Build a custom STC Pay checkout with the Moyasar API, covering payment initiation, OTP verification, and the redirect callback flow.

# 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](https://dashboard.moyasar.com)
2. [Get your API key](https://help.moyasar.com/en/article/moyasar-dashboard-api-keys-1srfrtb/) 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 title="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 title="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. |

        ```json title="JSON | GET Request"
        GET
        https://api.moyasar.com/v1/stc_pays/6187b1f9-ihn2-457b-a8bc-e2j5c808ff94/proceed?otp_token=SOQIbUEGsRTLaIoNDUGM
        &otp_value=12345
        ```

        ```json title="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 title="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"
  }
}
```