iOS Merchant SDK

 The Payment SDK is a library that simplifies interaction with the Freedom Pay API. Supports iOS 15 and above.

Table of Contents

dependencies: [
    .package(url: "https://github.com/freedompay-global/merchant-sdk-ios.git", from: "1.0.0")
]

targets: [
    .target(
        name: "YourTarget",
        dependencies: ["FreedomPaymentSdk"]
    )
]

import FreedomPaymentSdk

let merchantId = "123456"
let secretKey = "123456789ABCDEF"
let region = Region.kz
let freedomApi = FreedomAPI.create(merchantId: merchantId, secretKey: secretKey, region: region)

let paymentView = PaymentView()
freedomApi.setPaymentView(paymentView)

paymentView.onLoadingStateChanged { isLoading in
    // Handle loading state changes (e.g., show/hide a progress indicator)
}

public struct SdkConfiguration(
    public init(
        userConfiguration: UserConfiguration = UserConfiguration(),
        operationalConfiguration: OperationalConfiguration = OperationalConfiguration()
    ) {
        self.userConfiguration = userConfiguration
        self.operationalConfiguration = operationalConfiguration
    }
)

let userConfig = UserConfiguration(userPhone: "+123123123123", userEmail: "test@test.test")
let operationalConfig = OperationalConfiguration(
    testingMode: true,
    language: .RU,
    autoClearing: false,
    checkUrl: "https://test.check.url/",
    resultUrl: "https://test.result.url/"
)
let sdkConfiguration = SdkConfiguration(
    userConfiguration: userConfig,
    operationalConfiguration: operationalConfig)
freedomApi.setConfiguration(sdkConfiguration)

 These methods accept several parameters to define the payment details:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

val paymentRequest = StandardPaymentRequest(
    amount: 123.45,
    currency: Currency.KZT, // Using the provided Currency enum
    description: "Monthly Subscription",
    userId: "user12345",
    orderId: "SUB-2025-001",
)

freedomApi.createPaymentPage(paymentRequest: paymentRequest) { (result: FreedomResult<PaymentResponse>) in
    switch (result) {
        case .success:
            // Payment page processed successfully.
        case .error:
            // An error occurred during the payment process.
        }
    }
}

Get Payment status

 To retrieve the current status of a previously initiated payment, use the getPaymentStatus method.

 This method takes these parameters:

 The process returns an FreedomResult<Status> object, which can be either:

• success: Contains a Status object.
• error: Specifies the type of error that occurred.

freedomApi.getPaymentStatus(Int64(123456), includeLastTransactionInfo: true) { (result: FreedomResult<Status>) in
    switch result {
    case .success:
        // Payment status retrieved successfully.
    case .error:
        // Failed to retrieve payment status.
    }
}

Make Clearing Payment

 Use the makeClearingPayment method to explicitly initiate the clearing (final capture) of funds for a previously authorized payment. This method gives you the flexibility to clear an amount that may be different from the original amount specified when the payment was created (e.g., for partial captures).

 This method takes these parameters:

 The process returns an FreedomResult<ClearingStatus> object, which can be either:

• Success: Contains a ClearingStatus object.
• Error: Specifies the type of error that occurred.

freedomApi.makeClearingPayment(Int64(123456)) { (result: FreedomResult<ClearingStatus>) in
    switch result {
    case .success:
        // Handle the clearing status.
    case .error:
        // Failed to clear the payment.
    }
}

Make Cancel Payment

 Use the makeCancelPayment method to reverse an authorized payment, effectively unblocking the amount on the customer's card. This ensures that the funds will not be charged.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

freedomApi.makeCancelPayment(Int64(123456)) { (result: FreedomResult<PaymentResponse>) in
    switch result {
    case .success:
        // Cancellation attempt completed successfully.
    case .error:
        // Failed to cancel the payment.
    }
}

Make Revoke Payment

 The makeRevokePayment method allows you to process a full or partial refund for a completed payment.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

