# stc pay for Payment Setup API

To accept stc pay payments, you must:

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

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.

> **Information**
>
> The Payment Setup 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/payments/setups`

**Sandbox**

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

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "SAR",
  "amount": 1000,
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_type": "Regular",
  "customer": {
    "email": "hannah.bret@example.com",
    "phone": {
      "country_code": "966",
      "number": "555123456"
    }
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

- `processing_channel_id` – The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) 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

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "SAR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_methods": {
    "stcpay": {
      "initialization": "disabled",
      "status": "initialization_required",
      "flags": []
    }
  },
  "available_payment_methods": [
    "stcpay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

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](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api.md#Payment_method_status).
- `flags` – An array of error codes or indicators that highlight missing or invalid information.

---

## Update the payment setup

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

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

Call the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint, setting `payment_methods.stcpay.initialization` to `enabled`.

Additionally, provide the following fields:

| Field | Description |
| --- | --- |
| `amount`<br>`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md). <br><br>Minimum: 1 <br><br>**Required** |
| `currency`<br>`string` | The three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). <br><br>**Required** |
| `customer.phone.country_code`<br>`string` | The customer's phone country code. <br><br>**Required** |
| `customer.phone.number`<br>`string` | The customer's phone number registered with stc pay. <br><br>**Required** |
| `customer.email`<br>`string` | The customer's email address. |
| `reference`<br>`string` | The payment reference. <br><br>Max length: 80 characters |

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "SAR",
  "amount": 1000,
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_type": "Regular",
  "customer": {
    "email": "hannah.bret@example.com",
    "phone": {
      "country_code": "966",
      "number": "555123456"
    }
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "stcpay": {
      "initialization": "enabled"
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "SAR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_methods": {
    "stcpay": {
      "initialization": "enabled",
      "action": {
        "type": "otp"
      },
      "status": "action_required",
      "flags": []
    }
  },
  "available_payment_methods": [
    "stcpay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

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`.

---

## Submit the one-time password (OTP)

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](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint again and setting `payment_methods.stcpay.otp` to the value the customer provides.

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

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "SAR",
  "amount": 1000,
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_type": "Regular",
  "customer": {
    "email": "hannah.bret@example.com",
    "phone": {
      "country_code": "966",
      "number": "555123456"
    }
  },
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "stcpay": {
      "initialization": "enabled",
      "otp": "123456"
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "SAR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_methods": {
    "stcpay": {
      "initialization": "enabled",
      "status": "ready",
      "flags": []
    }
  },
  "available_payment_methods": [
    "stcpay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

---

## Verify payment authorization

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

Call the [Get a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/getAPaymentSetup) 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

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

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 1000,
  "currency": "SAR",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "stc pay payment",
  "payment_methods": {
    "stcpay": {
      "initialization": "enabled",
      "status": "ready",
      "flags": []
    }
  },
  "available_payment_methods": [
    "stcpay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

---

## Confirm the payment

When the payment status changes to `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

- The payment setup `id` as the `{id}` path parameter.
- `stcpay` as the `{payment_method_name}` path parameter.

**Production**

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

**Sandbox**

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