STC Pay API

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

STC Pay is a digital wallet payment method provided by Saudi Telecom Company (STC) for processing transactions in Saudi Arabia. The integration supports phone number-based authentication using One Time Passwords (OTP) for secure transaction verification.

STC Pay Integration Options

Choose the integration method that best fits your business requirements and technical capabilities:

Hosted Checkout

Server-side redirection to Amazon Payment Services hosted payment page for complete payment processing.

Custom Integration

Direct API integration allowing merchants to build custom payment flows while maintaining control over the user experience.

Mobile Integration

SDK-based integration for iOS and Android applications with native mobile payment capabilities.

API Endpoints

https://sbcheckout.payfort.com/FortAPI/paymentPage

Hosted Checkout

STC Pay follows the same hosted checkout implementation as other payment methods. When STC Pay is active on your merchant account and the transaction currency is SAR (Saudi Arabian Riyal), STC Pay will automatically appear as a payment option on the hosted checkout page.

STC Pay Specific Requirements

For STC Pay transactions, you must include these specific parameters:

Parameter	Requirement
currency	Must be `SAR` (Saudi Arabian Riyal)
command	Must be `PURCHASE` (AUTHORIZATION not supported)
digital_wallet	Set to `STCPAY` for STC Pay specific transactions

If you don't specify the digital_wallet parameter, STC Pay will automatically appear on the hosted checkout page when:

STC Pay is active on your merchant account
Transaction currency is SAR
Customer is in Saudi Arabia

To restrict the payment page to show only STC Pay, include digital_wallet: STCPAY in your request parameters.

Sample Request
<!-- HTTPS POST form submitted directly to APS from frontend -->

<form method="post" action="https://sbcheckout.payfort.com/FortAPI/paymentPage" id="stc_pay_form">
    
    <!-- Required STC Pay Parameters -->
    <input type="hidden" name="command" value="PURCHASE">
    <input type="hidden" name="access_code" value="zx0IPmPy5jp1vAz8Kpg7">
    <input type="hidden" name="digital_wallet" value="STCPAY">
    <input type="hidden" name="merchant_identifier" value="CycHZxVj">
    <input type="hidden" name="merchant_reference" value="STC-ORD-2024-1725887587">
    
    <!-- Amount: SAR 685.57 (68557 halalas) -->
    <input type="hidden" name="amount" value="68557">
    <input type="hidden" name="currency" value="SAR">
    <input type="hidden" name="language" value="en">
    
    <!-- Customer Information -->
    <input type="hidden" name="customer_email" value="customer@example.com">
    <input type="hidden" name="customer_ip" value="127.0.0.1">
    <input type="hidden" name="phone_number" value="0551111111">
    
    <!-- Order Details -->
    <input type="hidden" name="order_description" value="STC Pay Payment">
    
    <!-- Post-payment redirect URL -->
    <input type="hidden" name="return_url" value="https://www.merchant.com/stc-pay/callback">
    
    <input type="hidden" name="signature" value="7cad05f0212ed933c9a5d5dffa31661acf2c827a">
    
    <!-- Submit button -->
    <button type="submit">Pay with STC Pay</button>
    
</form>

Sample Response
command=PURCHASE
access_code=zx0IPmPy5jp1vAz8Kpg7
digital_wallet=STCPAY
merchant_identifier=CycHZxVj
merchant_reference=STC-ORD-2024-1725887587
amount=68557
currency=SAR
language=en
response_code=14000
response_message=Success
status=20
fort_id=149295435400084008
payment_option=STCPAY
eci=ECOMMERCE
customer_email=customer@example.com
customer_name=John Smith
phone_number=0551111111
signature=b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2

Custom Integration

Direct API integration for building custom STC Pay payment flows with full control over user experience and transaction handling.

API Endpoints

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

1. Generate OTP

Request Format