freedomApi.makeRevokePayment(Int64(123456)) { (result: FreedomResult<PaymentResponse>) in
    switch result {
    case .success:
        // Refund process completed successfully.
    case .error:
        // Failed to process the refund.
    }
}

Add New Card

 The addNewCard method facilitates the secure tokenization and addition of a new payment card to a customer's profile. This process allows future payments to be made without requiring the customer to re-enter their card details.

WARNING
This method requires that a PaymentView has been set using freedomApi.setPaymentView() prior to calling it, as it will display a web-based form within the PaymentView for the customer to securely enter their card details.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

freedomApi.addNewCard(
    userId: "user12345",
    orderId: "CARDADD-SESSION-XYZ" // Optional tracking ID
) { (result: Freedomresult<PaymentResponse) in
    switch result {
        case .success:
            // Card addition process completed successfully.
        case .error:
    }
}

Get Added Cards

 The getAddedCards method allows you to retrieve a array of payment cards that have been previously added and tokenized for a specific user.

 This method takes these parameters:

 The process returns an FreedomResult<[Card]> object, which can be either:

• success: Contains an array of Card objects.
• error: Specifies the type of error that occurred.

freedomApi.getAddedCards("user12345") { (result: FreedomResult<[Card]>) in
    switch result {
    case .success:
        // List of added cards retrieved successfully.
    case .error:
        // Failed to retrieve added cards.
    }
}

Remove Added Card

 removeAddedCard method allows you to securely remove a previously tokenized payment card associated with a specific user.

 This method takes these parameters:

 The process returns an FreedomResult<RemovedCard> object, which can be either:

• success: Contains a RemovedCard object.
• error: Specifies the type of error that occurred.

freedomApi.removeAddedCard(
    userId: "user12345",
    cardToken: "card-token-123abc"
) { (result: FreedomResult<RemovedCard) in
    switch result {
    case .success:
        // Card removal process completed successfully.
    case .error:
        // Failed to remove the card.
    }
}

Create Card Payment

 The createCardPayment method is used to initiate a payment using a previously tokenized (saved) card.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

let paymentRequest = TokenizedPaymentRequest(
    amount: someAmount,
    currency: Currency.KZT,
    description: "Monthly Subscription",
    cardToken: "card-token-123abc",
    userId: "user12345",
    orderId: "SUB-2025-001",
    extraParams: nil
)
freedomApi.createCardPayment(paymentRequest) { (result: FreedomResult<PaymentResponse>) in
    switch result {
        case .success:
            // Payment initiation completed successfully.
        case .error:
            // Failed to initiate payment with SDK.
    }
}

Confirm Card Payment

 The confirmCardPayment method is used to finalize a payment that was previously initiated with a saved card using createCardPayment.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

freedomApi.confirmCardPayment(123456) { (result: FreedomResult<PaymentResponse>) in
    switch result {
        case .success:
            // Card payment successfully confirmed.
        case .error:
            // Failed to confirm payment.
    }
}

Confirm Direct Payment

 The confirmDirectPayment method is used to finalize a payment that was previously initiated with a saved card using createCardPayment.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• Success: Contains a PaymentResponse object.
• Error: Specifies the type of error that occurred.

freedomApi.confirmDirectPayment(paymentId) { (result: FreedomResult<PaymentResponse>) in
    switch (result) {
        case .success:
            // Direct payment successfully confirmed.
        case .error:
            // Failed to confirm direct payment.
    }
}

Apple Pay Integration

These methods facilitate integrating Apple Pay into your application through the SDK. Our SDK's methods bridge your Apple Pay implementation with our payment gateway, handling the transaction processing.

1. Apple Developer Account Setup

Before you write any code, you must configure your Apple Developer account to handle Apple Pay transactions.

1. Log in to your Apple Developer account.

2. Navigate to Certificates, Identifiers & Profiles > Identifiers.

