# stc pay for mobile app

Accept stc pay payments on your app with [Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app.md), our pre-built, customizable payment user interface that you can embed directly into your mobile application. Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

---

## How it works

1. The customer opens the checkout screen.
2. You perform a server-side request to create a payment session.
3. You use the payment session data on the client side to create and render Flow for mobile.
4. Flow for mobile displays the available payment methods to the customer. For stc pay, the customer enters their phone number and verifies it with a one-time password (OTP) sent via SMS.
5. When the customer confirms the OTP, Flow for mobile performs a payment request and handles any additional actions required.
6. You receive a webhook notifying you of the payment status.

---

## Before you start

Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com.

Create a [public key and a secret key](https://www.checkout.com/docs/resources/api-authentication/api-keys.md) from the [Dashboard](https://dashboard.checkout.com), with the following key scopes:

- Public key – `payment-sessions:pay` and `vault-tokenization`
- Secret key – `payment-sessions`

To receive webhooks for the [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway), [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).

Integrate with [Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/get-started-with-flow-for-mobile.md) before continuing.

Ensure your account has stc pay enabled. To enable stc pay, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

---

## Add the SDK dependency

**Android**

In your project-level `build.gradle`, add the following repositories:

```gradle
repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
    maven { url = uri("https://maven.fpregistry.io/releases") }
}
```

In your app-level `build.gradle`, add the following dependency:

```gradle
dependencies {
    implementation 'com.checkout:checkout-android-components:$latest_version'
    implementation('com.checkout:checkout-android-components-payment-methods-redirect:$latest_version')
}
```

**iOS**

To add payment methods to your iOS app, enable the `CheckoutPaymentMethods` plugin.

If you have already added the `checkout-ios-components` package:

1. In Xcode, select your project, then select the _Package Dependencies_ tab.
2. Find `checkout-ios-components` and select the pencil icon to edit it.
3. Select `CheckoutPaymentMethods` in the product list and confirm.

If you are adding the package for the first time:

1. Select _File_ > _Add Package Dependencies_.
2. Enter the `checkout-ios-components` repository URL.
3. Select both `CheckoutComponents` and `CheckoutPaymentMethods` from the product list.
4. Select _Add Package_.

---

## Create a new payment session `Server side`

When the customer is ready to pay, send a server-side request to securely create a `PaymentSession` object. The `PaymentSession` contains the information required to handle all steps of the payment flow.

> **Note**
>
> Do not embed your secret key in your client-side code.

Call the [Create a Payment Session](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) endpoint.

> **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-sessions`

**Sandbox**

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

### Request example

```json
{
  "amount": 1000,
  "currency": "SAR",
  "reference": "ORDER_01234",
  "display_name": "Online shop",
  "payment_type": "Regular",
  "billing": {
    "address": {
      "country": "SA"
    }
  },
  "customer": {
    "name": "Jia Tsang",
    "email": "jia.tsang@example.com"
  },
  "items": [
    {
      "reference": "0001",
      "name": "Gold Necklace",
      "quantity": 1,
      "unit_price": 1000
    }
  ],
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

In the request body, provide the following:

| Field | Description |
| --- | --- |
| `currency` | The three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). Set to `SAR`. <br><br>**Required** |
| `billing.address.country` | The customer's billing country. Set to `SA`. <br><br>**Required** |
| `reference` | Your unique reference for the payment. |

### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34"
}
```

The payment session response also determines which payment methods can be displayed to the customer. The response is determined by the customer's device and region.

---

## Enable stc pay in Flow for mobile

Enable stc pay in Flow for mobile when creating a `CheckoutComponents` instance.

**Android**

Pass `StcPay.NAME` when creating a flow or standalone component. `StcPay.NAME` is a pre-built `PaymentMethodName("stcpay")` constant exposed by the SDK:

```kotlin
import com.checkout.components.paymentmethods.redirect.stcpay.StcPay

// Include stc pay in a Flow component (renders all available payment methods)
val flow = checkoutComponents.create(ComponentName.Flow)

// Or create a standalone stc pay component
val stcPayComponent = checkoutComponents.create(StcPay.NAME)
```

Render the component in Compose UI with `Render()` or in a View container with `provideView()`:

```kotlin
// Compose
stcPayComponent.Render()

// View
stcPayComponent.provideView(containerView)
```

**iOS**

Pass the providers you want to support to the `providers:` parameter when you create a flow component:

```swift
import CheckoutComponents
import CheckoutPaymentMethods

let sdk = CheckoutComponents(configuration: configuration)

let flow = try sdk.create(
  .flow(
    options: [.card()],
    providers: [CheckoutPaymentMethods.Provider.stcPay]
  )
)
```

Additionally, if you only want to render stc pay, you can create a standalone component:

```swift
import CheckoutComponents
import CheckoutPaymentMethods

let sdk = CheckoutComponents(configuration: configuration)

let stcPay = try sdk.create(CheckoutPaymentMethods.Provider.stcPay)
```

> **Note**
>
> stc pay uses a phone number and one-time password (OTP) verification step rather than a redirect. While the customer is on the phone-entry step, the pay button is not required. If you render your own custom pay button, check `isPayButtonRequired()` (Android) or `isPayButtonRequired` (iOS) to know when to show it. See the [PaymentMethodComponent](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/android/paymentmethodcomponent.md) and [Actionable](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference/ios/actionable.md) library reference pages.

---

## Handle the payment response `Client side`

Depending on the payment outcome, Checkout.com redirects the customer to the `success_url` or `failure_url` you specified when you created the `PaymentSession`.

We send you a webhook notifying you of changes to the payment's status. Wait for the webhook callback before you start your order fulfillment process. For the full list of stc pay supported webhook events, see the [Webhooks section](https://www.checkout.com/docs/payments/add-payment-methods/stc-pay.md#Webhooks).

For payments submitted with Flow, the `PaymentSession` ID appears in the webhook payload's `data.metadata.cko_payment_session_id` field.

---

## Next steps

**[Customize Flow for mobile](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/get-started-with-flow-for-mobile.md)**

Learn how to customize Flow for mobile.

**[Flow for mobile library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-mobile-app/flow-for-mobile-library-reference.md)**

See the configuration options and error handling steps for Flow for mobile.