stc pay for Payments Setup API

Last updated: March 4, 2026

To accept stc pay payments, you must:

Create a payment setup.
Update the payment setup and initialize stc pay as a payment method.
Update the payment setup with the One-Time Password (OTP).
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/payment-contexts


1{
2  "processing_channel_id": "pc_3veqrsnny5zudozaeymwjvtali",
3  "currency": "SAR",
4  "amount": 152,
5  "customer": {
6    "email": {
7      "address": "jane@email.com"
8    },
9    "phone": {
10      "country_code": "111",
11      "number": "222222222"
12    }
13  },
14  "settings": {
15    "success_url": "https://success.co.uk",
16    "failure_url": "https://failure.co.uk"
17  }
18}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – Set payment currency to SAR


1{
2  "id": "pay_js5diujz2kwunhokfgu7y2uxhm",
3  "processing_channel_id": "pc_3veqrsnny5zudozaeymwjvtali",
4  "currency": "SAR",
5  "amount": 152,
6  "payment_methods": {
7    "stcpay": {
8      "status": "action_required",
9      "initialization": "disabled",
10      "flags": ["initialization_disabled"]
11    }
12  },
13  "customer": {
14    "email": {
15      "address": "jane@email.com"
16    },
17    "phone": {
18      "country_code": "111",
19      "number": "222222222"
20    }
21  },
22  "settings": {
23    "success_url": "https://success.co.uk",
24    "failure_url": "https://failure.co.uk"
25  }
26}

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:

flags – An array of error codes or indicators that highlight missing or invalid information which you can prompt the customer to provide.
status – The status of the payment method.
initialization - The initialization status of the payment method, which can be either enabled or disabled. If initialization is disabled, you need to initialize the payment method before offering it to the customer.

When the customer selects stc pay, you must update the payment setup to initialize the payment method.

Call the Update a payment setup endpoint, setting payment_methods.stcpay.initialization to enabled. This triggers a one-time password (OTP) to be sent to the customer.

Additionally, provide the following required fields:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum value: 1
`customer.email.address` string	The customer's email address.
`description` string	A description of the payment.
`reference` string	A reference you can use to identify the payment. For example, an order number.


1{
2  "processing_channel_id": "pc_3veqrsnny5zudozaeymwjvtali",
3  "currency": "SAR",
4  "amount": 152,
5  "payment_methods": {
6    "stcpay": {
7      "initialization": "enabled"
8    }
9  },
10  "customer": {
11    "email": {
12      "address": "jane@email.com"
13    },
14    "phone": {
15      "country_code": "111",
16      "number": "222222222"
17    }
18  },
19  "settings": {
20    "success_url": "https://success.co.uk",
21    "failure_url": "https://failure.co.uk"
22  }
23}


1{
2  "id": "pay_js5diujz2kwunhokfgu7y2uxhm",
3  "processing_channel_id": "pc_3veqrsnny5zudozaeymwjvtali",
4  "currency": "SAR",
5  "amount": 152,
6  "payment_methods": {
7    "stcpay": {
8      "status": "action_required",
9      "initialization": "enabled",
10      "flags": [],
11      "action": {
12        "type": "otp"
13      }
14    }
15  },
16  "customer": {
17    "email": {
18      "address": "jane@email.com"
19    },
20    "phone": {
21      "country_code": "111",
22      "number": "222222222"
23    }
24  },
25  "settings": {
26    "success_url": "https://success.co.uk",
27    "failure_url": "https://failure.co.uk"
28  }
29}

The response indicates an action_required status with the action.type field set to otp. The customer receives an OTP via text message. Collect this and send a new payment setup update.

Call the Update a payment setup endpoint, setting payment_methods.stcpay.top to the OTP value you collected.


1{
2  "processing_channel_id": "pc_3veqrsnny5zudozaeymwjvtali",
3  "currency": "SAR",
4  "amount": 152,
5  "payment_methods": {
6    "stcpay": {
7      "initialization": "enabled",
8      "otp": "123"
9    }
10  },
11  "customer": {
12    "email": {
13      "address": "jane@email.com"
14    },
15    "phone": {
16      "country_code": "111",
17      "number": "222222222"
18    }
19  },
20  "settings": {
21    "success_url": "https://success.co.uk",
22    "failure_url": "https://failure.co.uk"
23  }
24}


1{
2  "id": "pay_js5diujz2kwunhokfgu7y2uxhm",
3  "processing_channel_id": "pc_3veqrsnny5zudozaeymwjvtali",
4  "currency": "SAR",
5  "amount": 152,
6  "payment_methods": {
7    "stcpay": {
8      "status": "ready",
9      "initialization": "enabled",
10      "flags": []
11    }
12  },
13  "customer": {
14    "email": {
15      "address": "jane@email.com"
16    },
17    "phone": {
18      "country_code": "111",
19      "number": "222222222"
20    }
21  },
22  "settings": {
23    "success_url": "https://success.co.uk",
24    "failure_url": "https://failure.co.uk"
25  }
26}

After the customer provides the correct OTP, the payment method status sets to ready.

After the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint, providing the id of the payment setup as the id path parameter, and stcpay as the payment_method_name path parameter.

post

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

stc pay for Payments Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Update the payment setup with the OTP

Request example

Response example

Confirm the payment