3. Click the "+" button to add a new identifier.

4. Select Merchant IDs and click Continue.

5. Provide a descriptive name and a unique identifier string (e.g., merchant.com.yourdomain.appname).

6. Click Register.

2. Create a Payment Processing Certificate

This certificate is used to encrypt payment data, ensuring that sensitive customer information is transmitted securely.

1. Within the Merchant ID you just created, locate the Apple Pay Payment Processing Certificate section and click Create Certificate.

2. You will be prompted to create a Certificate Signing Request (CSR) from your Mac:

   • Open Keychain Access
   • Go to Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.

3. Enter your email address and a common name for the key. Select Saved to disk and click Continue.

4. Back in the Developer portal, upload the generated CSR file.

5. Apple will then issue a payment processing certificate. Download it and add it to your Keychain.

3. Enable Apple Pay in Your App ID

You need to associate your Merchant ID with your application's App ID.

1. Go to Certificates, Identifiers & Profiles > Identifiers and select your app's App ID.

2. Under the Capabilities tab, find Apple Pay and check the box to enable it.

3. Select the Merchant ID you created earlier to link it to your app.

4. Xcode setup

1. Add the Apple Pay Capability to your Xcode Project: In your project settings, go to the Signing & Capabilities tab and click the "+" button to add the Apple Pay capability. Select the Merchant ID you created.
2. Add PassKit to your code:

import PassKit

