Masterpass iOS SDK

IOS integration

Portmone SDK supports iOS 8.0 version and above.

Opportunities provided by Portmone SDK

Masterpass wallet:

• add cards to an existing wallet or create a new one;
• delete cards from an existing wallet;
• get a list of cards for an existing wallet.

Payment:

• adding funds to a mobile phone account using Masterpass cards;
• paying for services by personal account using Masterpass cards.

Before getting started

Sign up at Masterpass™

To get started with Masterpass™, you need to go through the merchant registration process at developers.mastercard.com. To do this:

1. Go to https://developer.mastercard.com/account/sign-up
2. Complete the registration form and then go through the e-mail confirmation procedure
3. Create project on the page https://developer.mastercard.com/dashboard → Create new project

Sign up at Portmone.com

After receiving the keys from Masterpass™, send the following information to the Portmone.com:

• the keys data from your personal account, namely:

  • Public key (Press “Actions” → “Download *.pem”)
  • Keystore password
  • Key alias

You can find these data in the Key Management section at https://developer.mastercard.com/masterpass/merchant/#/keyManagement2

• Masterpass™ Checkout ID (copy from the next page in your personal account: https://developer.mastercard.com/masterpass/merchant/#/checkoutCredentials)

You should send the information via email at [email protected] with the subject “Partner [Your company's name] Onboarding”. Please make sure that you have permanent access to the mailbox from which you will send this email and that the mailbox is registered with your company's trusted domain. Emails from free public domains (gmail.com, yahoo.com, ukr.net etc.) will be automatically filtered out.

After registering your Masterpass™ Merchant data in the Portmone.com system, you will be contacted to assist on further integration and testing steps and will be provided the following information:

• Portmone.com Merchant Id;
• Portmone.com Merchant Login;
• The current version of the SDK for the iOS and/or Android platforms along with the samples of applications that use SDK.

1. Get started with the SDK

To use the SDK methods, before you get started you need to call a method which accepts a set of required parameters to work with SDK:

PortmoneSDK(merchantKey, clientId)

Parameters

Field	Type	Description	Nullability
clientId	String	A unique identifier of the client in the Masterpass system.	required
merchantKey	String	Unique key.	required

2. Authorization (AuthorizationService)

To use SDK features you should log in to the system. AuthorizationService, which is publicly available, and its authorize method are used for authorization. Authorization for one user is stored during the life of the application after calling the method. To change the user you need to call this method again with other parameters.

During the method call, the wallet status is checked using the specified phone number. If necessary, the client is automatically linked to the Masterpass system. In this case, card verification with the OTP code is necessary and error 2113 appears.

AuthorizationService

public func authorize(phone: String,
                      userId: String,
                      completion: @escaping OperationCompletion)

authorize method parameters

Parameter	Type	Description	Example
phoneNumber	String	User mobile phone number. Used as an identifier in the Masterpass wallet.	“380666789555”
userId	String	User ID in the Portmone system. Required for identification in the Portmone system.	“3715100”
completion	OperationCompletion	Asynchronous callback with the result of authorization.

Getting authorization result:

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

OperationCompletion parameters

Parameters	Description
Bool	Authorization result: true - successful, false - unsuccessful.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error object. When checking the status of a wallet, an error 2113 may occurs, which requires OTP verification of the card.

Example:

let service = AuthorizationService()
service.authorize(phone: "380666789555",
                  userId:"3714123") { [weak self] isSuccess, error in
            if error != nil {
                let code = (error as NSError?)?.code
                switch code {
                case 2113?:
                    self?.performSegue(withIdentifier: self?.confirmCardSegue ?? "", 
sender: self)

                default:
                    self?.presentAlert(title: "Error \(code ?? 0)",
                                       message: error?.localizedDescription)
                }
            } else {
                self?.presentAlert(title: "Success",
                                   message: "Authorization success.") { _ in
                    self?.performSegue(withIdentifier: "Functionality", sender: nil)
                }
            }
        }

3. Masterpass wallet (CardService)

The CardService is used to work with the wallet. It provides possibility to add or remove cards and get a list of cards in the existing wallet.

CardService

public func getMasterpassCards(completion: @escaping MasterpassCardsCompletion)

public func addMasterpassCard(card: MfsCard,
                              cardNumber: MfsTextField,
                              cvv: MfsTextField,
                              completion: @escaping OperationCompletion)

public func deleteMasterpassCard(cardName: String,
                                 completion: @escaping OperationCompletion)

3.1 Adding a card (addMasterpassCard)

The method adds a card to an existing Masterpass wallet using the phone number specified at authorization or creates a new one, if the existing one was not found for this number.

addMasterpassCard method parameters

Parameter	Type	Description	Example
card	MfsCard	The name of the card, the year and month of card expiration date must be filled in the MfsCard object. Card name should be URL encoded.	See below
cardNumber	MfsTextField	The card number filled in the MfsTextField object.	See below
cvv	MfsTextField	CVV code filled in the MfsTextField object.	See below
completion	OperationCompletion	Asynchronous callback for adding a card.

Example of the card parameter:

let card = MfsCard()
card.cardName = "СardName"
card.expireMonth = "03”
card.expireYear = "20"

Example of the cardNumber parameter:

cardNumber.setType(1)
cardNumber.maxLength = 20
cardNumber.placeholder = "Card No"
cardNumber.keyboardType = .numberPad
cardNumber.clear()

Example of the cvv parameter:

cvv.setType(3)
cvv.maxLength = 3
cvv.placeholder = "cvv"
cvv.keyboardType = .numberPad
cvv.clear()

Obtaining the result of adding a card:

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

OperationCompletion parameters

Parameters	Description
Bool	Result of adding a card: true - successful, false - unsuccessful.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object. When adding a card, errors 2113, 2114 may occur, which requires OTP verification of the card and phone number.

Example:

final class AddCardViewController: BaseViewController {

    private let confirmPhoneSegue = "ConfirmPhone"
    private let confirmCardSegue = "ConfirmCard"
    private let cardService = CardsService()

    @IBOutlet private weak var cardName: UITextField!
    @IBOutlet private weak var cardNumber: MfsTextField!
    @IBOutlet private weak var expireMonth: UITextField!
    @IBOutlet private weak var expireYear: UITextField!
    @IBOutlet private weak var cvv: MfsTextField!

    override func viewDidLoad() {
        super.viewDidLoad()

        cardNumber.setType(1)
        cardNumber.maxLength = 20
        cardNumber.placeholder = "Card No"
        cardNumber.keyboardType = .numberPad
        cardNumber.clear()

        cvv.setType(3)
        cvv.maxLength = 3
        cvv.placeholder = "cvv"
        cvv.keyboardType = .numberPad
        cvv.clear()
    }

    @IBAction private func addCardButtonClicked(_ sender: UIButton) {
        let card = MfsCard()
        card.cardName = cardName.text
        card.expireMonth = expireMonth.text
        card.expireYear = expireYear.text

        UIApplication.shared.isNetworkActivityIndicatorVisible = true
        cardService.addMasterpassCard(card: card,
                                      cardNumber: cardNumber,
                                      cvv: cvv) { [weak self] isSuccess, error in
            UIApplication.shared.isNetworkActivityIndicatorVisible = false
            if error != nil {
                let code = (error as NSError?)?.code
                switch code {
                case 2113?:
                    self?.performSegue(withIdentifier: self?.confirmCardSegue ?? "",
sender: self)

                case 2114?:
                    self?.performSegue(withIdentifier: self?.confirmPhoneSegue ?? "",
sender: self)

                default:
                    self?.presentAlert(title: "Error \(code ?? 0)",
                                       message: error?.localizedDescription)
                }
            } else {
                self?.presentAlert(title: "Success",
                                   message: "Add card success.") { _ in
                    self?.navigationController?.popViewController(animated: true)
                }
            }
        }
    }

    override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
        if (segue.identifier == confirmPhoneSegue) {
            if let navController = segue.destination as? UINavigationController,
                let controller = navController.viewControllers.first as?
ConfirmCodeViewController {
                controller.delegate = self
                controller.type = .phone
            }
        }

        if (segue.identifier == confirmCardSegue) {
            if let navController = segue.destination as? UINavigationController,
                let controller = navController.viewControllers.first as?
ConfirmCodeViewController {
                controller.delegate = self
                controller.type = .card
            }
        }
    }
}

3.2 Getting the cards list (getMasterpassCards)

The method provides possibility to get a list of existing cards for the wallet by the phone number specified at authorization.

MasterpassCardsCompletion

public typealias MasterpassCardsCompletion = ([MasterpassCard]?, Error?) -> Void

MasterpassCardsCompletion parameters

Parameters	Description
[MasterpassCard]?	Called after the cards are received successfully. In case of success, the method returns an array of MasterpassCard objects.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

MasterpassCard object

Field	Type	Description	Nullability
cardBin	String	Masked card number in 444433********11 format.	required
name	String	Unique card name in a Masterpass wallet.	required

Example:

let cardService = CardsService()
cardService.getMasterpassCards { cards, error in
            if cards != nil {
                self.cards = cards
                self.tableView.reloadData()
            } else {
                let code = (error as NSError?)?.code
                self.presentAlert(title: "Error \(code ?? 0)",
                                  message: error?.localizedDescription)
            }
        }

3.3 Deleting a card (deleteMasterpassCard)

This method deletes the card from the Masterpass wallet.

deleteMasterpassCard method parameters

Parameter	Type	Description	Example
cardName	String	Card name in the Masterpass system. It can be obtained from the name property of the MasterpassCard object	“MyCard”
completion	OperationCompletion	Asynchronous callback with the result of deleting a card

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

OperationCompletion parameters

Parameters	Description
Bool	Result of deleting a card: true - successful, false - unsuccessful.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

Example:

let cardService = CardsService()
cardService.deleteMasterpassCard(cardName: "SomeCardName") { isSuccess, error in
                if isSuccess {
                    self.presentAlert(title: "Success",
                                      message: cardName + " card deleted.") { _ in
                        self.cards?.remove(at: indexPath.row)
                        self.tableView.reloadData()
                    }
                } else {
                    let code = (error as NSError?)?.code
                    self.presentAlert(title: "Error \(code ?? 0)",
                                      message: error?.localizedDescription)
                }
            }

4. OTP verification (validateCode)

The method provides possibility to perform OTP validation of the phone number and bank card. Called when error codes 2113 or 2114 are received. Can be called using AuthorizationService and CardsService. After a successful validation, it may be necessary to perform an additional verification. In that case, the result may be an error stating that it's necessary to perform the verification with repeated method call.

public func validateCode(code: MfsTextField, completion: @escaping OperationCompletion)

OperationCompletion method parameters

Parameter	Type	Description
code	MfsTextField	The MfsTextField object with a filled in code for validation.
completion	OperationCompletion	Asynchronous callback with validation result.

Example of the code parameter:

confirmCode.setType(2)
confirmCode.maxLength = 6
confirmCode.placeholder = "PIN"
confirmCode.keyboardType = .numberPad
confirmCode.clear()

OperationCompletion

public typealias OperationCompletion = (Bool, Error?) -> Void

OperationCompletion parameters

Parameters	Description
Bool	Validation result: true - successful, false - unsuccessful.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object. Possible errors 2113 and 2114, which require OTP validation.

5. Getting companies (PayeeService)

The service provides possibility to get a list of companies to which a payment can be made using the SDK.

PayeeService

public func getPayees(completion: @escaping PayeesCompletion)

getPayees method parameters

Parameter	Type	Description	Example
completion	PayeesCompletion	Asynchronous callback with the result of receiving companies.

PayeesCompletion

public typealias PayeesCompletion = ([Payee]?, Error?) -> Void

MasterpassCardsCompletion method parameters

Parameter	Description
[Payee]?	If successful, the method returns an array of Payee objects.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

Payee object

Field	Type	Description	Nullability
payeeId	String	Unique identifier of a company.	required
name	String	Company name.	required
contractNumberTitle	PayeeLocalizedTitle	Name of the account number. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	required
contractNumberType	String	Data type for the account number. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	required
contractNumberSize	String	Maximum field size.	optional
attribute1Title	PayeeLocalizedTitle	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	optional
attribute1Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	optional
attribute1Size	String	Maximum field size.	optional
attribute1ForInfo	boolean	If true, the field should not be shown.	optional
attribute2Title	PayeeLocalizedTitle	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	optional
attribute2Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	optional
attribute2Size	String	Maximum field size.	optional
attribute2ForInfo	boolean	If true, the field should not be shown.	optional
attribute3Title	PayeeLocalizedTitle	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	optional
attribute3Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	optional
attribute3Size	String	Maximum field size.	optional
attribute3ForInfo	boolean	If true, the field should not be shown.	optional
attribute4Title	PayeeLocalizedTitle	Attribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	optional
attribute4Type	String	Data type for the attribute. Possible values: “N” - numeric, “C” - character, “D” - date in "dd.MM.yyyy" format.	optional
attribute4Size	String	Maximum field size.	optional
attribute4ForInfo	boolean	If true, the field should not be shown.	optional
imageUrl	String	URL with the image for this company.	optional
needRedirect	boolean	Determines if a user should be redirected to the site to pay to this company.	required
gateway	PayeeLocalizedTitle	URL to pay to this company (the URL to which a user will be redirected to make a payment on the site when the company cannot be displayed in the application). Contains options for 3 languages on the keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.	optional

Example:

let payeeService = PayeeService()
payeeService.getPayees { models, error in
            if models != nil {
                self.payees = models
                self.tableView.reloadData()
            } else {
                let code = (error as NSError?)?.code
                self.presentAlert(title: "Error \(code ?? 0)",
                                  message: error?.localizedDescription)
            }
        }

6. Payment (PayeePaymentService)

The service provides possibility to pay by companies. PayeePaymentService should be initialized with an object conformant to PayeePaymentDelegate protocol.

PayeePaymentService

public func getCommission(commissionParams: CommissionParams,
                          payeeId: String,
                          completion: @escaping PayeePaymentCompletion)

public func proceedPayment(paymentParams: PaymentParams,
                           transaction: PayeePaymentTransaction)

public func startVerify2dCard(transaction: PayeePaymentTransaction,
                              cvv2: String)

public func finishVerify2dCard(transaction: PayeePaymentTransaction,
                               verificationCode: String)

PayeePaymentTransaction object

Field	Type	Description
payeeId	String	ID of the company in the Portmone system.
card	MasterpassCard	Masterpass card object received using CardsService.
billAmount	Double	Amount of the payment.
commission	Double	Commission for the current payment.
bill	Bill	Object with payment information. Filled in after successful payment completion.

Bill object

Field	Type	Description	Nullability
billId	String	Unique payment ID.	optional
recieptUrl	String	Link to get a pdf receipt.	optional
contractNumber	String	Personal account number.	optional
payDate	Date	Time of payment in milliseconds.	optional

6.1 Getting a commission (getCommission)

The first step to make a payment is to get a commission for this payment. Successful result of getting the commission is the PayeePaymentTransaction object, which is required for further payment.

getCommission method parameters

Parameter	Type	Description
commissionParams	CommissionParams	A set of parameters required for getting the commission.
payeeId	String	ID of the company, to which payment is made, in the Portmone system.
completion	PayeePaymentCompletion	Asynchronous callback with the result of getting the commission.

CommissionParams object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object received using CardService.	required
billAmount	Double	Amount of the payment. Should be not less than 0.	required
merchantLogin	String	Login to pay to this company.	required
billNumber	String	Unique generated account number.	required

PayeePaymentCompletion

public typealias PayeePaymentCompletion = (PayeePaymentTransaction?, Error?) -> Void

PayeePaymentCompletion parameters

Parameters	Description
PayeePaymentTransaction?	Transaction object. Returned in case of successful getting the commission.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

6.2 Making a payment (proceedPayment)

This method initiates payment process. Its result will be returned to delegate.

proceedPayment mehtod parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	The transaction object received from PayeePaymentCompletion.
paymentParams	PayeeParams	Object with a set of parameters required for the payment.

PaymentParams object

Field	Type	Description	Nullability
contractNumber	String	Personal account number (*)	required
attribute1	String	Payment attribute 1. (*)	optional
attribute2	String	Payment attribute 2. (*)	optional
attribute3	String	Payment attribute 3. (*)	optional
attribute4	String	Payment attribute 4. (*)	optional
email	String	E-mail address to which a receipt will be sent.	optional

* The fields contractNumber, attribute1-4 must correspond to the fields of the Payee object and must be filled in the appropriate order.

PayeePaymentDelegate

func didFinishPayment(transaction: PayeePaymentTransaction)

func paymentIsWaitingFor2dVerification(transaction: PayeePaymentTransaction)

func paymentIsWaitingFor3dVerification(webView: PortmoneWebView)

func paymentIsFinishedFor3dVerification(webView: PortmoneWebView)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

Method	Parameters	Description
didFinishPayment	PayeePaymentTransaction	Called in case of successful payment. The transaction is filled with the Bill object.
paymentIsWaitingFor2dVerification	PayeePaymentTransaction	Called when 2d verification of the card is needed.
paymentIsWaitingFor3dVerification	PortmoneWebView	Called when 3d verification of the card is needed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
paymentIsFinishedFor3dVerification	PortmoneWebView	Called after 3d verification of the card is completed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

6.3 2d Verification of a card (startVerify2dCard, finishVerify2dCard)

2d Verification is carried out in 2 steps. At the first step, the startVerify2dCard method is called, where the card is checked and validated. After its successful completion an SMS with the verification code required for the second step is sent to the phone number associated with the card. At the second step, the finish2dVerification method is called. The payment is completed successfully after getting successful result after this step.

startVerify2dCard method parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	Transaction object received from delegate’s paymentIsWaitingFor2dVerification method.
cvv2	String	CVV code of the card for which verification is required.

PayeePaymentDelegate

func verificationIsWaitingForFinish(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate mehtods

Mehtod	Parameters	Description
verificationIsWaitingForFinish	PayeePaymentTransaction	Called in case the 2d verification was successfully started. The SMS with the verification code is sent to the mobile phone number.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

finishVerify2dCard method parameters

Parameter	Type	Description
transaction	PayeePaymentTransaction	Transaction object received from delegate’s verificationIsWaitingForFinish method.
verificationCode	String	Verification code received in SMS.

PayeePaymentDelegate

func didFinishPayment(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

Method	Parameters	Description
didFinishPayment	PayeePaymentTransaction	Called in case the verification and the payment were successfully completed.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol.

6.4 3d Verification of a card (PortmoneWebView)

Calling the paymentIsWaitingFor3dVerification method from the PayeePaymentDelegate means that 3d Verification is required for payment by this card. 3d Verification of the card is performed using PortmoneWebView.

PortmoneWebView is taken as an argument of the delegate method's call. Client app is responsible for displaying PortmoneWebView to user within its view hierarchy.

final class Confirm3DCodeViewController: BaseViewController {

    var webView: PortmoneWebView?

    override func viewDidLoad() {
        super.viewDidLoad()

    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)

        guard let webView = webView else {
            return
        }
        addViewToSelf(webView)
    }

    private func addViewToSelf(_ view: UIView) {
        view.translatesAutoresizingMaskIntoConstraints = false
        self.view.addSubview(view)

        NSLayoutConstraint.activate([view.leftAnchor.constraint(equalTo: self.view.leftAnchor),
                                     view.rightAnchor.constraint(equalTo: self.view.rightAnchor),
                                     view.topAnchor.constraint(equalTo: self.view.topAnchor),
                                     view.bottomAnchor.constraint(equalTo: self.view.bottomAnchor)])
    }

    @IBAction private func cancelButtonClicked(_ sender: UIBarButtonItem) {
        presentingViewController?.dismiss(animated: true, completion: nil)
    }
}

PayeePaymentDelegate

func paymentIsFinishedFor3dVerification(webView: PortmoneWebView)

func didFinishPayment(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

Method	Parameters	Description
paymentIsFinishedFor3dVerification	PortmoneWebView	Called regardless of the verification result to hide webView from the screen.
didFinishPayment	PayeePaymentTransaction	Called in case the verification and the payment were successfully completed.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

7. Adding funds to a mobile phone account (TopUpMobileService)

The service provides possibility to top up mobile phone account.

TopUpMobileService

public func getCommission(commissionParams: CommissionParams,
                          phoneNumber: String,
                          completion: @escaping TopUpCompletion)

public func proceedPayment(paymentParams: PaymentParams,
                           transaction: TopUpMobileTransaction)

public func startVerify2dCard(transaction: TopUpMobileTransaction,
                              cvv2: String)

public func finishVerify2dCard(transaction: TopUpMobileTransaction,
                               verificationCode: String)

TopUpMobileTransaction object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object received using CardsService.	required
billAmount	Double	Amount of the payment.	required
phoneNumber	String	Phone number to which funds are transferred.	required
commission	Double	Commission for the current payment.	required
payeeId	String	ID of the company in the Portmone system.	required
bill	Buill	Object with payment information. Filled in after the payment is successfully completed.	optional

Bill object

Field	Type	Description	Nullability
billId	String	Unique payment ID.	optional
recieptUrl	String	Link to get a pdf receipt.	optional
contractNumber	String	Personal account number.	optional
payDate	long	Time of payment in milliseconds.	optional

7.1 Getting a commission (getCommission)

The first step to make a payment is to get a commission for this payment. Successful result of getting the commission is the TopUpMobileTransaction object, which is required for further payment.

getCommission method parameters

Parameter	Type	Description
commissionParams	CommissionParams	A set of parameters required for getting the commission.
phoneNumber	String	Phone number to which funds are transferred.
completion	TopUpCompletion	Asynchronous callback with the result of getting the commission.

CommissionParams object

Field	Type	Description	Nullability
card	MasterpassCard	Masterpass card object received using CardsService.	required
billAmount	Double	Amount of the payment. Should be not less than 0.	required
merchantLogin	String	Login to pay for this company.	required
billNumber	String	Unique generated account number.	required

PayeePaymentCompletion

public typealias TopUpCompletion = (TopUpMobileTransaction?, Error?) -> Void

PayeePaymentCompletion parameters

Parameters	Description
TopUpMobileTransaction?	Transaction object. Returned in case of successful getting the commission.
Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

7.2 Making a payment (proceedPayment)

This method initiates payment process. Its result will be returned to delegate.

proceedPayment method parameters

Parameter	Type	Description
transaction	TopUpMobileTransaction	The transaction object received from TopUpCompletion.
paymentParams	PayeeParams	Object with a set of parameters required for payment.

PaymentParams object

Field	Type	Description	Nullability
contractNumber	String	Personal account number (*)	required
attribute1	String	Payment attribute 1. (*)	optional
attribute2	String	Payment attribute 2. (*)	optional
attribute3	String	Payment attribute 3. (*)	optional
attribute4	String	Payment attribute 4. (*)	optional
email	String	E-mail address to which a receipt will be sent.	optional

* The fields contractNumber, attribute1-4 must correspond to the fields of the Payee object and must be filled in the appropriate order.

PayeePaymentDelegate

func didFinishPayment(transaction: TopUpMobileTransaction)

func paymentIsWaitingFor2dVerification(transaction: TopUpMobileTransaction)

func paymentIsWaitingFor3dVerification(webView: PortmoneWebView)

func paymentIsFinishedFor3dVerification(webView: PortmoneWebView)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

Method	Parameters	Description
didFinishPayment	TopUpMobileTransaction	Called in case of successful payment. The transaction is filled with the Bill object.
paymentIsWaitingFor2dVerification	TopUpMobileTransaction	Called when 2d verification of the card is needed.
paymentIsWaitingFor3dVerification	PortmoneWebView	Called when 3d verification of the card is needed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
paymentIsFinishedFor3dVerification	PortmoneWebView	Called after 3d verification of the card is completed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

7.3 2d Verification of a card (startVerify2dCard, finishVerify2dCard)

2d Verification is carried out in 2 steps. At the first step, the startVerify2dCard method is called, where the card is checked and validated. After its successful completion an SMS with the verification code required for the second step is sent to the phone number associated with the card. At the second step, the finish2dVerificationmethod is called. The payment is completed successfully after getting a successful result after this step.

startVerify2dCard method parameters

Parameter	Type	Description
transaction	TopUpMobileTransaction	Transaction object received from delegate’s paymentIsWaitingFor2dVerification method.
cvv2	String	CVV code of the card for which verification is required.

PayeePaymentDelegate

func verificationIsWaitingForFinish(transaction: TopUpMobileTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

Method	Parameters	Description
verificationIsWaitingForFinish	TopUpMobileTransaction	Called in case the 2d verification was successfully started. The SMS with the verification code is sent to the mobile phone number.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

finishVerify2dCard method parameters

Parameters	Type	Description
transaction	TopUpMobileTransaction	Transaction object received from delegate’s verificationIsWaitingForFinish method.
verificationCode	String	Verification code received in SMS.

PayeePaymentDelegate

func didFinishPayment(transaction: TopUpMobileTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

Method	Parameters	Description
didFinishPayment	TopUpMobileTransaction	Called in case the verification and the payment were successfully completed.
didFinishPayment	Error?	Called when an error occurs during this operation. The parameter may be a system error or an Error protocol object.

7.4 3d Verification of a card (PortmoneWebView)

Calling the paymentIsWaitingFor3dVerification method from the TopUpMobileServiceDelegate means that 3d Verification is required for payment by this card. 3d verification of the card is done using PortmoneWebView.

PortmoneWebView is taken as an argument of the delegate method's call. Client app is responsible for displaying PortmoneWebView to user within its view hierarchy.

final class Confirm3DCodeViewController: BaseViewController {

    var webView: PortmoneWebView?

    override func viewDidLoad() {
        super.viewDidLoad()

    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)

        guard let webView = webView else {
            return
        }
        addViewToSelf(webView)
    }

    private func addViewToSelf(_ view: UIView) {
        view.translatesAutoresizingMaskIntoConstraints = false
        self.view.addSubview(view)

        NSLayoutConstraint.activate([
            view.leftAnchor.constraint(equalTo: self.view.leftAnchor),
            view.rightAnchor.constraint(equalTo: self.view.rightAnchor),
            view.topAnchor.constraint(equalTo: self.view.topAnchor),
            view.bottomAnchor.constraint(equalTo: self.view.bottomAnchor)])
    }

    @IBAction private func cancelButtonClicked(_ sender: UIBarButtonItem) {
        presentingViewController?.dismiss(animated: true, completion: nil)
    }
}

8. List of possible errors

SDK internal errors

Code	Description
2000	Authorization error. Please call AuthorizationService#authorize() before.
2004	Bill amount cannot be less than 0.
2005	Phone number is invalid.
2006	Phone number cannot be empty.
2007	Transaction object is not valid. Please use transaction from proceedPayment() call.
2008	Transaction object is not valid.Please use transaction from getCommission() call.
2009	Verification code cannot be empty.
2010	PayeeId cannot be empty.
2011	Contract number cannot be empty.
2012	User id cannot be empty.
2013	No gate type found for this payee. Payment cannot be proceeded!
2014	Transaction object is not valid.Please use transaction from startVerify2dCard() call.
2015	CVV cannot be empty.
2016	Initialized params cannot be empty. Please call initialize method
2017	Merchant login cannot be empty.
2018	Card verification error.

Portmone server errors are also possible, in the same format.

Masterpass errors

Code	Description
2100	Internal Error
2101	Connection Error
2102	Card Number is empty
2103	Card Number is invalid
2104	CVV/CVC2 is empty
2105	CVV/CVC2 is invalid
2106	Card Name is empty
2107	Validation Code is empty
2108	Validation Code is invalid
2109	3D URL is empty
2110	3D Secure is not validated
2111	Terms & Condition checkbox is not selected
2112	Expire Year is invalid
2113	OTP sending card's Bank is required.
2114	MasterPass OTP is required for phone number validation.
2200	*Masterpass service server error.