Skip to main content

Portmone eCommerce iOS SDK

Glossary

TermDefinition
Merchant, Online Store or PartnerOrganization which has signed a payment acceptance agreement with Portmone.com
Buyer, Client or CustomerA person who visits the Merchant's Online Store in order to learn about the range of goods (services) and to make a purchase
Card, Payment CardPayment cards of Visa, Mastercard international card associations and the National payment system PROSTIR
TokenA unique digital identifier of a card, which is generated during the first operation and then used for quick payment
AuthorizationThe procedure of obtaining confirmation from the issuing bank to make a payment by card
Biometric authorizationThe process of payment confirmation using biometric data (e.g. fingerprint, facial features) identification technology
Issuing Bank (Card Issuing Bank)A bank licensed as a member of a card association (like Visa or Mastercard), that issues and maintains payment cards
3-D Secure3-D Secure is a protocol which is used for secure handling of online bank card payments

General description

Portmone SDK supports iOS 12.0 version and above.

SDK can be integrated into the project in two ways:

  • copy PortmoneSDKEcom.framework to the project manually:

TargetBuild PhasesEmbed Frameworks add this file and set DestinationFrameworks

  • use CocoaPods:
pod 'PortmoneSDKEcom'

Usage scenarios

  1. Payment by card.
  2. Card token receiving (saving a card).
  3. Payment by token (card token can be obtained using scenario 1 or 2).
  4. Money transfer from card to card using token.
  5. Payment via Apple Pay.
  6. Making payments with Touch/Face ID.
  7. Mass payment of utility bills

Software interface description

1. Get started with the SDK

Before you get started to use the SDK methods, you need to initialize Payment Presenter which accepts a set of parameters:

/// Initializer
public init(delegate: PaymentPresenterDelegate,
styleSource: StyleSource? = nil,
language: PortmoneSDKEcom.PaymentPresenter.Language? = nil,
biometricAuth: Bool = false),
customUid: String? = nil)

Parameters

FieldTypeDescriptionNullability
delegatePaymentPresenterDelegateDelegate protocol. Provides information on payment statusrequired
styleSourceStyleSourceProtocol for screen elements customizationoptional
languageLanguageEnum to set the SDK interface language. Possible values: ukrainian, english. If the parameter is not transferred, the language of the client device will be usedrequired
biometricAuthBoolParameter used to activate biometric authorization. Default value: falseoptional
customUidStringThe ID of the endpoint to which requests will be sent. The need for filling agrees with the Portmone.com manageroptional

Please contact our Account Managers to activate biometric authorization

E-mail: [email protected]

PaymentPresenterDelegate protocol

/// Protocol for return payment result
@objc public protocol PaymentPresenterDelegate: class {
/// Method triggered as result of payment process.
///
/// - Parameter bill: Bill
/// - Parameter error: Error
func didFinishPayment(bill: Bill?, error: Error?)

/// Method triggered as result of payment bills process.
///
/// - Parameter bills: [UBill]
/// - Parameter error: Error
@objc optional func didFinishPaymentBills(bills: [UBill]?, error: Error?)

/// Optional method.
/// Method triggered when PortmoneSDK had already dismissed.
@objc optional func dismissedSDK()

/// Optional method.
/// Method triggered when the client closed the PortmoneSDK.
@objc optional func canceledSDK()
}

PayeePaymentDelegate methods

MethodParametersDescription
didFinishPaymentPortmoneSDKEcom.Bill?
Error?
Called after payment completion. The Bill object is present in case of successful payment. A system error or an Error protocol object may be present when an error occurs
didFinishPaymentBills[PortmoneSDKEcom.UBill]?Error?Called after bulk payment is completed. In case of success, UBill objects are present, in case of error, there may be a system error or protocol object Error
dismissedSDKCalled after closing the payment window
cancelledSDKCalled after the payment window was closed by the user

StyleSource protocol

/// Title label font (All screens)
func titleFont() -> UIFont

/// Title label color (All screens)
func titleColor() -> UIColor

/// Section header label font (Payment, commission screens)
func headersFont() -> UIFont

/// Section header label color (Payment, commission screens)
func headersColor() -> UIColor

/// Section header view background color (Payment, commission screens)
func headersBackgroundColor() -> UIColor

/// All textFields placeholder font
func placeholdersFont() -> UIFont

/// All textFields placeholder color
func placeholdersColor() -> UIColor

/// All textFields text font
func textsFont() -> UIFont

/// All textFields text color
func textsColor() -> UIColor