Method: POST
Content-Type: application/json
Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
service_command `String` `Max: 20` `Required` Service command for OTP generation. Value: `GENERATE_OTP` Example. GENERATE_OTP
access_code `String` `Max: 20` `Required` Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings → Security Settings. Example. zx0IPmPy5jp1vAz8Kpg7
amount `Integer` `Max: 10` `Required` Transaction amount in smallest currency unit (no decimal points). For AED: multiply by 100 (1.00 AED = 100), for USD: multiply by 100 (1.00 USD = 100), for KWD: multiply by 1000 (1.000 KWD = 1000). Example. 10000
digital_wallet `String` `Max: 100` `Required` Specifies the digital wallet type for the transaction. Values: `STCPAY` Example. STCPAY
signature `String` `Max: 200` `Required` SHA-256 HMAC signature calculated using your secret key and request parameters for authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
merchant_identifier `String` `Max: 20` `Required` Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference `String` `Max: 40` `Required` Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
currency `String` `Max: 3` `Required` Three-letter ISO 4217 currency code. STC Pay only supports Saudi Arabian Riyal. Value: `SAR` Example. SAR
language `String` `Max: 2` `Required` Response language. Supported values: en (English) or ar (Arabic). Example. en
phone_number `String` `Max: 19` `Required` Customer phone number in Saudi Arabia format for STC Pay OTP delivery. Example. 0548220713

For SAR currency, multiply your transaction amount by 100 before sending the amount parameter. Example: For 100.00 SAR, send 10000 in your request.

The merchant_reference must be unique per transaction.

Check signature calculation section to learn how to calculate the signature.

Response Parameters

Parameter
service_command `String` `Max: 20` Service command from the request. Value: `GENERATE_OTP` Example. GENERATE_OTP
response_code `Integer` `Max: 5` Numeric response code indicating OTP generation result. Example. 88000
response_message `String` `Max: 150` Human-readable response description in requested language. Example. Success
access_code `String` `Max: 20` Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
amount `Integer` `Max: 10` Transaction amount from the request. Example. 10000
signature `String` `Max: 200` Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
merchant_identifier `String` `Max: 20` Merchant identifier used in the request. Example. CycHZxVj
digital_wallet `String` `Max: 20` Digital wallet identifier from the request. Value: `STCPAY` Example. STCPAY
merchant_reference `String` `Max: 40` Unique order reference from the request. Example. XYZ9239-yu898
currency `String` `Max: 3` Currency code from the request. Value: `SAR` Example. SAR
language `String` `Max: 2` Language used for the response. Example. en
phone_number `String` `Max: 19` Customer phone number from the request. Example. 0548220713

Generate OTP Sample Request
{
  "amount": 68557,
  "service_command": "GENERATE_OTP",
  "digital_wallet": "STCPAY",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "merchantTest-10090",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "currency": "SAR",
  "language": "en",
  "phone_number": "0551111111"
}

Sample Response
{
  "service_command": "GENERATE_OTP",
    "response_code": "88000",
  "response_message": "Success",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "amount": "68557",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "merchant_identifier": "CycHZxVj",
  "digital_wallet": "STCPAY",
  "merchant_reference": "merchantTest-10090",
  "currency": "SAR",
  "language": "en",
  "phone_number": "0551111111"
}

2. Purchase

Request Format