3. Display the Apple Pay Button: Use PKPaymentButton to display the official Apple Pay button:

 override func viewDidLoad() {
    super.viewDidLoad()
    
    let applePayButton = PKPaymentButton(paymentButtonType: .plain, paymentButtonStyle: .black)
    
    applePayButton.addTarget(self, action: #selector(applePayButtonTapped), for: .touchUpInside)
    
    applePayButton.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(applePayButton)
    
    NSLayoutConstraint.activate([
        applePayButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
        applePayButton.centerYAnchor.constraint(equalTo: view.centerYAnchor),
        applePayButton.widthAnchor.constraint(equalToConstant: 200), 
        applePayButton.heightAnchor.constraint(equalToConstant: 50)  
    ])
}

@objc func applePayButtonTapped() {}

4. Create a Payment Request: When the user taps the button, create a PKPaymentRequest. This object will contain details about the payment, such as:
   • merchantIdentifier: Your Merchant ID.
   • countryCode: The two-letter country code.
   • currencyCode: The three-letter currency code.
   • supportedNetworks: The payment networks you support (e.g., Visa, Mastercard).
   • merchantCapabilities: The 3D Secure capabilities your app supports.
   • paymentSummaryItems: An array of PKPaymentSummaryItem objects that detail the cost of the items, shipping, and tax.

func createPaymentRequest() -> PKPaymentRequest {
    let paymentRequest = PKPaymentRequest()
    paymentRequest.merchantIdentifier = "merchant.com.yourdomain.appname"
    paymentRequest.countryCode = "US" 
    paymentRequest.currencyCode = "USD" 
    paymentRequest.supportedNetworks = [.visa, .masterCard]
    paymentRequest.merchantCapabilities = .threeDSecure
    let item = PKPaymentSummaryItem(label: "T-Shirt", amount: NSDecimalNumber(string: "20.00"))
    let tax = PKPaymentSummaryItem(label: "Tax", amount: NSDecimalNumber(string: "2.19"))
    let shipping = PKPaymentSummaryItem(label: "Shipping", amount: NSDecimalNumber(string: "4.99"))
    let total = PKPaymentSummaryItem(label: "Your Company Name", amount: NSDecimalNumber(string: "27.18"))
    
    paymentRequest.paymentSummaryItems = [item, tax, shipping, total]
    return paymentRequest
}

5. Present the Payment Sheet: Use a PKPaymentAuthorizationViewController to present the payment sheet to the user. Conform to PKPaymentAuthorizationViewControllerDelegate delegate to handle results.

@objc func applePayButtonTapped() {
    let paymentRequest = createPaymentRequest()
    guard let paymentVC = PKPaymentAuthorizationViewController(paymentRequest: paymentRequest) else {
        print("Error: Unable to present Apple Pay sheet.")
        return
    }
    paymentVC.delegate = self
    self.present(paymentVC, animated: true, completion: nil)
}

6. Handle the Payment Token: Upon successful authorization by the user (via Face ID, Touch ID, or passcode), the PKPaymentAuthorizationViewControllerDelegate will receive a PKPayment object containing an encrypted payment token.

extension PaymentViewController: PKPaymentAuthorizationViewControllerDelegate {
    // Called when user authorizes payment
    func paymentAuthorizationViewController(
        _ controller: PKPaymentAuthorizationViewController,
        didAuthorizePayment payment: PKPayment,
        handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
    ) {
        completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
    }
    
    // Called when Apple Pay sheet is dismissed
    func paymentAuthorizationViewControllerDidFinish(_ controller: PKPaymentAuthorizationViewController) {
        controller.dismiss(animated: true, completion: nil)
    }
}

5. Creating an Apple Pay Transaction

 The createApplePayment method is the first step in processing a payment via Apple Pay using the SDK. This method initiates a Apple Pay payment.

 This method takes these parameters:

 The process returns an FreedomResult<ApplePayment> object, which can be either:

• Success: Contains a ApplePayment object.
• Error: Specifies the type of error that occurred.

func createApplePayment() {
    let standardPaymentRequest = StandardPaymentRequest(
        amount: Decimal(10.0),
        currency: .KZT,
        description: "some description",
        userId: "123",
        orderId: "456",
        extraParams: nil)
    freedomApi.createApplePayment(
        paymentRequest: standardPaymentRequest
    ) { result in
        switch result {
        case .success(let applePayment):
            self.paymentId = applePayment.paymentId
        case .error(let error):
            print("Apple Payment failed: \(error)")
        }
    }
}

6. Confirming an Apple Pay Transaction

 The confirmApplePayment method is the final step in processing a Apple Pay transaction with the SDK. After you have successfully obtained the Apple Pay token from the PassKit (e.g., from PKPayment from PKPaymentAuthorizationController), you pass this token along with the paymentId received from createApplePayment to this method to finalize the transaction.

 This method takes these parameters:

 The process returns an FreedomResult<PaymentResponse> object, which can be either:

• .success: Contains a PaymentResponse object.
• .error: Specifies the type of error that occurred.

func paymentAuthorizationController(
    _ controller: PKPaymentAuthorizationController,
    didAuthorizePayment payment: PKPayment,
    handler completion: @escaping (PKPaymentAuthorizationResult) -> Void
) {
    freedomApi.confirmApplePayment(
        paymentId: paymentId,
        tokenData: payment.token.paymentData
    ) { result in
        switch result {
        case .success(let paymentResponse):
            print("Payment ID: \(paymentResponse.paymentId)")
            completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
        case .error(let error):
            print("Apple Payment Confirmation failed: \(error)")
            completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
        }
    }
}

Error Handling and Results

 All asynchronous operations in the SDK return their outcome encapsulated within a FreedomResult sealed interface.

 The FreedomResult interface has two primary states: success for successful completion and error for any failures.

FreedomResult.success<T>

• Represents a successful completion of the SDK operation.
• value: T: Holds the actual result of the operation. The type T will vary depending on the method called (e.g., Payment, [Card], ConfirmPaymentStatus).

FreedomResult.error

 The error type is a sealed interface itself, providing distinct types of errors for more precise handling.

1. ValidationError

 Indicates that one or more inputs provided to the SDK method were invalid or did not meet specified constraints (e.g., amount out of range, userId format mismatch).

• errors: List<ValidationErrorType>: A list detailing all specific validation errors that occurred. For a comprehensive list of types, refer to the ValidationErrorType table.

2. PaymentInitializationFailed

 Indicates a general failure during the initial setup or preparation of a payment, before it reaches the transaction processing stage.

3. Transaction

 Represents an error encountered by the payment gateway during the transaction processing (e.g., card declines, insufficient funds, 3D Secure failures).

• errorCode: Int: A numerical code representing a specific transaction error. You can find an up-to-date reference of error codes here.
• errorDescription: String?: A human-readable description of the transaction error, if available.

4. NetworkError

 Represents errors related to network connectivity or API responses. This is a sealed interface with several specific network error types:

• Protocol: Indicates an issue with the communication protocol or an unexpected response from the API.

  • code: Int: An HTTP status code or an internal protocol error code.
  • body: String?: The raw response body or a human-readable description of the protocol error, if available.

• Connectivity: Indicates problems related to the device's network connection. This sealed interface includes the following specific errors:

  • ConnectionFailed: The network connection could not be established.
  • ConnectionTimeout: The network request timed out.
  • Integrity: An issue with the integrity of the network connection (e.g., SSL/TLS certificate issues).

• Unknown: A general network error occurred that does not fall into more specific categories.

5. InfrastructureError

 Represents errors related to the internal state, configuration, or core components of the SDK. This is a sealed interface with several specific infrastructure error types:

• SdkNotConfigured: The SDK methods were called before freedomApi.setConfiguration() was successfully invoked.
• SdkCleared: The SDK methods were called after the SDK's internal state was cleared, preventing further operations.
• ParsingError: An error occurred while parsing data (e.g., a response from the server could not be deserialized).
• WebView: Errors specifically related to the internal WebView component used for displaying payment pages or frames. This sealed interface includes the following specific errors:
  • PaymentViewIsNotInitialized: A method requiring PaymentView was called, but freedomApi.setPaymentView() has not been called or the view is not ready.
  • Failed: A general error occurred during the payment process within the WebView, without a more specific cause.

Data Structures

 This section provides detailed descriptions of the structs and enums used throughout the SDK, particularly in the results of various method calls.

StandardPaymentRequest Structure

 The StandardPaymentRequest data class encapsulates the essential details required to initiate a new payment transaction.

TokenizedPaymentRequest Structure

 The TokenizedPaymentRequest data class is used to create payments with a previously saved and tokenized card, requiring the card's unique token along with standard payment details.

PaymentResponse Structure

 The PaymentResponse struct represents a successful payment transaction.

PaymentResponse.Status

switch paymentResponse.status {
case .new:
    // Payment has been created but no processing has started yet.
case .waiting:
    // Payment is pending further action or confirmation.
case .processing:
    // Payment is actively being handled by the system or provider.
case .incomplete:
    // Indicates that the payment was initiated but did not reach a final state within the allotted time.
case .success:
    // Payment was completed successfully and funds have been confirmed.
case .error(let code, let description):
    // Payment failed, with an error code
case .unknown(_):
    // Status value is not recognized by the SDK, possibly due to a new or unexpected status from the backend.
}

Status Structure

 Provides comprehensive details about the current state of a payment.

RevokedPayment Structure

 Details of an individual cancelled transaction.

RefundPayment Structure

 Details of an individual refund transaction.

LastTransactionInfo Structure

 Details of the most recent transaction associated with this payment

ClearingStatus Structure

 Represents the status of a clearing operation.

Card Structure

 Represents a single tokenized payment card associated with a user.

RemovedCard Structure

 Represents the outcome of an attempt to remove a stored card.

ValidationErrorType Structure

ApplePayment Structure

 The response received after initiating a Apple Pay transaction.

Currency Structure

 The Currency enum defines all supported currency codes that can be used when specifying payment amounts.

Support

If you have questions or need help, feel free to reach out! 👋
Email: support@freedompay.kz