/// All error strings text font
func errorsFont() -> UIFont

/// All error strings text color
func errorsColor() -> UIColor

/// All background color (Table, cells, navigation bar)
func backgroundColor() -> UIColor

/// Message label font (Result, 2d verification screens)
func resultMessageFont() -> UIFont

/// Message label color (Result, 2d verification screens)
func resultMessageColor() -> UIColor

/// Save receipt title color (Result screen)
func resultSaveReceiptColor() -> UIColor

/// Informative label on button (Save card screen)
func infoTextsFont() -> UIFont

func infoTextsColor() -> UIColor

/// Buttons back and next title font
func buttonTitleFont() -> UIFont

/// Button bottom title color
func buttonTitleColor() -> UIColor

/// Buttons back and next tint color
func buttonColor() -> UIColor

/// Button corner radius
func buttonCornerRadius() -> CGFloat

/// Biometric button title color
func biometricButtonColor() -> UIColor

/// Image for success result
func successImage() -> UIImage?

/// Image for failure result
func failureImage() -> UIImage?
MethodReturns the parametersDescription
titleFontUIFontThe font of the titles is changed on all screens. The size remains constant
titleColorUIColorThe color of the titles is changed on all screens
headersFontUIFontThe font of all section headers is changed. The size remains constant
headersColorUIColorThe color of all section headers is changed
headersBackgroundColorUIColorThe background color of all section headers is changed
placeholdersFontUIFontThe font of the placeholders on all screens is changed. The size remains constant
placeholdersColorUIColorThe color of the placeholders on all screens is changed
textsFontUIFontThe font of the main texts in the input fields on all screens is changed. The size remains constant
textsColorUIColorThe color of the main text in the input fields on all screens is changed
errorsFontUIFontThe font of errors on all screens is changed. The size remains constant
errorsColorUIColorThe color of errors on all screens is changed. The size remains constant
backgroundColorUIColorThe background color on all screens is changed
resultMessageFontUIFontThe font of the information label on the 2d verification and the payment result screens is changed. The font size remains constant
resultMessageColorUIColorThe color of the information label on the 2d verification and the payment result screens is changed
resultSaveReceiptColorUIColorThe color of the receipt saving button title on the payment result screen is changed
infoTextsFontUIFontThe font of the information text on the card saving screen is changed. The font size remains constant
infoTextsColorUIColorThe color of the information text on the saving card screen is changed
buttonTitleFontUIFontThe font of button titles on all screens is changed. The font size remains constant
buttonTitleColorUIColorThe color of button titles on all screens is changed
buttonColorUIColorThe button background color or color of the button titles on all screens is changed
buttonCornerRadiusCGFloatThe button corner radius on all screens is changed
biometricButtonColorUIColorThe color of the biometric button title on the payment by token screen is changed
successImageUIImage?The successful payment icon is changed
failureImageUIImage?The failed payment icon is changed

Example:

private var presenter: PaymentPresenter?

override func viewDidLoad() {
super.viewDidLoad()

presenter = PaymentPresenter(delegate: self,
styleSource: self,
language: .ukrainian,
biometricAuth: true),
customUid: “YOUR_CUSTOM_UID_FROM_PORTMONE”)
}

2. Payment by card

2.1. Initialization of payment by card

To call the payment by card screen use the presentPaymentByCard method with the required parameters.

PaymentPresenter

// Method to present payment by card screen
public func presentPaymentByCard(on controller: UIViewController,
params: PortmoneSDKEcom.PaymentParams,
showReceiptScreen: Bool = true)

presentPaymentByCard method parameters

ParameterTypeDescriptionNullability
controllerUIViewControllerThe controller on top of which the payment by card screen is shownrequired
paramsPaymentParamsObject with a set of parameters required for the paymentrequired
showReceiptScreenBoolDisplaying a screen with the receipt after successful payment. Default value: true
(* available for SDK version 1.4.0 and higher)
optional

PaymentParams object