Method: POST
Content-Type: application/json
Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
command `String` `Max: 20` `Required` Transaction type to be executed. For STC Pay, only PURCHASE is supported. Value: `PURCHASE` Example. PURCHASE
access_code `String` `Max: 20` `Required` Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings → Security Settings. Example. zx0IPmPy5jp1vAz8Kpg7
digital_wallet `String` `Max: 100` `Required` Specifies the digital wallet type for the transaction. Values: `STCPAY` Example. STCPAY
merchant_identifier `String` `Max: 20` `Required` Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference `String` `Max: 40` `Required` Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens (-), underscores (_), and periods (.) allowed. Example. XYZ9239-yu898
amount `Integer` `Max: 10` `Required` Transaction amount in smallest currency unit (no decimal points). For AED: multiply by 100 (1.00 AED = 100), for USD: multiply by 100 (1.00 USD = 100), for KWD: multiply by 1000 (1.000 KWD = 1000). Example. 10000
currency `String` `Max: 3` `Required` Three-letter ISO 4217 currency code. Example. SAR
otp `String` `Max: 10` `Required` OTP sent to customer's phone number. The length of the OTP can be 4, 5 or 6 characters. During integration, update the OTP field to be dynamic. Example. 1234
language `String` `Max: 2` `Required` Response language. Supported values: en (English) or ar (Arabic). Example. en
customer_email `String` `Max: 254` `Required` Valid customer email address for payment notifications and receipt delivery. Example. customer1@domain.com
customer_ip `String` `Max: 45` `Required` Customer's IP address for fraud prevention. Supports both IPv4 and IPv6 formats. Example. 192.178.1.10
signature `String` `Max: 200` `Required` SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
order_description `String` `Max: 150` `Optional` Human-readable description of the order or service being paid for. Example. iPhone 6-S
settlement_reference `String` `Max: 22` `Optional` Unique reference passed to the third party for settlement file identification. Example. XYZ9239-yu898
customer_name `String` `Max: 40` `Optional` Full name of the customer making the payment. Example. John Smith
merchant_extra `String` `Max: 999` `Optional` Custom data that will be returned in the response and webhook notifications. Example. JohnSmith
merchant_extra1 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra2 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra3 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith
merchant_extra4 `String` `Max: 250` `Optional` Additional custom field for merchant-specific data. Example. JohnSmith

For SAR currency, multiply your transaction amount by 100 before sending the amount parameter. Example: For 100.00 SAR, send 10000 in your request.

The OTP must be the same one generated in the previous step. OTP length varies between 4-6 characters.

The merchant_reference must be unique per transaction.

Check signature calculation section to learn how to calculate the signature.

Response Parameters

Parameter
response_code `Integer` `Max: 5` Numeric response code indicating transaction result. Example. 14000
response_message `String` `Max: 150` Human-readable response description in requested language. Example. Success
access_code `String` `Max: 20` Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
command `String` `Max: 20` Transaction type executed. Value: `PURCHASE` Example. PURCHASE
digital_wallet `String` `Max: 20` Digital wallet identifier used for the transaction. Value: `STCPAY` Example. STCPAY
merchant_identifier `String` `Max: 20` Merchant identifier used in the request. Example. CycHZxVj
merchant_reference `String` `Max: 40` Unique order reference from the request. Example. XYZ9239-yu898
amount `Integer` `Max: 10` Transaction amount processed. Example. 10000
currency `String` `Max: 3` Currency code used for the transaction. Value: `SAR` Example. SAR
language `String` `Max: 2` Language used for the response. Example. en
customer_email `String` `Max: 254` Customer email address used. Example. customer1@domain.com
customer_ip `String` `Max: 45` Customer's IP address from the request. Example. 192.178.1.10
signature `String` `Max: 200` Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
eci `String` `Max: 16` E-commerce indicator for STC Pay transactions. Value: `ECOMMERCE` Example. ECOMMERCE
payment_option `String` `Max: 10` Payment method used by customer. Value: `STCPAY` Example. STCPAY
fort_id `Integer` `Max: 20` Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
status `Integer` `Max: 2` Two-digit status code indicating transaction state. Example. 20
order_description `String` `Max: 150` Description of the order from the request. Example. iPhone 6-S
settlement_reference `String` `Max: 22` Settlement reference from the request. Example. XYZ9239-yu898
customer_name `String` `Max: 40` Customer's name from the request. Example. John Smith
merchant_extra `String` `Max: 999` Custom merchant data from the request. Example. JohnSmith
merchant_extra1 `String` `Max: 250` Additional custom field from the request. Example. JohnSmith
merchant_extra2 `String` `Max: 250` Additional custom field from the request. Example. JohnSmith
merchant_extra3 `String` `Max: 250` Additional custom field from the request. Example. JohnSmith
merchant_extra4 `String` `Max: 250` Additional custom field from the request. Example. JohnSmith

