STC Pay

Version: 3.0.0

Generate API Key for S2S channel. Navigate to Developers → API Keys → Add new API key → Select S2S in the Channel Dropdown.

STC Pay is a mobile wallet payment method. The customer is redirected to complete payment via the STC Pay app. The API returns a redirection URL that the customer follows to authorize the payment.

Endpoint

Method	URL
POST	`https://api.payorc.com/s2s/v1/payment`

Please use the test credentials for sandbox testing.

Headers

Header	Type	Required	Description
`merchant-key`	String	Yes	Your merchant API key
`merchant-secret`	String	Yes	Your merchant API secret
`Content-Type`	String	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description
`data.action`	String	Yes	Transaction action: `SALE`
`data.class`	String	Yes	Must be `ECOM`
`data.capture_method`	String	Yes	`AUTOMATIC`
`data.payment_token`	String	No	Leave empty for STC Pay
`data.type`	String	Yes	Must be `STCPAY`
`data.customer_details.m_customer_id`	String	No	Your internal customer ID
`data.customer_details.name`	String	Yes	Customer full name
`data.customer_details.email`	String	Yes	Customer email address
`data.customer_details.mobile`	String	Yes	Customer mobile number
`data.customer_details.code`	String	Yes	Country dial code (e.g., `966` for Saudi Arabia)
`data.order_details.m_order_id`	String	Yes	Your unique order ID
`data.order_details.amount`	String	Yes	Transaction amount
`data.order_details.currency`	String	Yes	Must be `SAR`
`data.order_details.return_url`	String	Yes	URL to redirect after payment
`data.items`	Array	Yes	Array of order items
`data.billing_details`	Object	Yes	Billing address details
`data.stcpay_details.id`	String	Yes	STC Pay registered phone number (e.g., `+966594393608`)
`data.shipping_details`	Object	No	Shipping address details
`data.urls`	Object	No	Redirect and webhook URLs — see S2S Payment URLs

Code Examples

curl --location --globoff 'https://api.payorc.com/s2s/v1/payment' \
--header 'merchant-key: YOUR_MERCHANT_KEY' \
--header 'merchant-secret: YOUR_MERCHANT_SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "action": "SALE",
    "class": "ECOM",
    "capture_method": "AUTOMATIC",
    "payment_token": "",
    "type": "STCPAY",
    "customer_details": {
      "m_customer_id": "1234",
      "name": "John Doe",
      "email": "[email protected]",
      "mobile": "594393608",
      "code": "966"
    },
    "order_details": {
      "m_order_id": "123456",
      "amount": "50",
      "currency": "SAR",
      "convenience_fee": "0",
      "description": "STC Pay payment",
      "return_url": "http://localhost/status"
    },
    "items": [
      {
        "title": "Product Name",
        "description": "Product description",
        "quantity": 1,
        "unit_price": "50.00",
        "discount_amount": "0.00",
        "is_refundable": true
      }
    ],
    "billing_details": {
      "address_line1": "Po Box 12322",
      "city": "Riyadh",
      "province": "Riyadh",
      "country": "SA",
      "pin": "54044"
    },
    "shipping_details": {
      "shipping_name": "John Doe",
      "shipping_email": "[email protected]",
      "shipping_code": "",
      "shipping_mobile": "",
      "address_line1": "Po Box 12322",
      "address_line2": "Jebel Ali Free Zone",
      "city": "Dubai",
      "province": "Dubai",
      "country": "AE",
      "pin": "54044",
      "location_pin": "",
      "shipping_currency": "AED",
      "shipping_amount": "0"
    },
    "parameters": [
      { "alpha": "" },
      { "beta": "" },
      { "gamma": "" },
      { "delta": "" },
      { "epsilon": "" }
    ],
    "custom_data": [
      { "alpha": "" },
      { "beta": "" },
      { "gamma": "" },
      { "delta": "" },
      { "epsilon": "" }
    ],
    "urls": {
      "success": "",
      "cancel": "",
      "failure": "",
      "webhook_url": "https://merchant.example.com/webhook"
    },

    "stcpay_details": {
      "id": "+966594393608"
    }
  }
}'

Success Response

{
  "data": {
    "order_status": "SUCCESS",
    "order_id": 1000010379,
    "amount": 50,
    "currency": "SAR",
    "psp_name": "telr",
    "redirection_url": "https://nodeserver.payorc.com/api/v1/stcpay/redirection/CC023F6305533251886C18E8AEA1B365E1A3725D8C4D60C8452984C1766616BF/1000010379/test",
    "stcpay_id": "+966594393608"
  },
  "message": "STCPay redirection url.",
  "status": "success",
  "code": "00"
}

Error Response

{
  "status": "fail",
  "code": "E0021",
  "message": "Service not available",
  "data": {
    "order_status": "FAILED",
    "order_id": 1000010379,
    "amount": 50,
    "currency": "SAR",
    "psp_name": "telr",
    "redirection_url": "",
    "stcpay_id": "+966594393608"
  }
}

Response Fields

Field	Type	Description
`data.order_status`	String	Order status: `SUCCESS` or `FAILED`
`data.order_id`	Number	PayOrc order ID
`data.amount`	Number	Transaction amount
`data.currency`	String	Currency code
`data.psp_name`	String	PSP name
`data.redirection_url`	String	URL to redirect customer for payment
`data.stcpay_id`	String	STC Pay registered phone number
`status`	String	API envelope: `success` or `fail`
`code`	String	`00` on success; `E0021` on failure
`message`	String	Response message

STC Pay

On this page