FieldTypeDescriptionNullability
descriptionStringDescription of payment detailsoptional
attribute1StringPayment attribute 1optional
attribute2StringPayment attribute 2optional
attribute3StringPayment attribute 3optional
attribute4StringPayment attribute 4optional
billNumberStringNumber of paid bill. Maximum length is 120 symbols. Must be unique within a single order. If the order with this number has already been paid, the Portmone.com system will reject the transactionoptional
preauthFlagBoolPayment pre-authorization mode. The funds are not charged from the account but only blocked. Default value: falseoptional
billCurrencyCurrencyCurrency of the payment. Possible values: UAH (default value), USD, EUR, GBP, BYN, KZToptional
billAmountDoubleAmount of the payment. Example: “1.00”required
payeeIdStringA unique identifier (ID) of the payee companyrequired
typePaymentTypePayment type. It can take one of two values:
1) .payment – standard option;
2) .mobilePayment – the description title is changed to "Phone number" and "+380" is added to the description value itself
optional
merchantIdentifierStringAn identifier you register with Apple that uniquely identifies your business as a merchant able to accept payments (Merchant ID)optional
paymentFlowTypePaymentFlowTypeAn attribute that sets up possible payment scenarios: by card, by card and via Apple Pay, or via Apple Pay only. Possible values: .byCard (default value), .byCardAndApplePay, .byApplePayoptional

Example:

@IBAction private func payButtonClicked(_ sender: UIButton) {
var billNumb = ""
if billNumber.text?.isEmpty ?? true {
billNumb = "SD\(Int(Date().timeIntervalSince1970))"
} else {
billNumb = billNumber.text ?? ""
}
let flowType = PaymentFlowType(payWithCard: payWithCardSwitch.isOn,
payWithApplePay: payWithAPaySwitch.isOn)

let paymentParams = PaymentParams(description: contractNumber.text ?? "",
attribute1: attribute1.text ?? "",
attribute2: attribute2.text ?? "",
attribute3: attribute3.text ?? "",
attribute4: attribute4.text ?? "",
billNumber: billNumb,
preauthFlag: preauthFlag.isOn,
billCurrency: .uah,
billAmount: Double(billAmount.text ?? "") ?? 0,
details: billDetails.text ?? "",
payeeId: payeeId.text ?? "",
merchantIdentifier: merchantIdTextField.text ?? "",
paymentFlowType: flowType)

presenter?.presentPaymentByCard(on: self, params: initParams)
}

Card payment screen (without branding)

Fig. 1a. Card payment screen (without branding)

Card payment screen (without branding)

Fig. 1b. Card payment screen (without branding)

Card payment screen (branding example)

Fig. 2a. Card payment screen (branding example)

Card payment screen (branding example)

Fig. 2b. Card payment screen (branding example)

2.2. Getting the result of payment by card

After a successful payment, the Bill object will be created containing payment information. The didFinishPayment method of the PaymentPresenterDelegate will be called after successful payment using the Bill object as a parameter. If an error occurs during the payment, the parameter will be a system error or an Error protocol object.

Bill object

FieldTypeDescriptionNullability
billIdStringA unique payment IDoptional
statusStringPayment status. Possible values: "PAYED" and "PREAUTH", depending on the type of payment selected at the initializationrequired
billAmountdoubleAmount of the paymentrequired
cardMaskStringThe mask of the card used for payment containing the first six and the last four digits of the card numberoptional
commissionAmountdoubleCommission for the paymentrequired
recieptUrlStringLink to get a pdf receiptoptional
contractNumberStringPersonal account numberoptional
payDatelongTime of payment in millisecondsoptional
payeeNameStringThe name of the company to which the payment has been madeoptional
tokenStringToken value for the payment made. In case of payment via Apple Pay, nil will returnoptional

Example:

// self <-- PaymentPresenter
extension PayByCardViewController: PaymentPresenterDelegate {
func didFinishPayment(bill: Bill?, error: Error?) {
// Save used card
UserDefaults.standard.set(bill?.cardMask, forKey: cardMask)
UserDefaults.standard.set(bill?.token, forKey: cardToken)

if error != nil {
self.presentAlert(title: "Error", message: error?.localizedDescription)
}

if bill != nil {
let mask = bill?.cardMask ?? ""
let token = bill?.token ?? ""
self.presentAlert(title: "Payment Success",
message: "Card mask: \n\(mask), \nToken: \n\(token)")
}
}
}

3. Saving a card

The card saving mechanism provides the possibility to get the token value for further payment by this card without entering the payment card number and expiration date. To receive the token 1 UAH is blocked at the client's card account. Unblocking is performed automatically within 30 minutes.

3.1. Initialization of card saving

To call the card saving screen use the presentPreauthCard method with the required parameters.

PaymentPresenter

/// Method to present preauth card screen
public func presentPreauthCard(on controller: UIViewController,
params: PortmoneSDKEcom.PreauthParams)

presentPreauthCard method parameters