Purchase Sample Request
{
  "amount": 68557,
  "digital_wallet": "STCPAY",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "merchant_identifier": "CycHZxVj",
  "access_code": "FIX7skJDGmjJF0WDh2oB",
  "customer_ip": "127.0.0.1",
  "language": "en",
  "otp": "12345",
  "command": "PURCHASE",
  "merchant_reference": "merchantTest-10117",
  "customer_email": "merchant07@merchantdomain.com",
  "currency": "SAR"
}

Sample Response
{
    "response_code": "14000",
  "response_message": "Success",
  "access_code": "FIX7skJDGmjJF0WDh2oB",
  "command": "PURCHASE",
  "digital_wallet": "STCPAY",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "merchantTest-10117",
  "amount": "68557",
  "currency": "SAR",
  "language": "en",
  "customer_email": "merchant07@merchantdomain.com",
  "customer_ip": "127.0.0.1",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "eci": "ECOMMERCE",
  "payment_option": "STCPAY",
  "fort_id": "149295435400084008",
  "status": "20"
}

Mobile Integration

SDK-based integration for iOS and Android applications providing native STC Pay payment capabilities with mobile-optimized user experience.

API Endpoints

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

1. Generate SDK Token

Request Format

Method: POST
Content-Type: application/json
Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
service_command `String` `Max: 20` `Required` Service command for SDK token generation. Value: `SDK_TOKEN` Example. SDK_TOKEN
device_id `String` `Max: 100` `Required` The unique device identifier from the mobile device. Example. ffffffff-a9fa-0b44-7b27-29e70033c587
signature `String` `Max: 100` `Required` SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
merchant_identifier `String` `Max: 20` `Required` Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
access_code `String` `Max: 20` `Required` Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
language `String` `Max: 2` `Required` SDK language. Supported values: en (English) or ar (Arabic). Example. en

Check signature calculation section to learn how to calculate the signature.

SDK Token Sample Request
{
  "service_command": "SDK_TOKEN",
  "device_id": "34354BB0-81C2-493E-9E71-198312EC2149",
  "signature": "366b91c3a411968fd8e30e93dae8b4f82195eb635a82c98d50d02fe7947a7178",
  "merchant_identifier": "e4c8e0dc",
  "access_code": "EVHtwFMINwAMJCZUp54k",
  "language": "en"
}

2. Generate OTP (Mobile)

Request Format

Method: POST
Content-Type: application/json
Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
amount `Integer` `Max: 10` `Required` Transaction amount to generate the OTP. This amount must also be used for the purchase transaction. Amount in halalas for SAR. Example. 10000
service_command `String` `Max: 20` `Required` Service command for OTP generation. Value: `GENERATE_OTP` Example. GENERATE_OTP
digital_wallet `String` `Max: 20` `Required` Digital wallet identifier for STC Pay transactions. Value: `STCPAY` Example. STCPAY
sdk_token `String` `Max: 100` `Required` The SDK token generated from the previous step to enable the Amazon Payment Services Mobile SDK. Example. dwp78q3
merchant_reference `String` `Max: 40` `Required` Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
merchant_identifier `String` `Max: 20` `Required` Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
access_code `String` `Max: 20` `Required` Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz8Kpg7
language `String` `Max: 2` `Required` Response language. Supported values: en (English) or ar (Arabic). Example. en
currency `String` `Max: 3` `Required` Three-letter ISO 4217 currency code. STC Pay only supports Saudi Arabian Riyal. Value: `SAR` Example. SAR
phone_number `String` `Max: 19` `Required` Customer phone number in Saudi Arabia format for STC Pay OTP delivery. Example. 0548220713

