Payment process diagram

Requirements

TranzzoPaymentSDK is written in Swift 5+. iOS 13.0+ Required

Install

With Cocoapods

pod 'TranzzoPaymentSDK', :git => 'https://github.com/tranzzo/mobile-sdk-ios.git'

While using TranzzoPaymentSDK, don’t forget:

import TranzzoPaymentSDK

SDK configuration

Init the TranzzoPaymentSDK library in the AppDelegate. For example:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.

    TranzzoPaymentSDK.setConfig(paymentConfig: PaymentsConfig(environment: .sandbox, currency: "currency", enableLogging: true))
    
    return true
}

Supported server Environment:

public enum Environment {
    case sandbox
    case production
}

Pay attentsion.

currency should be in format ISO 4217

Apple Pay Integration

1. Setting Up Apple Pay according guide
2. Pass ApplePayConfig into PaymentsConfig (by default ApplePayConfig is nil)

    TranzzoPaymentSDK.setConfig(paymentConfig: PaymentsConfig(environment: .sandbox, currency: "your_currency", applePay: ApplePayConfig(merchantId: "yout_merchat_id", countryCode: "country_code")))

Pay attentsion.

coutryCode should be in format ISO 3166-1 alpha-2

Customization

You can easily customize the payment screen color scheme/localization/showing apple pay button/ showing card form. Just implement PaymentContollerConfig and pass into makePayment method

var colorConfig = ColorConfig()
colorConfig.pay_button_enable_color = .blue
colorConfig.pay_button_disabled_color = .purple
colorConfig.fixed_amount_color = .blue
colorConfig.background_color = .white
colorConfig.section_backround_color = .cyan
colorConfig.border_color = .lightGray
colorConfig.placeholder_color = .darkGray
colorConfig.title_color = .darkGray
colorConfig.input_color = .black
colorConfig.error_color = .red

var localizationConfig = LocalizationConfig()
localizationConfig.main_title = "main_title"
localizationConfig.lookup_pay_button_title = "lookup_pay_button_title"
localizationConfig.enter_amount_title = "enter_amount_title"
localizationConfig.enter_amount_placeholder = "enter_amount_placeholder"
localizationConfig.pay_via_card_title = "pay_via_card_title"
localizationConfig.pay_button_title = "pay_button_title"
localizationConfig.wrong_card_data_title = "wrong_card_data_title"
localizationConfig.card_number_placeholder = "card_number_placeholder"
localizationConfig.card_exp_month_placeholder = "card_exp_month_placeholder"
localizationConfig.card_exp_year_plaecholder = "card_exp_year_plaecholder"
localizationConfig.card_cvv_placeholder = "card_cvv_placeholder"
localizationConfig.cancel_payment_title = "cancel_payment_title"
localizationConfig.cancel_payment_description = "cancel_payment_description"
localizationConfig.cancel_payment_confirm = "cancel_payment_confirm"
localizationConfig.cancel_payment_cancel = "cancel_payment_cancel"

PaymentContollerConfig(colorConfig: colorConfig, localizationConfig: localizationConfig, showApplePayForm: true, showCreditCardForm: false)

Pay attentsion.

Ukrainian language is default localization

Prepare payment data for sending:

a) Create PaymentType object that contains all necessary information about payment amount type.

• In case user should have the fixed amount for payment you need to create the next object:

let paymentType = FixedAmountPaymentType(orderId: "your_order_id",
                                         amount: 0.15,
                                         description: "your_order_description",
                                         tokenCards: [
                                            TokenCardModel(mask: "card_mask", 
                                                           token: "card_token",
                                                           isDefault: true)
                                                           ],
                                        method: .purchase,
                                        payment3dsBypass: .supported)

method - payment method according with your business. Supported types:

  public enum PaymentMethodType: String, Codable {
      case auth // two-step payment. Amount is simply hold on payer's card. For actual charging, complete the transaction with capture method.
      case purchase // one-step payment. Charges customer's card for specified amount (used by default)
  }

payment3dsBypass - 3DS bypass support. Supported types:

  public enum Payment3dsBypassType: String, Codable {
      case supported
      case always
      case never
  }

description is the text will be displayed to user on the payment screen. Please, provide a readable product description. tokenCards - array of already tokenized cards (TokenCardModel), nil by default

The UI example with fixed amount, product description and empty tokenCards:

The UI example with fixed amount, product description and tokenCards:

• In case user can change the amount of payment by themself you need to create the next object:

let paymentType = AnyAmountPaymentType(orderId: UUID().uuidString,
                                       description: "Test product",
                                       proposedAmounts: [9.99, 14.99, 29.99], // Decimal array
                                       tokenCards: [
                                            TokenCardModel(mask: "card_mask", 
                                                           token: "card_token",
                                                           isDefault: true)
                                                           ],
                                        method: .purchase,
                                        payment3dsBypass: .supported)