ParameterTypeDescriptionNullability
controllerUIViewControllerThe controller on top of which the card saving screen is shownrequired
paramsPreauthParamsObject with a set of parameters required for the paymentrequired

PreauthParams object

FieldTypeDescriptionNullability
payeeIdStringA unique identifier (ID) of the payee companyrequired
descriptionStringDescription of payment detailsrequired
billNumberStringNumber of paid bill. Maximum length is 120 symbols. Must be unique within a single order. If the order with this number has already been paid, the Portmone.com system will reject the transactionoptional

Example:

@IBAction private func saveButtonClicked(_ sender: UIButton) {
var billNumb = ""
if billNumber.text?.isEmpty ?? true {
billNumb = "SD\(Int(Date().timeIntervalSince1970))"
} else {
billNumb = billNumber.text ?? ""
}

let preauthParams = PreauthParams(payeeId: payeeId.text ?? "",
description: contractNumber.text ?? "",
billNumber: billNumb)

presenter?.presentPreauthCard(on: self, params: preauthParams)
}

Card saving screen (without branding)

Fig. 3. Card saving screen (without branding)

Card saving screen (branding example)

Fig. 4. Card saving screen (branding example)

3.2. Getting the result of card saving

After a successful payment, the Bill object will be created containing payment information. The didFinishPayment method of the PaymentPresenterDelegate will be called after successful payment using the Bill object as a parameter. If an error occurs during the payment, the parameter will be a system error or an Error protocol object.

Bill object

FieldTypeDescriptionNullability
billIdStringA unique payment IDoptional
statusStringPayment status. Possible values: "PAYED" and "PREAUTH", depending on the type of payment selected at the initializationrequired
billAmountdoubleAmount of the paymentrequired
cardMaskStringThe mask of the card used for payment containing the first six and the last four digits of the card numberoptional
commissionAmountdoubleCommission for the paymentrequired
recieptUrlStringLink to get a pdf receiptoptional
contractNumberStringPersonal account numberoptional
payDatelongTime of payment in millisecondsoptional
payeeNameStringThe name of the company to which the payment has been madeoptional
tokenStringToken value for the payment madeoptional

Example:

// self <-- PaymentPresenter
extension SaveCardViewController: PaymentPresenterDelegate {
func didFinishPayment(bill: Bill?, error: Error?) {
// Save preauth card
UserDefaults.standard.set(bill?.cardMask, forKey: cardMask)
UserDefaults.standard.set(bill?.token, forKey: cardToken)

if error != nil {
self.presentAlert(title: "Error", message: error?.localizedDescription)
}

if bill != nil {
let mask = bill?.cardMask ?? ""
let token = bill?.token ?? ""
self.presentAlert(title: "Save Success",
message: "Card mask: \n\(mask), \nToken: \n\(token)")
}
}
}

4. Payment by token

4.1. Initialization of payment by token

To call the payment by token screen use the presentPaymentByToken method with the required parameters.

PaymentPresenter

/// Method to present payment by token screen
public func presentPaymentByToken(on controller: UIViewController,
payParams: PortmoneSDKEcom.PaymentParams,
tokenParams: PortmoneSDKEcom.TokenPaymentParams,
showReceiptScreen: Bool = true)

presentPaymentByToken method parameters

ParameterTypeDescriptionNullability
controllerUIViewControllerThe controller on top of which the payment by token screen is shownrequired
payParamsPaymentParamsObject with a set of parameters required for the paymentrequired
tokenParamsTokenPaymentParamsObject with a set of parameters required for the payment by tokenrequired
showReceiptScreenBoolDisplaying a screen with the receipt after successful payment. Default value: true
(* available for SDK version 1.4.0 and higher)
optional

PaymentParams object

FieldTypeDescriptionNullability
descriptionStringDescription of payment detailsrequired
attribute1StringPayment attribute 1optional
attribute2StringPayment attribute 2optional
attribute3StringPayment attribute 3optional
attribute4StringPayment attribute 4optional
billNumberStringNumber of paid bill. Maximum length is 120 symbols. Must be unique within a single order. If the order with this number has already been paid, the Portmone.com system will reject the transactionoptional
preauthFlagBoolPayment pre-authorization mode. The funds are not charged from the account but only blocked. Default value: falseoptional
billCurrencyCurrencyCurrency of the payment. Possible values: UAH (default value), USD, EUR, GBP, BYN, KZToptional
billAmountDoubleAmount of the payment. Example: “1.00”required
payeeIdStringA unique identifier (ID) of the payee companyrequired

