Документація

Документація

  • EN
  • UK

›Documentation

Документація

  • Payment Gateway
  • PortmoneDirect
  • Google Pay
  • Apple Pay
  • Structured Link
  • iOS E-com SDK
  • Android E-com SDK
  • Masterpass iOS SDK
  • Masterpass Android SDK
  • H2H JSON ASYNC для PCI DSS
  • Visa/Masterpass Products

Documentation

  • Payment Gateway
  • PortmoneDirect
  • Google Pay
  • Apple Pay
  • Structured Link
  • iOS E-com SDK
  • Android E-com SDK
  • Masterpass iOS SDK
  • Masterpass Android SDK
  • H2H JSON ASYNC for PCI DSS
  • Visa/Masterpass Products

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

FieldTypeDescriptionNullability
clientIdStringA unique identifier of the client in the Masterpass system.required
merchantKeyStringUnique 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.

Authorization

AuthorizationService

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

authorize method parameters

ParameterTypeDescriptionExample
phoneNumberStringUser mobile phone number. Used as an identifier in the Masterpass wallet.“380666789555”
userIdStringUser ID in the Portmone system. Required for identification in the Portmone system.“3715100”
completionOperationCompletionAsynchronous callback with the result of authorization.

Getting authorization result:

OperationCompletion

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

OperationCompletion parameters

ParametersDescription
BoolAuthorization 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.

Adding a card

addMasterpassCard method parameters

ParameterTypeDescriptionExample
cardMfsCardThe 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
cardNumberMfsTextFieldThe card number filled in the MfsTextField object.See below
cvvMfsTextFieldCVV code filled in the MfsTextField object.See below
completionOperationCompletionAsynchronous 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

ParametersDescription
BoolResult 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.

Getting the cards list

MasterpassCardsCompletion

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

MasterpassCardsCompletion parameters

