stc pay for Payment Setup API

Last updated: May 13, 2026

To accept stc pay payments, you must:

Create a payment setup.
Update the payment setup and initialize stc pay as a payment method.
Submit the one-time password (OTP).
Verify payment authorization.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "SAR",
4  "amount": 1000,
5  "reference": "ORDER_01234",
6  "description": "stc pay payment",
7  "payment_type": "Regular",
8  "customer": {
9    "email": "hannah.bret@example.com",
10    "phone": {
11      "country_code": "966",
12      "number": "555123456"
13    }
14  },
15  "settings": {
16    "success_url": "https://example.com/payments/success",
17    "failure_url": "https://example.com/payments/failure"
18  }
19}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency
customer.phone.country_code – The customer's phone country code
customer.phone.number – The customer's phone number registered with stc pay


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "SAR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "stc pay payment",
9  "payment_methods": {
10    "stcpay": {
11      "initialization": "disabled",
12      "status": "pending",
13      "flags": [
14        "initialization_not_enabled"
15      ]
16    }
17  },
18  "available_payment_methods": [
19    "stcpay"
20  ],
21  "settings": {
22    "success_url": "https://example.com/payments/success",
23    "failure_url": "https://example.com/payments/failure"
24  }
25}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

For stc pay, payment_methods contains the following fields:

initialization – The initialization status of the payment method, which can be either enabled or disabled.
status – The status of the payment method.
flags – An array of error codes or indicators that highlight missing or invalid information.

When the customer selects stc pay as the payment method on the checkout page, you must update the payment setup to:

Initialize the payment method.
Provide stc pay-specific configuration values.

Call the Update a payment setup endpoint, setting payment_methods.stcpay.initialization to enabled.

Additionally, provide the following fields:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	The three-letter ISO 4217 currency code. Required
`customer.phone.country_code` string	The customer's phone country code. Required
`customer.phone.number` string	The customer's phone number registered with stc pay. Required
`customer.email` string	The customer's email address.
`reference` string	The payment reference. Max length: 80 characters


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "SAR",
4  "amount": 1000,
5  "reference": "ORDER_01234",
6  "description": "stc pay payment",
7  "payment_type": "Regular",
8  "customer": {
9    "email": "hannah.bret@example.com",
10    "phone": {
11      "country_code": "966",
12      "number": "555123456"
13    }
14  },
15  "settings": {
16    "success_url": "https://example.com/payments/success",
17    "failure_url": "https://example.com/payments/failure"
18  },
19  "payment_methods": {
20    "stcpay": {
21      "initialization": "enabled"
22    }
23  }
24}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "SAR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "stc pay payment",
9  "payment_methods": {
10    "stcpay": {
11      "initialization": "enabled",
12      "action": {
13        "type": "otp"
14      },
15      "status": "action_required",
16      "flags": []
17    }
18  },
19  "available_payment_methods": [
20    "stcpay"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

The response returns an action_required status with an action.type of otp. stc pay sends a one-time password (OTP) to the customer's registered phone number. Submit the OTP in a follow-up update call to advance the payment to ready.

After receiving the action_required response, prompt the customer to enter the OTP sent to their registered phone number.

Submit the OTP by calling the Update a payment setup endpoint again and setting payment_methods.stcpay.otp to the value the customer provides.

Field Description

Field	Description
`payment_methods.stcpay.otp` string	The one-time password (OTP) provided by the customer. Max length: 50 Required

payment_methods.stcpay.otp

string

The one-time password (OTP) provided by the customer.
Max length: 50
Required


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "SAR",
4  "amount": 1000,
5  "reference": "ORDER_01234",
6  "description": "stc pay payment",
7  "payment_type": "Regular",
8  "customer": {
9    "email": "hannah.bret@example.com",
10    "phone": {
11      "country_code": "966",
12      "number": "555123456"
13    }
14  },
15  "settings": {
16    "success_url": "https://example.com/payments/success",
17    "failure_url": "https://example.com/payments/failure"
18  },
19  "payment_methods": {
20    "stcpay": {
21      "initialization": "enabled",
22      "otp": "123456"
23    }
24  }
25}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "SAR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "stc pay payment",
9  "payment_methods": {
10    "stcpay": {
11      "initialization": "enabled",
12      "status": "ready",
13      "flags": []
14    }
15  },
16  "available_payment_methods": [
17    "stcpay"
18  ],
19  "settings": {
20    "success_url": "https://example.com/payments/success",
21    "failure_url": "https://example.com/payments/failure"
22  }
23}

After the customer submits the OTP, the payment method status changes to ready.

Call the Get a payment setup endpoint, setting the id of the payment setup as the id path parameter, to check the status before confirming.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

get

https://{prefix}.api.checkout.com/payments/setups/{id}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "SAR",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "stc pay payment",
9  "payment_methods": {
10    "stcpay": {
11      "initialization": "enabled",
12      "status": "ready",
13      "flags": []
14    }
15  },
16  "available_payment_methods": [
17    "stcpay"
18  ],
19  "settings": {
20    "success_url": "https://example.com/payments/success",
21    "failure_url": "https://example.com/payments/failure"
22  }
23}

When the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
stcpay as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/stcpay

stc pay for Payment Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Submit the one-time password (OTP)

Request example

Response example

Verify payment authorization

Information

Response example

Confirm the payment