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:
- Go to https://developer.mastercard.com/account/sign-up
- Complete the registration form and then go through the e-mail confirmation procedure
- 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 |
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 |
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. |