TokenPaymentParams object

FieldTypeDescriptionNullability
cardNumberMaskedStringMasked card numberrequired
tokenDataStringCard tokenrequired
merchantIdentifierStringAn identifier you register with Apple that uniquely identifies your business as a merchant able to accept payments (Merchant ID)optional
paymentFlowTypePaymentFlowTypeAn attribute that sets up possible payment scenarios: by card, by card and via Apple Pay, or via Apple Pay only. Possible values: .byCard (default value), .byCardAndApplePay, .byApplePayoptional

An example of displaying screen of making payment using token/ payment with Face ID (without branding)

Fig. 5. An example of displaying screen of making payment using token/ payment with Face ID (without branding)

Screen of making payment using token/ payment with Face ID (branding example)

Fig. 6. Screen of making payment using token/ payment with Face ID (branding example)

An example of displaying screen of making payment using token/ payment with Touch ID (without branding)

Fig. 7a. An example of displaying screen of making payment using token/ payment with Touch ID (without branding)

An example of displaying screen of making payment using token/ payment with Touch ID (without branding)

Fig. 7b. An example of displaying screen of making payment using token/ payment with Touch ID (without branding)

4.2. Getting the result of payment by token

After a successful payment, the Bill object will be created containing payment information. The didFinishPayment method of the PaymentPresenterDelegate will be called after successful payment using the Bill object as a parameter. If an error occurs during the payment, the parameter will be a system error or an Error protocol object.

Bill object

FieldTypeDescriptionNullability
billIdStringA unique payment IDoptional
statusStringPayment status. Possible values: "PAYED" and "PREAUTH", depending on the type of payment selected at the initializationrequired
billAmountdoubleAmount of the paymentrequired
cardMaskStringThe mask of the card used for payment containing the first six and the last four digits of the card numberoptional
commissionAmountdoubleCommission for the paymentrequired
recieptUrlStringLink to get a pdf receiptoptional
contractNumberStringPersonal account numberoptional
payDatelongTime of payment in millisecondsoptional
payeeNameStringThe name of the company to which the payment has been madeoptional
tokenStringToken value for the payment madeoptional

Example:

// self <-- PaymentPresenter
extension PayByTokenViewController: PaymentPresenterDelegate {
func didFinishPayment(bill: Bill?, error: Error?) {
if error != nil {
self.presentAlert(title: "Error", message: error?.localizedDescription)
}

if bill != nil {
let mask = bill?.cardMask ?? ""
let token = bill?.token ?? ""
self.presentAlert(title: "Payment Success",
message: "Card mask: \n\(mask), \nToken: \n\(token)")
}
}
}

5. Money transfer from card to card using token

5.1. Initialization of money transfer

To call the transfer by token screen use the presentTransferByToken method with the required parameters.

PaymentPresenter

/// Method to present payment by token screen
public func presentTransferByToken(on controller: UIViewController,
transferParams: PortmoneSDKEcom.TransferParams,
tokenParams: PortmoneSDKEcom.TokenPaymentParams,
showReceiptScreen: Bool = true)

presentTransferByToken method parameters

ParameterTypeDescriptionNullability
controllerUIViewControllerThe controller on top of which the payment by card screen is shownrequired
transferParamsTransferParamsObject with a set of parameters required for the paymentrequired
tokenParamsTokenPaymentParamsObject with a set of parameters required for the payment by tokenrequired
showReceiptScreenBoolDisplaying a screen with the receipt after successful payment. Default value: true
(* available for SDK version 1.4.0 and higher)
optional

TransferParams object

FieldTypeDescriptionNullability
attribute2StringPayment attribute 2optional
attribute3StringPayment attribute 3optional
attribute4StringPayment attribute 4optional
billNumberStringNumber of paid bill. Maximum length is 120 symbols. Must be unique within a single order. If the order with this number has already been paid, the Portmone.com system will reject the transactionoptional
billAmountDoubleAmount of the payment. Example: “1.00”required
payeeIdStringA unique identifier (ID) of the payee companyrequired

TokenPaymentParams object

FieldTypeDescriptionNullability
cardNumberMaskedStringMasked card numberrequired
tokenDataStringCard tokenrequired

Example:

