# Revolut Pay iOS SDK This document provides a detailed reference for the parameters, objects, and methods available in the Revolut Pay iOS SDK. :::info For detailed instructions on how to install and integrate the SDK, see: [Accept payments via Revolut Pay - iOS](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios). ::: ## Methods and parameters ### `RevolutPaymentsSDK.configure` method The `RevolutPaymentsSDK.configure` method is used to set up the SDK with necessary configurations, such as the merchant's public API key and the environment in which the SDK will operate. Configuring the SDK needs to happen before any SDK usage, can be done on app launch by adding this to `AppDelegate`. ```swift RevolutPaymentsSDK.configure( with: .init( merchantPublicKey: String, environment: Environment ) ) ``` | Parameter | Description | Format | Required | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- | | `merchantPublicKey` | The merchant's public API key used for authorization. | `String` | Yes | | `environment` | This parameter specifies the environment in which the SDK operates. If omitted it defaults to `.production`.

Possible values are: | `Environment` | Yes | ### `RevolutPayKit.handle` method This static method processes incoming URLs when users are redirected from the Revolut app back to your app. You must call this method in your app's URL handling delegate methods to complete the payment flow. This method should be implemented in one of the following locations, depending on your app's lifecycle: - **Modern apps (iOS 13+):** In `UISceneDelegate.scene(_:openURLContexts:)` - **Legacy apps:** In `AppDelegate.application(_:open:sourceApplication:annotation:)` ```swift RevolutPayKit.handle(url: URL) ``` | Parameter | Description | Format | Required | | --------- | --------------------------------------------------------------------------------------------------- | ------ | -------- | | `url` | The URL received from the system when your app is opened via a Universal Link or custom URL scheme. | `URL` | Yes | :::info For implementation examples with both `SceneDelegate` and `AppDelegate`, see: [Accept payments via Revolut Pay - iOS: Add the URL handler](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#24-add-the-url-handler). ::: ### `RevolutPayKit.button` method This method creates a `RevolutPayButton`, a `UIView` that handles the entire Revolut Pay flow when tapped. It is the primary way to initiate a payment. The method can be configured for one of three payment flows: 1. **Standard payment:** No optional features are enabled. 1. **Fast checkout:** Set `shouldRequestShipping` to `true` to collect shipping information. 1. **Merchant-Initiated Transaction (MIT):** Set `savePaymentMethodForMerchant` to `true` to save the customer's payment details for future use. :::info Fast checkout and MIT are mutually exclusive. You can enable one or the other, but not both in the same transaction. ::: ```swift func button( style: RevolutPayButton.Style, returnURL: String, savePaymentMethodForMerchant: Bool, // or shouldRequestShipping: Bool, customer: Customer? = nil, createOrder: @escaping CreateOrderCallback, completion: @escaping (RevolutPayKit.PaymentResult) -> Void ) -> RevolutPayButton ``` | Parameter | Description | Format | Required | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -------- | | `style` | Contains styling parameters of the button. | [`RevolutPayButton.Style`](#revolutpaybuttonstyle-object) | Yes | | `returnURL` | Upon payment completion, the Revolut app attempts to open this URL. This can be a Universal Link or a custom URL scheme.

Possible values: | `String` | Yes | | `savePaymentMethodForMerchant` | If `true`, the customer gives permission for their payment method to be saved for future merchant-initiated transactions. Default is `false`.