Generate OTP SDK Sample Request
{
  "amount": 100,
  "service_command": "GENERATE_OTP",
  "digital_wallet": "STCPAY",
  "sdk_token": "a8c4a35cfb094bee952b94f4f22bace9",
  "merchant_reference": "a8c4a35cfb094bee952b94f4f22bace9",
  "merchant_identifier": "e4c8e0dc",
  "access_code": "EVHtwFMINwAMJCZUp54k",
  "language": "en",
  "currency": "SAR",
  "phone_number": "0548220713"
}

3. Purchase (Mobile)

Request Format

Method: POST
Content-Type: application/json
Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
amount `Integer` `Max: 10` `Required` Transaction amount. This needs to be the same as the amount supplied when generating the OTP. Amount in halalas for SAR. Example. 10000
digital_wallet `String` `Max: 20` `Required` Digital wallet identifier for STC Pay transactions. Value: `STCPAY` Example. STCPAY
sdk_token `String` `Max: 100` `Required` The SDK token generated from the first step to enable the Amazon Payment Services Mobile SDK. Example. dwp78q3
merchant_reference `String` `Max: 40` `Required` Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
customer_email `String` `Max: 254` `Required` Valid customer email address for payment notifications and receipt delivery. Example. customer1@domain.com
phone_number `String` `Max: 19` `Required` Customer phone number in Saudi Arabia format for STC Pay verification. Example. 00962797219966
otp `String` `Max: 10` `Required` OTP sent to customer's phone number. The length of the OTP can be 4, 5 or 6 characters. Example. 123456
currency `String` `Max: 3` `Required` Three-letter ISO 4217 currency code. STC Pay only supports Saudi Arabian Riyal. Value: `SAR` Example. SAR
command `String` `Max: 20` `Required` Transaction type to be executed. For STC Pay, only PURCHASE is supported. Value: `PURCHASE` Example. PURCHASE
language `String` `Max: 2` `Required` Response language. Supported values: en (English) or ar (Arabic). Example. en
settlement_reference `String` `Max: 22` `Optional` Unique reference passed to the third party for settlement file identification. Example. XYZ9239-yu898

Purchase SDK Sample Request
{
  "amount": 100,
  "digital_wallet": "STCPAY",
  "sdk_token": "a8c4a35cfb094bee952b94f4f22bace9",
  "merchant_reference": "a8c4a35cfb094bee952b94f4f22bace9",
  "customer_email": "sdasd@mail.com",
  "phone_number": "0548220713",
  "language": "en",
  "otp": "******",
  "currency": "SAR",
  "command": "PURCHASE"
}

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

Hosted Checkout URL: https://sbcheckout.payfort.com/FortAPI/paymentPage
API URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
Test Phone Numbers: Use test phone numbers provided by Amazon Payment Services for sandbox testing

Go-Live Process

When ready to move to production, follow our Go-Live checklist

STC Pay Integration Options​

Hosted Checkout

Custom Integration

Mobile Integration

API Endpoints​

Hosted Checkout​

STC Pay Specific Requirements​

Custom Integration​

API Endpoints​

1. Generate OTP​

Request Format​

Request Parameters​

Response Parameters​

2. Purchase​

Request Format​

Request Parameters​

Response Parameters​

Mobile Integration​

API Endpoints​

1. Generate SDK Token​

Request Format​

Request Parameters​

2. Generate OTP (Mobile)​

Request Format​

Request Parameters​

3. Purchase (Mobile)​

Request Format​

Request Parameters​

Response Codes​

Testing The Integration​

Sandbox Testing​

Go-Live Process​

STC Pay Integration Options

API Endpoints

Hosted Checkout

STC Pay Specific Requirements

Custom Integration

API Endpoints

1. Generate OTP

Request Format

Request Parameters

Response Parameters

2. Purchase

Request Format

Request Parameters

Response Parameters

Mobile Integration

API Endpoints

1. Generate SDK Token

Request Format

Request Parameters

2. Generate OTP (Mobile)

Request Format

Request Parameters

3. Purchase (Mobile)

Request Format

Request Parameters

Response Codes

Testing The Integration

Sandbox Testing

Go-Live Process