@IBAction private func trasferButtonClicked(_ sender: UIButton) {
var billNumb = ""
if billNumber.text?.isEmpty ?? true {
billNumb = "SD\(Int(Date().timeIntervalSince1970))"
} else {
billNumb = billNumber.text ?? ""
}

let transferParams = TransferParams(attribute2: attribute2.text ?? "",
attribute3: attribute3.text ?? "",
attribute4: attribute4.text ?? "",
billNumber: billNumb,
billAmount: Double(billAmount.text ?? "") ?? 0,
payeeId: payeeId.text ?? "")

let mask = UserDefaults.standart.string(forKey: Constants.cardMask)
let token = UserDefaults.standart.string(forKey: Constants.cardToken)

let tokenParams = TokenPaymentParams(cardNumberMasked: mask ?? "",
tokenData: token ?? "")

presenter?.presentTransferByToken(on: self,
transferParams: transferParams,
tokenParams: tokenParams)
}

Money transfer screen from card to card (without branding)

Fig. 8a. Money transfer screen from card to card (without branding)

Money transfer screen from card to card (without branding)

Fig. 8b. Money transfer screen from card to card (without branding)

Money transfer screen from card to card (branding example)

Fig. 9a. Money transfer screen from card to card (branding example)

Money transfer screen from card to card (branding example)

Fig. 9b. Money transfer screen from card to card (branding example)

5.2. Getting the result of money transfer from card to card using token

After a successful payment, the Bill object will be created containing payment information. The didFinishPayment method of the PaymentPresenterDelegate will be called after successful payment using the Bill object as a parameter. If an error occurs during the payment, the parameter will be a system error or an Error protocol object.

Bill object

FieldTypeDescriptionNullability
billIdStringA unique payment IDoptional
statusStringPayment status. Possible values: “PAYED” and “PREAUTH”, depending on the type of payment selected at the initializationrequired
billAmountdoubleAmount of the paymentrequired
cardMaskSringThe mask of the card used for payment containing the first six and the last four digits of the card numberoptional
commissionAmountdoubleCommission for the paymentrequired
recieptUrlStringLink to get a pdf receiptoptional
contractNumberStringPersonal account numberoptional
payDatelongTime of payment in millisecondsoptional
payeeNameStringThe name of the company to which the payment has been madeoptional
tokenStringToken value for the payment madeoptional

Example:

// self <-- PaymentPresenter
extension PayByTokenViewController: PaymentPresenterDelegate {
func didFinishPayment(bill: Bill?, error: Error?) {
if error != nil {
self.presentAlert(title: "Error", message: error?.localizedDescription)
}

if bill != nil {
let mask = bill?.cardMask ?? ""
let token = bill?.token ?? ""
self.presentAlert(title: "Payment Success",
message: "Card mask: \n\(mask), \nToken: \n\(token)")
}
}
}

6. Payment via Apple Pay

You must have an account in Apple Developer to accept payments through Apple Pay.

Next, follow these steps:

  1. Register a Merchant ID and send it to Portmone.com:

    a. Sign in to your Apple Developer Account.

    b. Select "Certificates, Identifiers & Profiles".

    c. Under "Identifiers", select "Merchant IDs".

    d. Add a new Merchant ID by clicking the Add button ("+") in the upper-right corner of the screen.

    e. Fill in the required fields*, then click "Continue".

    f. Click "Register" to confirm the data entered.

    g. Send your Merchant ID to Portmone.com at [email protected].

Note: * – in the Description field specify your description. In the Identifier field specify the reverse domain name of your site with adding the "merchant" at the beginning (for example, if your site is shop.ua, the Identifier will look like this – merchant.ua.shop).

  1. Obtain a CSR (certificate signing request) file from Portmone.com. CRS will be provided by Portmone.com in the return email after you send your Mercant ID. Use this CSR at the next step.

  2. Create an Apple Pay Payment Processing Certificate and send it to Portmone.com:

    a. Sign in to your Apple Developer Account.

    b. Select "Certificates, Identifiers & Profiles".

    c. Under "Identifiers", select "Merchant IDs".

    d. Select the Merchant ID you created earlier from the list and click "Edit".

    e. In the Apple Pay Payment Processing Certificate section click "Create Certificate".

    f. On the next screen click "Continue".

    g. Click "Choose File" to upload the certificte. In the dialog that appears, select CRS-file obtained from Portmone.com, then click "Continue".

    h. Download the generated certificate.

    i. Send the downloaded certificate (a file with a .cer file extension) at [email protected].

To make a payment through Apple Pay you should send your Merchant ID in the merchantIdentifier parameter when calling the SDK.

An example of displaying a payment screen with the ability to pay by card or via Apple Pay (without branding)

Fig. 10a. An example of displaying a payment screen with the ability to pay by card or via Apple Pay (without branding)