To learn more about merchant initiated transactions, see: [Accept payments via Revolut Pay - iOS: Advanced features](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#53-advanced-features). | `Boolean` | No | | `shouldRequestShipping` | If `true`, the shipping address and delivery method are collected from the user via the Revolut Pay flow. Requires backend support for Fast checkout. Default is `false`.

To learn more about Fast checkout, see: [Accept payments via Revolut Pay - iOS: Advanced features](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#53-advanced-features). | `Boolean` | No | | `customer` | An object containing customer details you already have, which will be pre-filled during widget initialisation. | [`Customer`](#customer-object) | No | | `createOrder` | A callback function that is executed after the user taps the button. Your app should request an order `token` from your backend and pass it to the `createOrderHandler`. | `Closure` | Yes | | `completion` | A closure that is called when the payment flow is complete. It returns a [`PaymentResult`](#revolutpaykitpaymentresult-enumeration) indicating success, failure, or user abandonment.

Further considerations

The completion closure might indicate a failure even if the user later completes the payment, such as in scenarios where they initially abandon the payment or if there is a transient issue during payment processing. Therefore, it is crucial to verify the final payment status with your backend before concluding that the payment has failed permanently. This helps in avoiding scenarios where a transaction might be unintentionally processed more than once. | `Closure` | Yes | ### `RevolutPayKit.swiftUIButton` method This method creates a SwiftUI-native Revolut Pay button that functions identically to the UIKit version. ```swift @ViewBuilder func swiftUIButton( style: RevolutPayButton.Style, returnURL: String, savePaymentMethodForMerchant: Bool, // or shouldRequestShipping: Bool, customer: Customer? = nil, createOrder: @escaping CreateOrderCallback, completion: @escaping (RevolutPayKit.PaymentResult) -> Void ) -> some View ``` | Parameter | Description | Format | Required | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -------- | | `style` | Contains styling parameters of the button. | [`RevolutPayButton.Style`](#revolutpaybuttonstyle-object) | Yes | | `returnURL` | Upon payment completion, the Revolut app attempts to open this URL. This can be a Universal Link or a custom URL scheme.

Possible values: | `String` | Yes | | `savePaymentMethodForMerchant` | If `true`, the customer gives permission for their payment method to be saved for future merchant-initiated transactions. Default is `false`.

To learn more about merchant initiated transactions, see: [Accept payments via Revolut Pay - iOS: Advanced features](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#53-advanced-features). | `Boolean` | No | | `shouldRequestShipping` | If `true`, the shipping address and delivery method are collected from the user via the Revolut Pay flow. Requires backend support for Fast checkout. Default is `false`.

To learn more about Fast checkout, see: [Accept payments via Revolut Pay - iOS: Advanced features](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#53-advanced-features). | `Boolean` | No | | `customer` | An object containing customer details you already have, which will be pre-filled during widget initialisation. | [`Customer`](#customer-object) | No | | `createOrder` | A callback function that is executed after the user taps the button. Your app should request an order `token` from your backend and pass it to the `createOrderHandler`. | `Closure` | Yes | | `completion` | A closure that is called when the payment flow is complete. It returns a [`PaymentResult`](#revolutpaykitpaymentresult-enumeration) indicating success, failure, or user abandonment.

Further considerations

The completion closure might indicate a failure even if the user later completes the payment, such as in scenarios where they initially abandon the payment or if there is a transient issue during payment processing. Therefore, it is crucial to verify the final payment status with your backend before concluding that the payment has failed permanently. This helps in avoiding scenarios where a transaction might be unintentionally processed more than once. | `Closure` | Yes | ### `RevolutPayKit.pay` method This method allows you to initiate the Revolut Pay flow programmatically without requiring the user to tap a `RevolutPayButton`. ```swift func pay( orderToken: String, returnURL: String, savePaymentMethodForMerchant: Bool, // or shouldRequestShipping: Bool, customer: Customer? = nil, completion: @escaping (RevolutPayKit.PaymentResult) -> Void ) ``` | Parameter | Description | Format | Required | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------- | | `orderToken` | The `token` for the order created via the Merchant API, passed to the SDK from your backend. | `String` | Yes | | `returnURL` | Upon payment completion, the Revolut app attempts to open this URL. This can be a Universal Link or a custom URL scheme.

Possible values: | `String` | Yes | | `savePaymentMethodForMerchant` | If `true`, the customer gives permission for their payment method to be saved for future merchant-initiated transactions. Default is `false`.

To learn more about merchant initiated transactions, see: [Accept payments via Revolut Pay - iOS: Advanced features](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#53-advanced-features). | `Boolean` | No | | `shouldRequestShipping` | If `true`, the shipping address and delivery method are collected from the user via the Revolut Pay flow. Requires backend support for Fast checkout. Default is `false`.

To learn more about Fast checkout, see: [Accept payments via Revolut Pay - iOS: Advanced features](/docs/guides/merchant/accept-payments/online-payments/revolut-pay/mobile/ios#53-advanced-features). | `Boolean` | No | | `customer` | An object containing customer details you already have, which will be pre-filled during widget initialisation. | [`Customer`](#customer-object) | No | | `completion` | A closure that is called when the payment flow is complete. It returns a [`PaymentResult`](#revolutpaykitpaymentresult-enumeration) indicating success, failure, or user abandonment. | `Closure` | Yes | ### `RevolutPayKit.promotionalBanner` method This method creates a `UIView` that displays a promotional banner inviting users to join Revolut. ```swift func promotionalBanner( style: PromotionalBannerStyle = .init(), transactionId: String, amount: Int64?, currency: Currency, customer: PromotionalBannerCustomer? ) -> UIView ``` | Parameter | Description | Format | Required | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------- | | `style` | Contains styling parameters for the banner. | [`PromotionalBannerStyle`](#promotionalbannerstyle-object) | No | | `transactionId` | The ID of the transaction corresponding to the promotional offer. | `String` | Yes | | `amount` | The amount paid by the customer, in the currency's smallest unit (e.g., 1000 for £10.00). | `Int64` | No | | `currency` | The payment currency in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217). | [`Currency`](#currency-enumeration) | Yes | | `customer` | An object containing customer details to pre-fill the offer. | [`PromotionalBannerCustomer`](#promotionalbannercustomer-object) | No | ## Helper objects and types ### `Customer` object This object holds the customer's information. To create a `Customer` object, use its initialser: ```swift public init( name: String? = nil, dateOfBirth: GenericDate? = nil, email: String? = nil, phone: String? = nil, countryCode: String? = nil ) ``` | Parameter | Description | Format | Required | | ------------- | ----------------------------------------------------------------- | ------------------------------------ | -------- | | `name` | Customer's full name. | `String` | No | | `dateOfBirth` | Customer's date of birth. | [`GenericDate`](#genericdate-object) | No | | `email` | Customer's email address. | `String` | No | | `phone` | Customer's phone number, including the `+` sign and country code. | `String` | No | | `countryCode` | Customer's country in ISO 3166-1 alpha-2 format (e.g., "GB"). | `String` | No | ### `GenericDate` object This object represents a simple Gregorian calendar date. To create a `GenericDate` object, use its failable initialiser: ```swift public init?( day: UInt, month: UInt, year: UInt ) ``` | Parameter | Description | Format | Required | | --------- | ---------------------------------------------------- | ------ | -------- | | `day` | Day of the date. Must be between 1 and 31. | `UInt` | Yes | | `month` | Month of the date. Must be between 1 and 12. | `UInt` | Yes | | `year` | Year of the date. Must have four digits (e.g. 1970). | `UInt` | Yes | ### `RevolutPayButton.Style` object This object defines the visual style of the `RevolutPayButton`. To create a `Style` object, use its initializer: ```swift public init( size: Size = .large, variants: VariantModes = .init(), radius: Radius = .small, attachmentStyle: AttachmentStyle? = .init() ) ``` | Parameter | Description | Format | Required | | ----------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- | -------- | | `size` | The size of the button. Default is `.large`. | [`Size`](#revolutpaybuttonstylesize) | No | | `variants` | The color schemes for light and dark modes. | [`VariantModes`](#revolutpaybuttonstylevariantmodes) | No | | `radius` | The corner radius of the button. Default is `.small`. | [`Radius`](#revolutpaybuttonstyleradius) | No | | `attachmentStyle` | The style of the optional attachment box, used to attract users. | [`AttachmentStyle`](#revolutpaybuttonstyleattachmentstyle) | No | #### `RevolutPayButton.Style.Size` An enum that defines the size of the button, which affects its intrinsic content size. ```swift public enum Size { case large case medium case small case extraSmall } ``` #### `RevolutPayButton.Style.VariantModes` A struct that defines the button's appearance for light and dark modes. To create a `VariantModes` object, use its initialiser: ```swift public init( lightMode: Style.Variant = .dark, darkMode: Style.Variant = .light ) ``` | Parameter | Description | Format | Required | | ----------- | ---------------------------------- | ------------------------------------------ | -------- | | `lightMode` | The variant to use for light mode. | [`Variant`](#revolutpaybuttonstylevariant) | No | | `darkMode` | The variant to use for dark mode. | [`Variant`](#revolutpaybuttonstylevariant) | No | #### `RevolutPayButton.Style.Variant` An enum that defines the colour scheme of the button. ```swift public enum Variant { case light case dark case lightOutlined case darkOutlined } ``` | Case | Description | | --------------- | ------------------------------------------------------------ | | `light` | Light background. Should be used on dark screen backgrounds. | | `dark` | Dark background. Should be used on light screen backgrounds. | | `lightOutlined` | Light background with a dark outline. | | `darkOutlined` | Dark background with a light outline. | :::info For more information about colour scheme recommendations see: [Revolut Pay button guidelines](/docs/resources/revolut-pay-button-guidelines) ::: #### `RevolutPayButton.Style.Radius` An enum that defines the corner radius of the button. ```swift public enum Radius { case none case small case medium case large @available(*, deprecated, renamed: "large") case rounded } ``` :::info For more information about button style recommendations see: [Revolut Pay button guidelines](/docs/resources/revolut-pay-button-guidelines) ::: #### `RevolutPayButton.Style.AttachmentStyle` A struct that defines the style for the optional attachment box displayed below the button. ```swift public struct AttachmentStyle { let currency: Currency } ``` | Parameter | Description | Format | Required | | ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------- | | `currency` | The currency displayed in the reward text in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. | [`Currency`](#currency-enumeration) | Yes | ### `PromotionalBannerStyle` object This object defines the visual style of the promotional banner. To create a `PromotionalBannerStyle` object, use its initialiser: ```swift public init( accentColor: UIColor? = nil, backgroundColor: UIColor? = nil, bannerCornerRadius: CGFloat = 16, componentCornerRadius: CornerRadius = .default, border: Border? = nil ) ``` | Parameter | Description | Format | Required | | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------- | -------- | | `accentColor` | The banner's accent color. Other colors are derived from this. | `UIColor` | No | | `backgroundColor` | The banner's background color. | `UIColor` | No | | `bannerCornerRadius` | The corner radius of the banner's view. | `CGFloat` | No | | `componentCornerRadius` | The corner radius of the banner's components. | [`CornerRadius`](#promotionalbannerstylecornerradius-enumeration) | No | | `border` | The banner's border configuration. | [`Border`](#promotionalbannerstyleborder-object) | No | #### `PromotionalBannerStyle.Border` object This object defines the style for the promotional banner's border. To create a `Border` object, use its initialiser: ```swift public init( color: UIColor? = nil, width: CGFloat = 1 ) ``` | Parameter | Description | Format | Required | | --------- | --------------------------------- | --------- | -------- | | `color` | The color of the banner's border. | `UIColor` | No | | `width` | The width of the banner's border. | `CGFloat` | No | #### `PromotionalBannerStyle.CornerRadius` enumeration This enum defines the corner radius style for components within the promotional banner. ```swift public enum CornerRadius { case custom(CGFloat) case circular case `default` } ``` | Case | Description | | ----------------- | --------------------------------------------------------- | | `custom(CGFloat)` | A custom corner radius with a specific `CGFloat` value. | | `circular` | A fully rounded corner radius, creating a circular shape. | | `default` | The default corner radius style provided by the SDK. | ### `PromotionalBannerCustomer` object This object holds the customer's information for the promotional banner. To create a `PromotionalBannerCustomer` object, use its initialiser: ```swift public init( name: String? = nil, email: String? = nil, phone: String? = nil, country: Country? = nil ) ``` | Parameter | Description | Format | Required | | --------- | ----------------------------------------------------------------- | --------------------------------- | -------- | | `name` | Customer's full name. | `String` | No | | `email` | Customer's email address. | `String` | No | | `phone` | Customer's phone number, including the `+` sign and country code. | `String` | No | | `country` | Customer's country. | [`Country`](#country-enumeration) | No | ### `Currency` enumeration This enum represents currency in ISO 4217 format. Use dot notation (e.g., `.GBP`) to select a value. ```swift public enum Currency: String { case AED case AUD case BGN case CAD case CHF case CZK case DKK case EUR case GBP case HKD case HRK case HUF case ILS case JPY case MXN case NOK case NZD case PLN case QAR case RON case RUB case SAR case SEK case SGD case THB case TRY case USD case ZAR } ``` ### `Country` enumeration This enum maps [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes to human-readable format. Use dot notation (e.g., `.unitedKingdom`) to select a value. ```swift public enum Country: String { case austria = "AT" case belgium = "BE" case bulgaria = "BG" case croatia = "HR" case cyprus = "CY" case czechRepublic = "CZ" case denmark = "DK" case estonia = "EE" case finland = "FI" case france = "FR" case germany = "DE" case greece = "GR" case hungary = "HU" case iceland = "IS" case ireland = "IE" case italy = "IT" case latvia = "LV" case liechtenstein = "LI" case lithuania = "LT" case luxembourg = "LU" case malta = "MT" case monaco = "MO" case netherlands = "NL" case norway = "NO" case poland = "PL" case portugal = "PT" case romania = "RO" case spain = "ES" case slovenia = "SI" case slovakia = "SK" case sweden = "SE" case switzerland = "CH" case ukraine = "UA" case unitedKingdom = "GB" case vaticanCity = "VA" case canada = "CA" case mexico = "MX" case usa = "US" case brazil = "BR" case hongKong = "HK" case india = "IN" case japan = "JP" case kazakhstan = "KZ" case macau = "MC" case singapore = "SG" case australia = "AU" case newZealand = "NZ" } ``` ## Callbacks and results ### `RevolutPayKit.PaymentResult` enumeration This enum represents the final outcome of a payment flow and is returned in the `completion` closure. | Case | Description | | ----------------------- | ------------------------------------------------------------ | | `.success` | The payment was successful. | | `.failure(Error)` | The payment failed with an associated `RevolutPayKit.Error`. | | `.userAbandonedPayment` | The user dismissed or abandoned the payment flow. | ### `RevolutPayKit.CreateOrderHandler` class This handler is provided in the `createOrder` callback and is used to pass the order `token` back to the SDK. | Method | Description | | ------------------------- | ------------------------------------------------------------------------------ | | `set(orderToken: String)` | Sets the order `token` obtained from your backend to proceed with the payment. | | `cancel()` | Stops the payment flow. | ## Errors ### `RevolutPayKit.Error` enumeration This enum defines the possible errors that can be returned in the `.failure` case of a `PaymentResult`. ```swift public enum Error: Swift.Error { case sdkNotConfigured case kitAlreadyInUse case paymentFailed case cantBuildRevolutUniversalLink(token: String, returnURL: String) case cantAuthenticate case apiError(Swift.Error?) case internalError } ``` | Case | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `sdkNotConfigured` | The SDK was not configured before use. Ensure `RevolutPaymentsSDK.configure(with:)` has been called. | | `kitAlreadyInUse` | The `RevolutPayKit` instance is already processing another payment. | | `paymentFailed` | The payment failed for reasons like insufficient funds. | | `cantBuildRevolutUniversalLink` | The SDK could not construct the necessary URL for redirection, possibly due to an invalid token or return URL. | | `cantAuthenticate` | The user could not be authenticated. | | `apiError` | An internal API error occurred, such as using a token for an already paid order. | | `internalError` | An unspecified internal error occurred. |