> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/integration/mobile-sdk/ios-sdk/reference/api.md).

# API

Every public type in the iOS SDK, under its Swift and Objective-C name.

Module: `EGWPay`. Minimum deployment target: iOS 15.0.

In Swift the types are unprefixed. In Objective-C the same types carry an `EGW` prefix. Both names are listed for every type.

***

## PaymentKit

`PaymentKit` / `EGWPaymentKit`

The entry point. Runs one payment at a time; starting a second while the first is on screen finishes the second immediately as `.failed` with an `invalidRequest` error.

### Initializers

```swift
init(configuration: Configuration)
init(configuration: Configuration, statusResolver: PaymentStatusResolving)
```

Objective-C: `-initWithConfiguration:` and `-initWithConfiguration:statusResolver:`.

The first form uses the built-in status lookup when `configuration.apiBaseURL` is set, and otherwise resolves every payment as `.unresolved`.

### Methods

```swift
func startPayment(_ request: PaymentRequest,
                  from presenter: UIViewController,
                  completion: @escaping (PaymentResult) -> Void)

func startPayment(_ request: PaymentRequest,
                  from presenter: UIViewController,
                  delegate: PaymentDelegate)

func startCardPayment(_ request: CardPaymentRequest,
                      card: CardInput,
                      from presenter: UIViewController,
                      completion: @escaping (PaymentResult) -> Void)

func startCardPayment(_ request: CardPaymentRequest,
                      card: CardInput,
                      from presenter: UIViewController,
                      delegate: PaymentDelegate)
```

Objective-C selectors: `startPayment:from:completion:`, `startPayment:from:delegate:`, `startCardPayment:card:from:completion:`, `startCardPayment:card:from:delegate:`.

Every overload delivers exactly one result, on the main thread, after the SDK has dismissed any interface it presented. The delegate is held weakly.

`startCardPayment` requires `checkoutAPIBaseURL` and `checkoutBaseURL` on the configuration. A missing `checkoutAPIBaseURL` fails with `invalidRequest`; a missing `checkoutBaseURL` fails with `encryptionKeyUnavailable`.

***

## Configuration

`Configuration` / `EGWConfiguration`