ParametersDescription
[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

FieldTypeDescriptionNullability
cardBinStringMasked card number in 444433********11 format.required
nameStringUnique 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.

Deleting a card

deleteMasterpassCard method parameters

ParameterTypeDescriptionExample
cardNameStringCard name in the Masterpass system. It can be obtained from the name property of the MasterpassCard object“MyCard”
completionOperationCompletionAsynchronous callback with the result of deleting a card

OperationCompletion

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

OperationCompletion parameters

ParametersDescription
BoolResult 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

ParameterTypeDescription
codeMfsTextFieldThe MfsTextField object with a filled in code for validation.
completionOperationCompletionAsynchronous 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

ParametersDescription
BoolValidation 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

ParameterTypeDescriptionExample
completionPayeesCompletionAsynchronous callback with the result of receiving companies.

PayeesCompletion

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

MasterpassCardsCompletion method parameters

ParameterDescription
[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

FieldTypeDescriptionNullability
payeeIdStringUnique identifier of a company.required
nameStringCompany name.required
contractNumberTitlePayeeLocalizedTitleName of the account number. Contains translations into 3 languages by keys:
“uk ” = Ukrainian,
“en” = English,
“ru” = Russian.
required
contractNumberTypeStringData type for the account number. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
required
contractNumberSizeStringMaximum field size.optional
attribute1TitlePayeeLocalizedTitleAttribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.optional
attribute1TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
optional
attribute1SizeStringMaximum field size.optional
attribute1ForInfobooleanIf true, the field should not be shown.optional
attribute2TitlePayeeLocalizedTitleAttribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.optional
attribute2TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
optional
attribute2SizeStringMaximum field size.optional
attribute2ForInfobooleanIf true, the field should not be shown.optional
attribute3TitlePayeeLocalizedTitleAttribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.optional
attribute3TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
optional
attribute3SizeStringMaximum field size.optional
attribute3ForInfobooleanIf true, the field should not be shown.optional
attribute4TitlePayeeLocalizedTitleAttribute name. Contains translations into 3 languages by keys: “uk ” = Ukrainian, “en” = English, “ru” = Russian.optional
attribute4TypeStringData type for the attribute. Possible values:
“N” - numeric,
“C” - character,
“D” - date in "dd.MM.yyyy" format.
optional
attribute4SizeStringMaximum field size.optional
attribute4ForInfobooleanIf true, the field should not be shown.optional
imageUrlStringURL with the image for this company.optional
needRedirectbooleanDetermines if a user should be redirected to the site to pay to this company.required
gatewayPayeeLocalizedTitleURL 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.

Payment

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

FieldTypeDescription
payeeIdStringID of the company in the Portmone system.
cardMasterpassCardMasterpass card object received using CardsService.
billAmountDoubleAmount of the payment.
commissionDoubleCommission for the current payment.
billBillObject with payment information. Filled in after successful payment completion.

Bill object

FieldTypeDescriptionNullability
billIdStringUnique payment ID.optional
recieptUrlStringLink to get a pdf receipt.optional
contractNumberStringPersonal account number.optional
payDateDateTime 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

ParameterTypeDescription
commissionParamsCommissionParamsA set of parameters required for getting the commission.
payeeIdStringID of the company, to which payment is made, in the Portmone system.
completionPayeePaymentCompletionAsynchronous callback with the result of getting the commission.

CommissionParams object

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object received using CardService.required
billAmountDoubleAmount of the payment. Should be not less than 0.required
merchantLoginStringLogin to pay to this company.required
billNumberStringUnique generated account number.required

PayeePaymentCompletion

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

PayeePaymentCompletion parameters

ParametersDescription
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

ParameterTypeDescription
transactionPayeePaymentTransactionThe transaction object received from PayeePaymentCompletion.
paymentParamsPayeeParamsObject with a set of parameters required for the payment.

PaymentParams object

FieldTypeDescriptionNullability
contractNumberStringPersonal account number (*)required
attribute1StringPayment attribute 1. (*)optional
attribute2StringPayment attribute 2. (*)optional
attribute3StringPayment attribute 3. (*)optional
attribute4StringPayment attribute 4. (*)optional
emailStringE-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

MethodParametersDescription
didFinishPaymentPayeePaymentTransactionCalled in case of successful payment. The transaction is filled with the Bill object.
paymentIsWaitingFor2dVerificationPayeePaymentTransactionCalled when 2d verification of the card is needed.
paymentIsWaitingFor3dVerificationPortmoneWebViewCalled when 3d verification of the card is needed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
paymentIsFinishedFor3dVerificationPortmoneWebViewCalled after 3d verification of the card is completed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
didFinishPaymentError?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.

2d Verification of a card

startVerify2dCard method parameters

ParameterTypeDescription
transactionPayeePaymentTransactionTransaction object received from delegate’s paymentIsWaitingFor2dVerification method.
cvv2StringCVV code of the card for which verification is required.

PayeePaymentDelegate

func verificationIsWaitingForFinish(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate mehtods

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

finishVerify2dCard method parameters

ParameterTypeDescription
transactionPayeePaymentTransactionTransaction object received from delegate’s verificationIsWaitingForFinish method.
verificationCodeStringVerification code received in SMS.

PayeePaymentDelegate

func didFinishPayment(transaction: PayeePaymentTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

MethodParametersDescription
didFinishPaymentPayeePaymentTransactionCalled in case the verification and the payment were successfully completed.
didFinishPaymentError?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.

3d  Verification of a card

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

MethodParametersDescription
paymentIsFinishedFor3dVerificationPortmoneWebViewCalled regardless of the verification result to hide webView from the screen.
didFinishPaymentPayeePaymentTransactionCalled in case the verification and the payment were successfully completed.
didFinishPaymentError?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.

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

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object received using CardsService.required
billAmountDoubleAmount of the payment.required
phoneNumberStringPhone number to which funds are transferred.required
commissionDoubleCommission for the current payment.required
payeeIdStringID of the company in the Portmone system.required
billBuillObject with payment information. Filled in after the payment is successfully completed.optional

Bill object

FieldTypeDescriptionNullability
billIdStringUnique payment ID.optional
recieptUrlStringLink to get a pdf receipt.optional
contractNumberStringPersonal account number.optional
payDatelongTime 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

ParameterTypeDescription
commissionParamsCommissionParamsA set of parameters required for getting the commission.
phoneNumberStringPhone number to which funds are transferred.
completionTopUpCompletionAsynchronous callback with the result of getting the commission.

CommissionParams object

FieldTypeDescriptionNullability
cardMasterpassCardMasterpass card object received using CardsService.required
billAmountDoubleAmount of the payment. Should be not less than 0.required
merchantLoginStringLogin to pay for this company.required
billNumberStringUnique generated account number.required

PayeePaymentCompletion

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

PayeePaymentCompletion parameters

ParametersDescription
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

ParameterTypeDescription
transactionTopUpMobileTransactionThe transaction object received from TopUpCompletion.
paymentParamsPayeeParamsObject with a set of parameters required for payment.

PaymentParams object

FieldTypeDescriptionNullability
contractNumberStringPersonal account number (*)required
attribute1StringPayment attribute 1. (*)optional
attribute2StringPayment attribute 2. (*)optional
attribute3StringPayment attribute 3. (*)optional
attribute4StringPayment attribute 4. (*)optional
emailStringE-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

MethodParametersDescription
didFinishPaymentTopUpMobileTransactionCalled in case of successful payment. The transaction is filled with the Bill object.
paymentIsWaitingFor2dVerificationTopUpMobileTransactionCalled when 2d verification of the card is needed.
paymentIsWaitingFor3dVerificationPortmoneWebViewCalled when 3d verification of the card is needed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
paymentIsFinishedFor3dVerificationPortmoneWebViewCalled after 3d verification of the card is completed. It takes PortmoneWebView (UIView subclass with integrated WebView) as an argument.
didFinishPaymentError?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.

2d Verification of a card

startVerify2dCard method parameters

ParameterTypeDescription
transactionTopUpMobileTransactionTransaction object received from delegate’s paymentIsWaitingFor2dVerification method.
cvv2StringCVV code of the card for which verification is required.

PayeePaymentDelegate

func verificationIsWaitingForFinish(transaction: TopUpMobileTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

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

finishVerify2dCard method parameters

ParametersTypeDescription
transactionTopUpMobileTransactionTransaction object received from delegate’s verificationIsWaitingForFinish method.
verificationCodeStringVerification code received in SMS.

PayeePaymentDelegate

func didFinishPayment(transaction: TopUpMobileTransaction)

func didFinishPayment(with error: Error?)

PayeePaymentDelegate methods

MethodParametersDescription
didFinishPaymentTopUpMobileTransactionCalled in case the verification and the payment were successfully completed.
didFinishPaymentError?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.

3d Verification of a card

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

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

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

Masterpass errors

CodeDescription
2100Internal Error
2101Connection Error
2102Card Number is empty
2103Card Number is invalid
2104CVV/CVC2 is empty
2105CVV/CVC2 is invalid
2106Card Name is empty
2107Validation Code is empty
2108Validation Code is invalid
21093D URL is empty
21103D Secure is not validated
2111Terms & Condition checkbox is not selected
2112Expire Year is invalid
2113OTP sending card's Bank is required.
2114MasterPass OTP is required for phone number validation.
2200*Masterpass service server error.
← Android E-com SDKMasterpass Android SDK →
  • IOS integration
  • Opportunities provided by Portmone SDK
  • Before getting started
    • Sign up at Masterpass™
    • Sign up at Portmone.com
  • 1. Get started with the SDK
  • 2. Authorization (AuthorizationService)
  • 3. Masterpass wallet (CardService)
    • 3.1 Adding a card (addMasterpassCard)
    • 3.2 Getting the cards list (getMasterpassCards)
    • 3.3 Deleting a card (deleteMasterpassCard)
  • 4. OTP verification (validateCode)
  • 5. Getting companies (PayeeService)
  • 6. Payment (PayeePaymentService)
    • 6.1 Getting a commission (getCommission)
    • 6.2 Making a payment (proceedPayment)
    • 6.3 2d Verification of a card (startVerify2dCard, finishVerify2dCard)
    • 6.4 3d Verification of a card (PortmoneWebView)
  • 7. Adding funds to a mobile phone account (TopUpMobileService)
    • 7.1 Getting a commission (getCommission)
    • 7.2 Making a payment (proceedPayment)
    • 7.3 2d Verification of a card (startVerify2dCard, finishVerify2dCard)
    • 7.4 3d Verification of a card (PortmoneWebView)
  • 8. List of possible errors
Copyright © 2022 Portmone.com