STC Pay
Beta

Last updated: August 16, 2023

Start accepting payments using STC Pay, a favorite payment method in Saudi Arabia.

STC Pay enables customers to transfer funds, add funds to a digital wallet, and make payments on ecommerce websites.

Information

To start accepting STC Pay payments, contact your Account Manager.

Model	Gateway
Payment flow	Direct
Payment method type	Digital wallet
One-step payment
Authorization
Capture
Refund
Partial refund
Chargeback
Recurring payment

STC Pay follows a two-step process:

Request a payment.
Capture a payment, using a one-time password (OTP).

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 100,
3  "currency": "SAR",
4  "source": {
5    "type": "stcpay"
6  },
7  "reference": "ORD-5023-4E89",
8  "capture": "true",
9  "customer": {
10    "email": "[email protected]",
11    "name": "John Smith",
12    "phone": {
13      "country_code": "111",
14      "number": "222222222"
15    }
16  }
17}

If you receive a 202 Success response containing a status field set to Pending, your request was successful.


1{
2  "id": "pay_zc6gq2wzgcauhhjxsltdmsudri",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "number": "222222222",
11      "country_code": "111"
12    }
13  },
14  "_links": {
15    "self": {
16      "href": "http://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri"
17    }
18  }
19}

To capture a payment, you must submit the OTP provided by the customer.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments/{id}/captures


1{
2  "processing": {
3    "otp_value": "123"
4  }
5}


1{
2  "action_id": "act_saksxakpjahuhjltfv654qoaim",
3  "_links": {
4    "payment": {
5      "href": "http://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji"
6    }
7  }
8}

You can retrieve details about an existing STC Pay payment.

For the full API specification, see the API reference.

get

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


1{
2  "id": "pay_fysbbiwwomyebab5afvewiytji",
3  "requested_on": "2023-06-05T07:37:04.4237199Z",
4  "source": {
5    "type": "stcpay"
6  },
7  "amount": 100,
8  "currency": "SAR",
9  "payment_type": "Regular",
10  "reference": "ORD-5023-4E89",
11  "status": "Authorized",
12  "approved": true,
13  "balances": {
14    "total_authorized": 100,
15        "total_voided": 0,
16        "available_to_void": 100,
17        "total_captured": 0,
18        "available_to_capture": 100,
19        "total_refunded": 0,
20        "available_to_refund": 0
21  },
22  "customer": {
23    "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
24    "email": "[email protected]",
25    "name": "John Smith",
26    "phone": {
27        "country_code": "111",
28        "number": "222222222"
29    }
30  },
31  "_links": {
32    "self": {
33        "href": "https://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji"
34    },
35    "actions": {
36        "href": "https://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji/actions"
37    },
38    "capture": {
39        "href": "https://gwc.ckotech.co/gateway/payments/pay_fysbbiwwomyebab5afvewiytji/captures"
40    }
41  }
42}

STC Pay supports full, partial, and multiple partial refunds. You can refund a payment using the Dashboard, or the Refund API.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments/{id}/refunds


1{
2  "amount": 100
3}


1{
2  "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
3  "_links": {
4    "payment": {
5      "href": "https://api.sandbox.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
6    }
7  }
8}

You may receive the following webhooks when using STC Pay:

Webhook	Description
`payment_pending`	Occurs when an asynchronous payment request was successfully initiated.
`payment_approved`	Occurs when an authorization for a payment is successfully approved.
`payment_captured`	Occurs when a capture is successful.
`payment_capture_declined`	Occurs when a capture is declined.
`payment_refunded`	Occurs when a full or partial refund is successful.
`payment_refund_declined`	Occurs when a refund is declined.

View all of our webhook notifications.

Note

To start testing, contact your Account Manager and ask to activate STC Pay payments in the sandbox environment.

Create an STC Pay payment using the steps described previously. In your request, set the customer.phone.country_code field to 111, and the customer.phone.number field to 222222222.
Capture the payment. In your request, set the processing.otp_value field to 123.

We've made some changes to our API

STC Pay
Beta

Information

Request a payment

Request example

Response example

Capture a payment

Endpoints

Request example

Response example

Get details about a payment

Endpoints

Response example

Refund a payment

Endpoints

Request example

Response example

Webhooks

Test STC Pay

Note