stc pay

Last updated: October 23, 2024

Information

stc pay is also available through Flow. Flow enables you to accept payments on your website using Checkout.com's global network of payment methods with a single integration.

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

Information

To enable stc pay payments on your account, contact your Account Manager or [email protected].

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 context to trigger a one-time password (OTP).
Request a payment, using a one-time password (OTP).

Request a payment context to trigger the one-time password (OTP) sent to the customer:

For the full API specification, see the API reference.

Information

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

post

https://api.checkout.com/payment-contexts


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

If you receive a 201 Created response code, your request was successful:


1{
2    "id": "pct_bi6zuj5bc23u3anhbpkqbqlhmm",
3    "partner_metadata": {},
4    "_links": {
5        "self": {
6            "href": "https://api.sandbox.checkout.com/payment-contexts/pct_xxx"
7        }
8    }
9}

Request the payment with the the OTP provided by the customer.

Information

You must request the payment within two minutes after requesting the payment context. Otherwise, the payment will be declined with a 20019 - Transaction has expired response code.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2    "payment_context_id": "pct_bi6zuj5bc23u3anhbpkqbqlhmm",
3    "processing": {
4        "otp_value": "123"
5    }
6}

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    "_links": {
5        "self": {
6            "href": "https://gwc.ckotech.co/payments/pay_zc6gq2wzgcauhhjxsltdmsudri"
7        }
8    }
9}

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_zc6gq2wzgcauhhjxsltdmsudri",
3    "requested_on": "2024-04-26T13:14:41.7984245Z",
4    "source": {
5        "type": "stcpay"
6    },
7    "amount": 100,
8    "currency": "SAR",
9    "payment_type": "Regular",
10    "reference": "ORD-5023-4E89",
11    "status": "Captured",
12    "approved": true,
13    "balances": {
14        "total_authorized": 100,
15        "total_voided": 0,
16        "available_to_void": 0,
17        "total_captured": 100,
18        "available_to_capture": 0,
19        "total_refunded": 0,
20        "available_to_refund": 100
21    },
22    "processing": {
23        "otp_value": "123"
24    },
25    "_links": {
26        "self": {
27            "href": "https://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri"
28        },
29        "actions": {
30            "href": "https://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri/actions"
31        },
32        "refund": {
33            "href": "https://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri/refunds"
34        }
35    }
36}

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.

To test stc pay, create an stc pay payment context request using:

the customer.phone.country_code field set to 777
the customer.phone.number fields and the processing.otp_value field in your subsequent payment request set to a value from the following table, depending on which outcome you want to simulate:

Response Code	Description	Phone Number	OTP
`20120`	Declined Payment Context - When phone number is not accepted by stc pay	222222223	N/A
`20120`	Declined Payment - stc pay account status is not valid to perform this transaction or customer registration with stc pay is incomplete	222222222	321
`20051`	Declined Payment - stc pay account does not have sufficient funds	222222222	456
`20151`	Declined Payment - OTP is not accepted	222222222	789
`20019`	Declined Payment - Transaction has expired	222222222	420

See response codes for a description of each response code.

stc pay

Information

Information

Request a payment context

Information

Request example

Response example

Request a payment

Information

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