# Revolut Merchant Card Form SDK
This page contains information about the available methods and parameters of the Revolut Merchant Card Form SDK for iOS.
:::info
For detailed instructions on how to install and integrate the SDK, see: [Accept payments via Revolut Merchant Card Form SDK - iOS](/docs/guides/merchant/accept-payments/online-payments/card-payments/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:** - **`.production`**
- **`.sandbox`**
| `Environment` | Yes |
### `RevolutMerchantCardFormKit.pay` method
The `RevolutMerchantCardFormKit.pay` method initiates the payment process by presenting a card payment form to the user. It manages the collection of payment details and handles the payment transaction. This method is critical for processing card payments within your app.
```swift
RevolutMerchantCardFormKit.pay(
publicId: String,
billingAddress: Address? = nil,
shippingAddress: Address? = nil,
email: String? = nil,
savePaymentMethodFor: UserType? = nil,
completion: @escaping (RevolutMerchantCardFormKit.PaymentResult) -> Void
)
```
| Parameter | Description | Format | Required |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- |
| `publicId` | The unique `token` of the order, obtained from your server after creating an order. This identifies the transaction to be processed. | String | Yes |
| `billingAddress` | An optional parameter that accepts an object of type `RevolutMerchantCardFormKit.Address`, representing the customer's billing address. Providing this can help increase payment acceptance rates. | `Address` | No |
| `shippingAddress` | An optional parameter that accepts an object of type `RevolutMerchantCardFormKit.Address`, representing the customer's shipping address. | `Address` | No |
| `email` | The customer's email address, which can be used for sending payment confirmations and receipts. | String | No |
| `savePaymentMethodFor` | This parameter accepts a `UserType` enum, which indicates whether the payment method should be saved for the customer or merchant.
**Possible values:**
- **`.customer`** - This method is used only when the customer is on the checkout page.
- **`.merchant`** - This method can be used without the customer being on the checkout page, and the merchant can initiate transactions (e.g. take payments for recurring transactions). This method is saved as the new default payment method for merchant initiated transactions, regardless of the number of saved payment methods stored against the customer.
_For more information, see: [Charge a customer's saved payment method](/docs/guides/merchant/optimise-checkout/save-payment-methods/charge-saved-payment-method)_ | `UserType` | No |
| `completion` | A closure that is called when the payment flow is complete. It returns a [`PaymentResult`](#revolutmerchantcardformkitpaymentresult-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 |
### `RevolutMerchantCardFormKit.Address` object
The `RevolutMerchantCardFormKit.Address` object represents an address used for billing or shipping purposes. Providing accurate address information can help reduce the likelihood of transaction declines and improve overall payment success rates.
```swift
RevolutMerchantCardFormKit.Address(
country: String,
region: String? = nil,
city: String? = nil,
streetLine1: String? = nil,
streetLine2: String? = nil,
postcode: String? = nil
)
```
| Parameter | Description | Format | Required |
| ------------- | --------------------------------------------------------------------------- | ------ | -------- |
| `country` | The 2-letter country code of the country associated with the address. | String | Yes |
| `region` | The region or state within the country. | String | No |
| `city` | The city or locality of the address. | String | No |
| `streetLine1` | The primary street address line. | String | No |
| `streetLine2` | The second line of the street address, such as a floor or apartment number. | String | No |
| `postcode` | The postcode of the address. | String | No |
## Results
### `RevolutMerchantCardFormKit.PaymentResult` enumeration
This enum represents the final outcome of a payment flow and is returned in the completion closure.
```swift
RevolutMerchantCardFormKit.PaymentResult(
case .success
case .failure(PaymentError)
case .userAbandonedPayment
)
```
| Case | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `.success` | The payment was successful. |
| `.failure(PaymentError)` | The payment failed with an associated [PaymentError](#revolutmerchantcardformkitpaymenterror-enumeration). |
| `.userAbandonedPayment` | The user dismissed or abandoned the payment flow. |
## Errors
### `RevolutMerchantCardFormKit.PaymentError` enumeration
The `PaymentError` enumeration defines a set of error types that can occur during the payment process, returned by the `.failure` case of the `completion` closure. These errors provide detailed information about what went wrong, and help developers handle various failure scenarios appropriately. The `PaymentError` enum conforms to the `Error` and `Equatable` protocols, allowing it to be used in error handling and comparison operations.
```swift
RevolutMerchantCardFormKit.PaymentError(
case failed(FailureReasonError),
case declined(FailureReasonError),
case orderNotFound,
case orderNotAvailable,
case internalError,
case timeout,
case invalidInput(Set)
)
```
| Case | Description |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `failed(FailureReasonError)` | Indicates that the payment process failed due to a specific reason encapsulated in `FailureReasonError`. This is a catch-all for errors that do not fit into more specific categories. |
| `declined(FailureReasonError)` | The payment was declined by the issuer or payment gateway, with a reason provided by `FailureReasonError`. This typically occurs due to issues identified by the payment processor. |
| `orderNotFound` | The specified order could not be found. This error usually occurs when an invalid or expired order `token` is provided. Ensure that the correct order `token` is being used. |
| `orderNotAvailable` | The order is currently not available for processing, possibly due to changes in its status or other restrictions. |
| `internalError` | An unspecified internal error occurred within the SDK or payment system. This might require further investigation if encountered frequently. |
| `timeout` | The payment process timed out, typically due to network issues or unresponsive services. Retrying the operation or checking the network connection might resolve this issue. |
| `invalidInput(Set)` | One or more input parameters are invalid, as described by a set of `InputValidationError` values. This requires validation and correction of the input data before retrying the payment process. |
### `RevolutMerchantCardFormKit.PaymentError.FailureReasonError` enumeration
The `FailureReasonError` enumeration provides specific reasons for failed or declined payments. It offers detailed insights into why a payment might have been declined or failed, allowing developers to implement precise error handling and inform users accordingly. This enum conforms to the `Error` and `Equatable` protocols, enabling effective error management and comparison.
```swift
RevolutMerchantCardFormKit.PaymentError.FailureReasonError(
case highRisk
case unknownCard
case pickupCard
case invalidCard
case expiredCard
case doNotHonour
case invalidEmail
case invalidAmount
case restrictedCard
case insufficientFunds
case rejectedByCustomer
case cardholderNameMissing
case withdrawalLimitExceeded
case threeDSChallengeFailed
case threeDSChallengeAbandoned
case threeDSChallengeFailedManually
case transactionNotAllowedForCardholder
case issuerNotAvailable
case invalidExpiry
case invalidCVV
case invalidPin
case invalidPhone
case invalidAddress
case invalidCountry
case invalidMerchant
case customerChallengeFailed
case customerNameMismatch
case technicalError
case unknown
)
```
:::info
For more information about the error cases, see: [Decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons).
:::
### `RevolutMerchantCardFormKit.PaymentError.InputValidationError` enumeration
The `InputValidationError` enumeration specifies the types of input errors that can occur when validating payment information. These errors help developers identify specific issues with user input and provide feedback or corrective actions to ensure data integrity and successful transaction processing. The enum conforms to the `Error` and `Equatable` protocols, making it suitable for error handling and comparisons.
```swift
RevolutMerchantCardFormKit.PaymentError.InputValidationError(
case invalidCardholderName
case invalidExpirationDate
case invalidCardNumber
case invalidCVV
case invalidEmail
)
```
:::info
For more information about the error cases, see: [Decline reasons](/docs/guides/merchant/reference/error-codes/decline-reasons).
:::