# stc pay for Unified Payments API

> **Note**
>
> We no longer support new stc pay integrations on the Payments API. For new stc pay integrations, use the [Payment Setup API](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api.md).

stc pay follows a two-step process:

1. [Request a payment context](#Request_a_payment_context) to trigger a one-time password (OTP).
2. [Request a payment](#Request_a_payment), using a one-time password (OTP).

---

## Request a payment context

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

For the full API specification, see the [API reference](https://api-reference.checkout.com/#tag/Payment-Context).

> **Information**
>
> The Payment Contexts API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payment-contexts`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payment-contexts`

### Request example

```json
{
    "amount": 100,
    "currency": "SAR",
    "source": {
        "type": "stcpay"
    },
    "reference": "ORD-5023-4E89",
    "capture": "true",
    "customer": {
        "phone": {
            "country_code": "111",
            "number": "222222222"
        }
    },
    "processing_channel_id": "pc_3wuuqzzjbrzexbu4osjacmk7q4"
}
```

### Response example

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

```json
{
    "id": "pct_bi6zuj5bc23u3anhbpkqbqlhmm",
    "partner_metadata": {},
    "_links": {
        "self": {
            "href": "https://{prefix}.api.sandbox.checkout.com/payment-contexts/pct_xxx"
        }
    }
}
```

---

## Request a payment

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](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout).

> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
    "payment_context_id": "pct_bi6zuj5bc23u3anhbpkqbqlhmm",
    "processing": {
        "otp_value": "123"
    }
}
```

### Response example

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

```json
{
    "id": "pay_zc6gq2wzgcauhhjxsltdmsudri",
    "status": "Pending",
    "_links": {
        "self": {
            "href": "https://gwc.ckotech.co/payments/pay_zc6gq2wzgcauhhjxsltdmsudri"
        }
    }
}
```

---

## Get details about a payment

You can retrieve details about an existing stc pay payment.

### Endpoints

For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails).

> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

### Response example

```json
{
    "id": "pay_zc6gq2wzgcauhhjxsltdmsudri",
    "requested_on": "2024-04-26T13:14:41.7984245Z",
    "source": {
        "type": "stcpay"
    },
    "amount": 100,
    "currency": "SAR",
    "payment_type": "Regular",
    "reference": "ORD-5023-4E89",
    "status": "Captured",
    "approved": true,
    "balances": {
        "total_authorized": 100,
        "total_voided": 0,
        "available_to_void": 0,
        "total_captured": 100,
        "available_to_capture": 0,
        "total_refunded": 0,
        "available_to_refund": 100
    },
    "processing": {
        "otp_value": "123"
    },
    "_links": {
        "self": {
            "href": "https://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri"
        },
        "actions": {
            "href": "https://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri/actions"
        },
        "refund": {
            "href": "https://gwc.ckotech.co/gateway/payments/pay_zc6gq2wzgcauhhjxsltdmsudri/refunds"
        }
    }
}
```

---

## Refund a payment

stc pay supports full, partial, and multiple partial refunds. You can refund a payment using the [Dashboard](https://dashboard.checkout.com), or the [Refund API](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md).

### Endpoints

For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment).

> **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`

### Request example

```json
{
  "amount": 100
}
```

### Response example

```json
{
  "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
    }
  }
}
```

---

## Test stc pay

> **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 `111`
  - 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](https://www.checkout.com/docs/developer-resources/codes/api-response-codes.md) for a description of each response code.