An example of displaying a payment screen with the ability to pay by card or via Apple Pay (without branding)

Fig. 10b. An example of displaying a payment screen via Apple Pay (without branding)

An example of displaying a payment screen with the ability to pay by card or via Apple Pay (without branding)

Fig. 11. An example of displaying a payment screen via Apple Pay (without branding)

7. Mass payment of utility bills

This method allows you to pay multiple bills that were found using an address search.

7.1 Saving a card

7.1.1 Obtaining credentials

It is necessary to make a POST request with the parameters of the user's login and password to receive credentials

https://www.portmone.com.ua/r3/api/merchant-bills

Request structure and example:

{
"method":"getcred",
"params": {
"data": {
"login": "Login,
"password": "Password"
}
},
"id":"1"
}

Response structure and example:

{
"result": {
"credentials": "32397c10e4ccc5841ae706ed4b16d0eb42adce4e6890466663c140a017f6869c2a52f5d6384447"
},
"id": "1"
}

Important! Must be savedcredentials. When changing the password, it is necessary to generate credentials again.

7.1.2 Saving the card for mass payment of utility bills

The mechanism of saving the card allows you to receive a token for further mass payment of bills with this card without specifying the number and date.

To call the payment by card screen use the presentPreauthCardBill method with the required parameters.

PaymentPresenter

/// Method to present preauth card screen
public func presentPreauthCardBill(on controller: UIViewController,
params: PortmoneSDKEcom.SaveCardTokenBillParams)

presentPreauthCardBill method parameters

ParameterTypeDescriptionNullability
controllerUIViewControllerThe controller on top of which the payment by card screen is shownrequired
paramsSaveCardTokenBillParamsObject with a set of parameters required for the paymentrequired

SaveCardTokenBillParams

FieldTypeDescriptionNullability
contractNumberStringUser loginrequired
attribute1StringCredentials which we received by making the request described in the paragraph 7.1.1required
languageLanguage.rawValueEnum to set the SDK interface language. Possible values: ukrainian, english. If the parameter is not transferred, the language of the client device will be usedrequired