method - payment method according with your business. Supported types:

  public enum PaymentMethodType: String, Codable {
      case auth // two-step payment. Amount is simply hold on payer's card. For actual charging, complete the transaction with capture method.
      case purchase // one-step payment. Charges customer's card for specified amount (used by default)
  }

payment3dsBypass - 3DS bypass support. Supported types:

  public enum Payment3dsBypassType: String, Codable {
      case supported
      case always
      case never
  }

proposedAmounts - array of already predefined amount values, nil by default description - text will be displayed to user on the payment screen. Please, provide a readable product description. tokenCards - array of already tokenized cards (TokenCardModel), nil by default

The UI example with free to change amount, description, empty proposedAmounts, empty tokenCards.

The UI example with free to change amount, proposedAmounts,product description and empty tokenCards:

The UI example with free to change amount, proposedAmounts,product description and tokenCards:

• In case verify payment cards using your own payment page you need to create the next object:

let paymentType = LookupPaymentType(orderId: UUID().uuidString,
                                    description: "Test product",
                                    method: .purchase,
                                    payment3dsBypass: .supported)

method - payment method. Supported types:

  public enum LookupMethodType: String, Codable {
    case lookup
  }

payment3dsBypass - 3DS bypass support. Supported types:

  public enum Payment3dsBypassType: String, Codable {
      case supported
      case always
      case never
  }

description - text will be displayed to user on the payment screen. Please, provide a readable product description.

The UI example with product description:

b) Create KeyConfig object:

let keyConfig = KeyConfig(sessionToken: "your_session_token",
                        apiKey: "your_api_key",
                        posId: "your_pos_id")

c) Create CustomerData object that contains all your necessary data:

let customerData = CustomerData(customerEmail: "customerEmail", // required
                                customerPhone: "customerPhone", // required
                                customerId: "customerId", // optinal
                                customerFname: "customerFname", // optinal
                                customerLname: "customerLname", // optinal
                                customerLang: "customerLang", // optinal
                                customerCountry: "customerCountry" // optional 
                                )

customerLang supported values: "EN", "RU", "ES", "PL", "AR", "AZ", "BG", "CS", "DA", "DE", "EL", "FA", "FI", "FR", "HE", "HI", "HR", "HU", "IT", "JA", "KO", "NL", "NO", "PT", "PT_BR", "RO", "SK", "SL", "SR", "Ї", "SV", "TH", "TR", "UK", "ZH", "ZH_HA"

d) Create AdditionalData object that contains all additional information.

let additionalData = AdditionalData(serverUrl: nil,
                                    products: nil,
                                    merchantMcc: nil,
                                    payload: nil)

serverUrl - callback url on your server
products - array of products that are being paid for. All supported fields you find on our help centre
merchantMcc - MCC for this transaction.
payload - custom string data. Max 4000 symbols.

All field can be nill.

Make a request for payment processing

func someFunc() {
    TranzzoPaymentSDK.makePayment(rootController: self,
                                  delegate: self,
                                  paymentData: PaymentData(type: paymentType,
                                                           keyConfig: keyConfig,
                                                           customerData: customerData,
                                                           additionalData: additionalData),
                                  uiConfig: PaymentContollerConfig(colorConfig: colorConfig,
                                                                   localizationConfig: localizationConfig,
                                                                   showApplePayForm: true,
                                                                   showCreditCardForm: false)
   )
}

rootController - UIViewController for displaying PaymentController

delegate - delegate

paymentData - object that contains PaymentType, KeyConfig, CustomerData and AdditionalData

uiConfig - object that contains PaymentContollerConfig

Handling payment status

func paymentSuccess(_ results: PaymentInfoResponse)

Method fire when Payment was successfully. Return PaymentInfoResponse object that contains all information about payment

PaymentStatus

public enum PaymentStatus: String, Codable {
    case pending
    case failure
    case success
}

SUCCESS

This status indicates that the transaction has been processed successfully.

FAILURE

This status indicates that the transaction has been rejected. The reasons for this may include specific errors at any stage of the payment process, such as incorrect payment data, activation of limits and checks, insufficient funds, and so on.

PENDING

This status is applicable to all types of transactions and indicates that the transaction is being processed by the bank or payment system. The SDK checks this status on its own and re-requests the status until it receives SUCCESS or FAILURE. But if the status does not change within 60 seconds, the client receives the PENDING status.

func paymentFailed(_ error: TranzzoError)

Method fire when Payment was failed. Return TranzzoError object that contains short info about error

func paymentCanceled()

Method fire when user canceled Payment on any processing step