See [Configuration](broken://pages/f53963955478c17a845bd68be40c141079362690).

***

## PaymentRequest

`PaymentRequest` / `EGWPaymentRequest`

A hosted-checkout payment.

### Initializer

```swift
init(paymentId: String, verificationKey: String, checkoutURL: URL, returnURL: URL)
```

Objective-C: `-initWithPaymentId:verificationKey:checkoutURL:returnURL:`.

### Properties

| Property          | Type      | Description                                                                                                                  |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`       | `String`  | Read-only. The payment identifier from your backend.                                                                         |
| `verificationKey` | `String`  | Read-only. The per-payment access credential from your backend.                                                              |
| `checkoutURL`     | `URL`     | Read-only. The `_links.checkoutRedirect.href` value. Must be `http` or `https`.                                              |
| `returnURL`       | `URL`     | Read-only. The same value your backend sent as `shopRedirectUrl`.                                                            |
| `preferredMethod` | `String?` | Mutable. Opens the checkout page straight onto one method. `nil` shows the method chooser. An unrecognised value is ignored. |

### MethodHint

`PaymentRequest.MethodHint` / `EGWPaymentMethodHint`

String constants for `preferredMethod`.

| Constant                | Value            |
| ----------------------- | ---------------- |
| `MethodHint.card`       | `"card"`         |
| `MethodHint.bank`       | `"bank"`         |
| `MethodHint.clickToPay` | `"click-to-pay"` |

***

## CardPaymentRequest

`CardPaymentRequest` / `EGWCardPaymentRequest`

A payment paid through your own card form.

```swift
init(paymentId: String, verificationKey: String)
```

Objective-C: `-initWithPaymentId:verificationKey:`.

| Property          | Type     | Description |
| ----------------- | -------- | ----------- |
| `paymentId`       | `String` | Read-only.  |
| `verificationKey` | `String` | Read-only.  |

No checkout URL and no return URL: the shopper never leaves your app.

***

## PaymentResult

`PaymentResult` / `EGWPaymentResult`

Delivered to your completion block or delegate. Receive-only: applications do not construct it.

| Property        | Type             | Description                                                                        |
| --------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `outcome`       | `PaymentOutcome` | The outcome of the payment run.                                                    |
| `paymentId`     | `String`         | Always present.                                                                    |
| `paymentStatus` | `String?`        | The platform's raw status string, for example `"SETTLED"`.                         |
| `orderNumber`   | `String?`        | The platform's record of the order number your backend supplied.                   |
| `sessionId`     | `String?`        | The card session identifier. Set by the card flow only; `nil` for hosted checkout. |
| `error`         | `NSError?`       | Present when the SDK could not complete the flow.                                  |

`description` returns a short summary suitable for logs. It contains no card data and no verification key.

***

## PaymentOutcome

`PaymentOutcome` / `EGWPaymentOutcome`

| Case          | Objective-C                   | Raw value | Payment status                                                             |
| ------------- | ----------------------------- | --------- | -------------------------------------------------------------------------- |
| `.succeeded`  | `EGWPaymentOutcomeSucceeded`  | `0`       | `AUTHORIZED`, `CAPTURED`, `SETTLED`, `REFUNDED`                            |
| `.failed`     | `EGWPaymentOutcomeFailed`     | `1`       | `FAILED`, or the SDK could not run the flow                                |
| `.cancelled`  | `EGWPaymentOutcomeCancelled`  | `2`       | `CANCELLED`, `ABANDONED`, or the shopper dismissed the page                |
| `.unresolved` | `EGWPaymentOutcomeUnresolved` | `3`       | `INITIALIZED`, `SENT_FOR_PROCESSING`, an unrecognised status, or no lookup |

`.unresolved` is a normal outcome, not an error. See [Handling the result](/integration/mobile-sdk/ios-sdk/using-the-sdk/handling-the-result.md).

***

## CardInput

`CardInput` / `EGWCardInput`

A headless model for card details. Values are read at submission time.

```swift
init()
```

| Property         | Type        | Description                                                                                                                                   |
| ---------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardholderName` | `String`    | Mutable. Defaults to `""`.                                                                                                                    |
| `cardNumber`     | `String`    | Mutable. Defaults to `""`. Formatting characters are tolerated.                                                                               |
| `expiryMonth`    | `String`    | Mutable. Two digits, `"01"` through `"12"`.                                                                                                   |
| `expiryYear`     | `String`    | Mutable. Two digits, for example `"30"`.                                                                                                      |
| `securityCode`   | `String`    | Mutable. Defaults to `""`.                                                                                                                    |
| `brand`          | `CardBrand` | Read-only, derived from `cardNumber`. For display and input formatting only; never sent to the gateway and never used to reject a submission. |
| `isValid`        | `Bool`      | Read-only. `true` when every field passes validation.                                                                                         |

### Methods

```swift
func validationError(for field: CardField) -> NSError?
```

Objective-C: `-validationErrorFor:`.

Returns `nil` when the field is valid, and otherwise an `NSError` in the `com.egw.egwpay` domain with code `7` (`cardValidationFailed`) whose `localizedDescription` names the problem.

***

## CardField

`CardField` / `EGWCardField`

| Case              | Objective-C                  | Raw value |
| ----------------- | ---------------------------- | --------- |
| `.cardholderName` | `EGWCardFieldCardholderName` | `0`       |
| `.cardNumber`     | `EGWCardFieldCardNumber`     | `1`       |
| `.expiry`         | `EGWCardFieldExpiry`         | `2`       |
| `.securityCode`   | `EGWCardFieldSecurityCode`   | `3`       |

***

## CardBrand

`CardBrand` / `EGWCardBrand`

| Case          | Objective-C              | Raw value |
| ------------- | ------------------------ | --------- |
| `.unknown`    | `EGWCardBrandUnknown`    | `0`       |
| `.visa`       | `EGWCardBrandVisa`       | `1`       |
| `.mastercard` | `EGWCardBrandMastercard` | `2`       |
| `.amex`       | `EGWCardBrandAmex`       | `3`       |
| `.maestro`    | `EGWCardBrandMaestro`    | `4`       |
| `.discover`   | `EGWCardBrandDiscover`   | `5`       |

Brand detection drives display and input formatting. Whether a shop accepts a brand is decided server-side.

***

## Card text fields

Three `UITextField` subclasses that handle input behaviour and formatting. They set no colours, fonts, borders or insets, so they inherit your app's appearance. All three support `init(frame:)` and `init?(coder:)`, so they work in code and in Interface Builder.

Using them is optional.

### CardNumberTextField

`CardNumberTextField` / `EGWCardNumberTextField`

Groups digits as the shopper types, caps the length, and sets `textContentType = .creditCardNumber` so iOS autofill and Scan Card work.

| Property | Type        | Description                                            |
| -------- | ----------- | ------------------------------------------------------ |
| `digits` | `String`    | Read-only. The entered number with formatting removed. |
| `brand`  | `CardBrand` | Read-only. Derived from `digits`.                      |

### CardExpiryTextField

`CardExpiryTextField` / `EGWCardExpiryTextField`

Formats input as `MM/YY`.

| Property | Type     | Description                                                   |
| -------- | -------- | ------------------------------------------------------------- |
| `month`  | `String` | Read-only. `""` until two digits have been entered.           |
| `year`   | `String` | Read-only. `""` until more than two digits have been entered. |

### CardSecurityCodeTextField

`CardSecurityCodeTextField` / `EGWCardSecurityCodeTextField`

Masks input and caps the digit count according to the card brand.

| Property | Type        | Description                                                                        |
| -------- | ----------- | ---------------------------------------------------------------------------------- |
| `brand`  | `CardBrand` | Mutable. Set it from the number field's `brand` so the digit cap follows the card. |
| `digits` | `String`    | Read-only. The entered code.                                                       |

***

## PaymentStatusResolving

`PaymentStatusResolving` / `EGWPaymentStatusResolving`

Implement this to replace the SDK's built-in status lookup with your own.

```swift
@objc protocol PaymentStatusResolving: NSObjectProtocol {
    func resolveStatus(paymentId: String,
                       verificationKey: String,
                       completion: @escaping (_ status: String?,
                                              _ orderNumber: String?,
                                              _ error: NSError?) -> Void)
}
```

Objective-C selector: `resolveStatusWithPaymentId:verificationKey:completion:`.

Call `completion` exactly once, from any queue. Return the platform's raw status string and the SDK maps it to an outcome. A `nil` status with a `nil` error resolves to `.unresolved`.

***

## PaymentDelegate

`PaymentDelegate` / `EGWPaymentDelegate`

An alternative to the completion block.

```swift
@objc protocol PaymentDelegate: NSObjectProtocol {
    func paymentDidFinish(_ result: PaymentResult)
}
```

Objective-C selector: `paymentDidFinish:`.

Called exactly once, on the main thread, after the SDK's interface is dismissed. `PaymentKit` holds the delegate weakly, so keep your own strong reference.

***

## PaymentError

`PaymentError` is a Swift enumeration. Objective-C applications, and Swift code reading `PaymentResult.error`, see `NSError` instead.

| Member                | Value                                                 |
| --------------------- | ----------------------------------------------------- |
| `PaymentError.domain` | `"com.egw.egwpay"`                                    |
| `PaymentError.Code`   | An `Int`-backed enumeration of the twelve error codes |

See [Error handling](/integration/mobile-sdk/ios-sdk/guides/error-handling.md) for the code table and recovery guidance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ecommerce.seb.ee/integration/mobile-sdk/ios-sdk/reference/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.