Example:

    @IBAction private func saveButtonClicked(_ sender: UIButton) {

let initParams = SaveCardTokenBillParams(contractNumber: contractNumber.text ?? "",
attribute1: attribute1.text ?? "",
language: Language.ukrainian.rawValue)

presenter?.presentPreauthCardBill(on: self, params: initParams)

7.1.3 Getting the result of card saving

After a successful payment, a Bill object will be created with payment information and the didFinishPayment method of the PaymentPresenterDelegate delegate will be called with it as a parameter. In the event of a payment error, the parameter will be a system error or an Error protocol object.

Bill object

FieldTypeDescriptionNullability
billIdStringA unique payment IDoptional
statusStringPayment status. Possible values: "PAYED" and "PREAUTH", depending on the type of payment selected at the initializationrequired
billAmountdoubleAmount of the paymentrequired
cardMaskSringThe mask of the card used for payment containing the first six and the last four digits of the card numberoptional
commissionAmountdoubleCommission for the paymentrequired
recieptUrlStringLink to get a pdf receiptoptional
contractNumberStringPersonal account numberoptional
payDatelongTime of payment in millisecondsoptional
payeeNameStringThe name of the company to which the payment has been madeoptional
tokenStringToken value for the payment made. In case of payment via Apple Pay, nil will returnoptional

Example:

// self <-- PaymentPresenter
extension SaveCardViewController: PaymentPresenterDelegate {
func didFinishPayment(bill: Bill?, error: Error?) {
// Save preauth card
UserDefaults.standard.set(bill?.cardMask, forKey: cardMask)
UserDefaults.standard.set(bill?.token, forKey: cardToken)

if error != nil {
self.presentAlert(title: "Error", message: error?.localizedDescription)
}

if bill != nil {
let mask = bill?.cardMask ?? ""
let token = bill?.token ?? ""
self.presentAlert(title: "Save Success",
message: "Card mask: \n\(mask), \nToken: \n\(token)")
}
}
}

7.2. Mass payment of utility bills by token

7.2.1 Initialization of payment by token

To call the payment by token screen use the presentPaymentBillsByToken method with the required parameters.

PaymentPresenter

/// Method to present payment Bills by token screen
public func presentPaymentBillsByToken(on controller: UIViewController,
payParams: PortmoneSDKEcom.BillsPaymentParams,,
tokenParams: PortmoneSDKEcom.TokenPaymentParams)

presentPaymentBillsByToken method parameters

ParameterTypeDescriptionNullability
controllerUIViewControllerThe controller on top of which the payment by token screen is shownrequired
payParamsBillsPaymentParamsObject with a set of parameters required for the paymentrequired
tokenParamsTokenPaymentParamsObject with a set of parameters required for the payment by tokenrequired

BillsPaymentParams object

FieldTypeDescriptionNullability
contractNumberStringUser loginrequired
paymentBills[PaymentBill]An array of bills for payment. The PaymentBill object includes 2 mandatory parameters, these are:
billId: String, (Example: “123456789”.)
billAmount: Double, (Example : "1.00".)
required
billCurrencyCurrencyCurrency of the payment. Possible values: UAH (default value)optional
paymentFlowTypepaymentFlowTypeAn attribute that sets up possible payment scenarios: by card, by card and via Apple Pay, or via Apple Pay only. Possible values: .byCard (default value), .byCardAndApplePay, .byApplePayoptional
merchantIdentifierStringAn identifier you register with Apple that uniquely identifies your business as a merchant able to accept payments (Merchant ID)optional

TokenPaymentParams object

FieldTypeDescriptionNullability
cardNumberMaskedStringMasked card numberrequired
tokenDataStringCard tokenrequired
credentialsStringCredentials which we received by making the request described in the paragraph 7.1.1required

7.2.2. Getting the result of payment by token

After making the payment, an array of [UBill] objects will be formed with information about the payment of each bill and the didFinishPaymentBills method of the PaymentPresenterDelegate delegate will be called with it as a parameter. In the event of a payment error, the parameter will be a system error or an Error protocol object.

After a successful payment by receiving an array of [UBill] objects in the didFinishPaymentBills method of the PaymentPresenterDelegate delegate, it is necessary to analyze each bill. If the parameters status of the account are not "PAYED" and errorMessage is not empty, it means that the account has not been paid, the error of payment of the account is in the errorMessage parameter.

UBill object

FieldTypeDescriptionNullability
billIdStringA unique payment IDoptional
statusStringPayment status. Possible values: "PAYED" and "PREAUTH", depending on the type of payment selected at the initializationrequired
billAmountdoubleAmount of the paymentrequired
cardMaskSringThe mask of the card used for payment containing the first six and the last four digits of the card numberoptional
commissionAmountdoubleCommission for the paymentrequired
recieptUrlStringLink to get a pdf receiptoptional
contractNumberStringPersonal account numberoptional
payDatelongTime of payment in millisecondsoptional
errorMessageStringПerror messageoptional
payeeNameStringthe company nameoptional

Example:

// self <-- PaymentPresenter
extension PayBillsViewController: PaymentPresenterDelegate {

func didFinishPaymentBills(bills: [UBill]?, error: Error?) {
if error != nil {
presentAlert(title: "Error", message: error?.localizedDescription)
}

if bills != nil {
var description: String = ""
bills?.forEach({ bill in
description += "\n\nBill id: \(bill.billId ?? "")\nBill status: \(bill.status)\nBill amount: \(bill.billAmount)\nBill paidAmount: \(bill.paidAmount)\nBill commission: \(bill.commissionAmount)\nBill authCode: \(bill.authCode ?? "")\nBill recieptUrl: \(bill.recieptUrl ?? "")\nBill payDate: \(bill.payDate ?? "")\nBill payeeName: \(bill.payeeName ?? "")\nBill errorMessage: \(bill.errorMessage ?? "")"
})

self.presentAlert(title: "Payment Bills",
message: description)

Testing

After registering in the Portmone.com system, you need to get the following information from your Account manager:

  • the ID of your company in the Portmone.com system (payee_id);
  • your company's private key – a value that you will use to create a unique signature of each request.

The Portmone.com system provides partners with two modes for testing: test mode and production mode with an automatic payment cancellation.

The test mode of the payment gateway means that the Portmone.com system checks the validity of entered data from the Partner and its Client, creates an order, but payment card authorization is not performed. 3-D Secure check is not possible.

Cards for testing:

Card numberResult
4444333322221111Successful payment
4111111111111111Failed payment

The production mode with payment auto cancellation provides the possibility to make real payments using real payment cards. The cancellation of payment is performed automatically within 30 minutes.

Please contact our Account Managers to enable and disable test mode or payment auto cancellation

Email: [email protected]

Important! Before putting the payment acceptance system into operation, make sure that the test mode or payment auto cancellation are disabled!