Client iOS SDK

Summary

This document describes how to integrate the One Inc’s PortalOne iOS SDK into an existing iOS application and invoke the make payment and/or save payment method. When these methods are invoked, a modal will open which will allow a user to make a payment or save a payment method based upon the provided parameters.

Requirements

Platform Compatibility

iOS 9.0 and up

Installation

You can install Digital Payments Widgets into your project with CocoaPods. For this you must add into Podfile from your project next line into use_frameworks! block

pod 'DigitalPaymentsSDK', :git => 'URL', :tag => '1.0.3'
After that run pod update command.

Prepare your API

Our prebuilt UI elements require a temporary key, a short-lived API key with restricted API access. You can think of an temporary key as a session, authorizing the SDK to retrieve and update a specific object for the duration of the session. To provide a temporary key to the SDK, you'll need to expose a new API endpoint on your backend. This endpoint should create a temporary key for the current One Inc customer, and return the key's unmodified response as JSON. This temporary key is called Session Key.

In order to create the Session Key you need a PortalOne authentication key. This key uniquely identifies you as a customer and it is your responsibility to keep your authentication key secure. To help encourage good security practices, client side requests which would expose the authentication key are not permitted and a server-side request to obtain the Session Key is required. If you do not have your PortalOne Authentication Key, please feel free to reach out to us and we can issue one.


[HttpGet]
[ResponseType(typeof(CreateSessionResponse))]
public async Task<HttpResponseMessage> Create()
{
    try
    {
        using (var httpClient = new HttpClient())
        {
            var request = new CreateSessionRequest
            {
                PortalOneAuthenticationKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            };

            var uri = new Uri("https://stgportalone.processonepayments.com/GenericModal/SessionKey/Create");
            var httpResponseMessage = await httpClient.PostAsJsonAsync(uri, request);
            if (httpResponseMessage.IsSuccessStatusCode)
            {
                var response = await httpResponseMessage.Content.ReadAsAsync<CreateSessionResponse>();
                var httpStatusCode = response.IsSuccessful
                    ? HttpStatusCode.OK
                    : HttpStatusCode.InternalServerError;
                return Request.CreateResponse(httpStatusCode, response);
            }

            return Request.CreateErrorResponse(httpResponseMessage.StatusCode,
                httpResponseMessage.ReasonPhrase);
        }
    }
    catch (Exception e)
    {
        return Request.CreateErrorResponse(HttpStatusCode.InternalServerError, e.Message);
    }
}

Initialization

The setup of any of SDK actions is simply a call to initialize(sessionKey, url) static method with a Session key, which was generated with your Session Key API endpoint, and an url of PortalOne service API.


DPMakePayment
    .initialize(sessionKey: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        url: "https://stgportalone.processonepayments.com")
    ...
                        

Digital Payment Forms API

Making a payment

In order to make payment need your code should start the DPMakePayment view controller. The view should be set with parameters of specific payment so the view controller should be called as method calls chain DPMakePayment#initialize, DPMakePayment#makePayment and DPMakePayment#startWebView

In result of the method chain call the make payment process will be started.

DPMakePayment methods

Method Description
initialize See Initialization
makePayment Sets payment parameters. See MakePaymentRequest. Required
startWebView Starts the view. The parameter is a parent view controller. Required

If you're going to launch the DPMakePayment from a button, and you've set the button's onClick action, add the method as:


@IBAction func onClick(_ sender: UIButton) {
    DPMakePayment
        .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
        .makePayment(request:
            MakePaymentRequest(
                paymentCategory: PaymentCategory.eCheck,
                feeContext: FeeContext.paymentWithFee,
                amountContext: AmountContext.selectOrEnterAmount,
                minAmountDue: 50,
                accountBalance: 100,
                policyHolderName: "John Smith",
                clientReferenceData1: "POL330701-02"
            ))
        .startWebView(hostViewController: self)
}

MakePaymentRequest data object

Here you can find a detailed explanation of every field in the MakePaymentRequest data object that is required to start the DPMakePayment view controller.

Field Name Description Type Note
paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation or if the user will be able to make a choice. PaymentCategory Required
feeContext Indicates whether a fee will be applied to the payment. FeeContext Required
amountContext Indicates if the user will be able to set the payment amount and if so, which options will be provided. AmountContext Optional
saveOption Indicates whether a requested operation will save the payment method that is used to make the payment. SaveOption Optional, if not sent default value will be DoNotSave.
confirmationDisplay Indicates whether the flow for the requested operation will display a final confirmation screen upon the completion of the primary operation. Bool Optional, if not sent default will be true
minAmountDue The minimum amount that is due for a policy. Must be greater than zero. Decimal Required
accountBalance The outstanding balance for the policy. Decimal Required
billingZip Zip code associated with the credit card. The value will be pre-populated on the form if provided. String Optional. Card operations only
billingAddressStreet Billing address associated with the credit card. The value will be pre-populated on the form if provided. String Optional
policyHolderName Name that will be linked to the payment. The value will be pre-populated on the form if provided. Bool Optional
accountGroupCode Indicates the account group/corresponding bank account where the transaction's funds will be allocated from the set of account groups configured in your merchant settings. If omitted, the default account group configured in your merchant settings will be used. String Optional
clientReferenceData1 A reference number that will be linked to a transaction. Usually this is a policy number or some other identifier that corresponds to a particular policy or claim number. The value will be searchable in the transaction search report. String Required
clientReferenceData2 An External TransactionId value. The value will be searchable in the transaction search report. String Optional
clientReferenceData3 Location data such as the office the transaction originated. The value will be searchable in the transaction search report. String Optional
clientReferenceData4 Additional information with the transaction. The value will be displayed in the transaction details. String Optional
clientReferenceData5 Source account information. Additional reference number such as an account number. The value will be searchable in the transaction search report. String Optional
token Token that identifies credit card or bank account. String Optional

Saving a payment method

To start a save payment method process we need to call a similar method chain.

The following example demonstrates how to start a save payment method activity:


DPSavePaymentMethod
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .savePaymentMethod(request:
        SavePaymentMethodRequest(
            paymentCategory: PaymentCategory.creditCard,
            policyHolderName: "John Smith",
            clientReferenceData1: "POL330701-02"
        ))
    .startWebView(this)

SavePaymentMethodRequest data object

Here you can find a detailed explanation of every field in the SavePaymentMethodRequest data object that is required to start the DPSavePaymentMethod view controller.

Field Name Description Type Note
paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation or if the user will be able to make a choice. PaymentCategory Required
confirmationDisplay Indicates whether the flow for the requested operation will display a final confirmation screen upon the completion of the primary operation. Bool Optional, if not sent default will be true
billingZip Zip code associated with the credit card. The value will be pre-populated on the form if provided. String Optional. Card operations only
billingAddressStreet Billing address associated with the credit card. The value will be pre-populated on the form if provided. String Optional
policyHolderName Name that will be linked to the payment. The value will be pre-populated on the form if provided. Bool Optional
clientReferenceData1 A reference number that will be linked to a transaction. Usually this is a policy number or some other identifier that corresponds to a particular policy or claim number. The value will be searchable in the transaction search report. String Required
clientReferenceData2 An External TransactionId value. The value will be searchable in the transaction search report. String Optional
clientReferenceData3 Location data such as the office the transaction originated. The value will be searchable in the transaction search report. String Optional
clientReferenceData4 Additional information with the transaction. The value will be displayed in the transaction details. String Optional
clientReferenceData5 Source account information. Additional reference number such as an account number. The value will be searchable in the transaction search report. String Optional

Common Data Types

Payment Category Enum

PortalOne requires you to provide a payment category option which allows you to easily toggle from credit card to bank account operations. The payment category field is required for every operation. If this field is not included in the request, the PortalOne API will trigger an error event.

Option NameDescription
creditCard

Specifies a Credit/Debit card operation

eCheck

Specifies a bank account operation

userSelect

Allows the user to select the payment type. This value should not be used when charging percentage based fees.

Fee Context Enum

PortalOne allows you to make a payment with or without a fee. To determine if a fee will be charged, send the appropriate Fee Context. The Fee Context field is required for the make payment operation. If this field is not provided in the request, the PortalOne API will trigger an error event.

Option NameDescription
paymentWithFee

Specifies that a fee will be added to the payment amount

paymentWithoutFee

Specifies that the payment will be processed without any additional fee

Amount Context Enum

PortalOne allows you to control if the user can specify the payment amount or pay a fixed amount. To specify how the payment amount will be determined, send the appropriate Amount Context. The Amount Context is NOT required for every operation. If The AmountContext property is not included or value is null, the system will interpret as a value of selectOrEnterAmount.

Option NameDescription
amountDueOnly

Will set the payment amount to the value that is sent in the minAmountDue field. The payment amount will be display only

selectAmount

Will allow the user to specify the payment amount by selecting either the payment amount from the values that are sent in the minAmountDue field or the accountBalance field

selectOrEnterAmount

Will allow the user specify the payment amount by selecting one of the values sent in minAmountDue or accountBalance or entering a value in a text field. The entered amount must be greater than zero and less than or equal to the accountBalance

selectOrEnterAmountConstrained

Will allow the user specify the payment amount by selecting either the minAmountDue or accountBalance amounts passed in the request or entering a value in a text field. The entered amount must be no less than the minAmountDue and no greater than the accountBalance passed in the request to open the modal

Save Option Enum

PortalOne allows you to specify if a payment method that is being used to make a payment will be saved or not. The Save Option is NOT required for every operation. If the SaveOption property is not included or value is null, the system will interpret as a value of doNotSave. Applicable to Make payment operations only.

Option NameDescription
userSelect

Specifies the user will be able to make a choice of whether or not to save the payment method that is used to make the payment

save

Specifies the payment method that is used to make the payment will be securely saved and a token will be returned which can be used to make future payments

doNotSave

Specifies the payment method that is used to make the payment will not be saved

Events

The PortalOne iOS SDK provides custom events for most actions. You can add event handler functions using an appropriate view controller method. The PortalOne library declares the following events:

We use higher-order functions in order to register event handlers. So you can use lambda functions or give a handling method as a parameter.

Close Event

Occurs when a dialog is closed.

Example:


DPSavePaymentMethod
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .savePaymentMethod(request: saveRequest)
    .onClose(do: { print("onClose event") })
    .startWebView(hostViewController: self)

Error Event

Occurs on errors.

Example:


DPMakePayment
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .makePayment(request: makePaymentRequest)
    .onError(do: {(error: ErrorResponse) -> Void in print("onError: \(error.toJSONString())")  })
    .startWebView(hostViewController: self)

Event Object Parameter

Field Name Description Type
Description Error description String
Details Collection of error messages Dictionary with String key and array of String value

Event Object Example:


let error = ErrorResponse(description: "There are validation errors")
error.details = [
    "paymentCategory": ["The paymentCategory is a required field"],
    "clientReferenceData1": ["Incorrect format"]
]
                        

Payment Complete Event

Occurs when payment is successfully completed.

Example:


DPMakePayment
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .makePayment(request: makePaymentRequest)
    .onPaymentComplete(do: {(response: PaymentInfo) -> Void in
        print("onPaymentComplete \(response.toJSONString())") })
    .startWebView(hostViewController: self)

CreditCardPaymentInfo event Object Parameter

Will be returned for payments with PaymentCategory of creditCard

Field Name Description Type
sessionId Unique identifier echoed back from call to a PortalOne operation. UUID
paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. PaymentCategory
cardType Returns the card type that was processed. String
customerName Name that was provided with a card or bank account inforamtion. Passed back as Customer Name String
holderZip Returns zip code of card holder passed back from billingZip on request. String
authCode Returns authorization code provided by issuing bank. String
cardExpirationMonth Returns the card expiration month. Int
cardExpirationYear Returns the card expiration year. Int
tokenId Unique identifier that represents a saved card. Can be used to safely make payments of with the save payment method. String
batchNumber ProcessOne Batch ID, file identifier. Identifies which batch is associated with a transaction. Int
transactionId ProcessOne Transaction ID, payment identifier. Will be displayed as Confirmation number on the modal and web pages. Can be used to search for a specific payment in the ProcessOne Transaction Report String
paymentAmount The premium payment amount excluding any convenience fees. Decimal
convenienceFee The convenience fee applied to premium amount. Decimal
totalPaymentAmount The total payment amount that was processed including convenience fees. Decimal
lastFourDigits Last 4 digits of the card or bank account String
transactionDate Date Stamp of the payment with time zone Date
Credit Card PaymentInfo Object Example:

let info = CreditCardPaymentInfo()
info.sessionId = UUID(uuidString: "aec2b965-87a2-49b2-89b7-ef96d26f7764")
info.transactionId = "2"
info.paymentAmount = 50
info.totalPaymentAmount = 55
info.convenienceFee = 5
info.lastFourDigits = "1234"
info.transactionDate = DateFormatter.portalOneDateFormat("PST")
    .date(from: "Tue Feb 11 02:56:11 GMT+00:00 2020")
info.batchNumber = 2
info.clientReferenceData1 = "123456789"
info.tokenId = "c99c5aca-16c8-491f-ab10-45bac17a1111"
info.paymentCategory = .creditCard
info.cardType = "Visa"
info.customerName = "Test"
info.holderZip: "95630"
info.authCode: "TEST0000"
info.cardExpirationYear: 2021
info.cardExpirationMonth: 4

BankAccountPaymentInfo event Object Parameter

Will be returned for payments with PaymentCategory of eCheck

Field Name Description Type
sessionId Unique identifier echoed back from call to a PortalOne operation. UUID
paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. PaymentCategory
accountType Returns the account type of the bank account: Checking or Saving. String
bankName Returns the name of a bank associated with a provided account. String
customerName Name that was provided with a card or bank account inforamtion. Passed back as Customer Name String
tokenId Unique identifier that represents a saved card or bank account. Can be used to safely make payments of with the save payment method. String
batchNumber ProcessOne Batch ID, file identifier. Identifies which batch is associated with a transaction. Int
transactionId ProcessOne Transaction ID, payment identifier. Will be displayed as Confirmation number on the modal and web pages. Can be used to search for a specific payment in the ProcessOne Transaction Report String
paymentAmount The premium payment amount excluding any convenience fees. Decimal
convenienceFee The convenience fee applied to premium amount. Decimal
totalPaymentAmount The total payment amount that was processed including convenience fees. Decimal
lastFourDigits Last 4 digits of the card or bank account String
transactionDate Date Stamp of the payment with time zone Date
ECheck PaymentInfo Object Example:

let info = BankAccountPaymentInfo()
info.sessionId = UUID(uuidString: "aec2b965-87a2-49b2-89b7-ef96d26f7764")
info.transactionId = "2"
info.paymentAmount = 50
info.totalPaymentAmount = 55
info.convenienceFee = 5
info.lastFourDigits = "1234"
info.transactionDate = DateFormatter.portalOneDateFormat("PST")
    .date(from: "Tue Feb 11 02:56:11 GMT+00:00 2020")
info.batchNumber = 2
info.clientReferenceData1 = "123456789"
info.tokenId = "c99c5aca-16c8-491f-ab10-45bac17a1111"
info.paymentCategory = .eCheck
info.customerName = "Test"
accountType = "Checking",
bankName = "Test bank"

Payment Canceled Event

Occurs when payment operation is canceled.

Example:


DPMakePayment
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .makePayment(request: makePaymentRequest)
    .onPaymentCanceled(do: { print("onPaymentCanceled")  })
    .startWebView(hostViewController: self)

Save Complete Event

Occurs when payment method was successfully saved.

Example:


DPSavePaymentMethod
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .savePaymentMethod(request: saveRequest)
    .onSaveComplete(do: {(response: SavePaymentMethodResponse) -> Void in
        print("onSaveComplete \(response.toJSONString())") })
    .startWebView(hostViewController: self)

SaveCreditCardResponse Event Object Parameter

Will be returned for operations with PaymentCategory of creditCard only.

Field Name Description Type
sessionId Unique identifier echoed back from call to a PortalOne operation. UUID
paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. PaymentCategory
cardType Returns the card type that was processed. String
cardExpirationMonth Returns the card expiration month. Int
cardExpirationYear Returns the card expiration year. Int
customerName Name that was provided with a card or bank account inforamtion. Passed back as Customer Name String
holderZip Returns zip code of cardholder passed back from billingZip on request. String
tokenId Unique identifier that represents a saved card or bank account. Can be used to safely make payments of with the save payment method. String
lastFourDigits Last 4 digits of the card or bank account that was tokenized String
transactionDate Date Stamp of the save operation with time zone Date
SaveCreditCardResponse Object Example:

let info = SaveCreditCardResponse()
info.sessionId = UUID(uuidString: "aec2b965-87a2-49b2-89b7-ef96d26f7764")
info.lastFourDigits = "1234"
info.transactionDate = DateFormatter.portalOneDateFormat("PST")
    .date(from: "Tue Feb 11 02:56:11 GMT+00:00 2020")
info.batchNumber = 2
info.tokenId = "c99c5aca-16c8-491f-ab10-45bac17a1111"
info.paymentCategory = .creditCard
info.cardType = "Visa"
info.customerName = "Test"
info.holderZip: "95630"
info.authCode: "TEST0000"
info.cardExpirationYear: 2021
info.cardExpirationMonth: 4

SaveBankAccountResponse Event Object Parameter

Will be returned for operations with PaymentCategory of eCheck only.

Field Name Description Type
sessionId Unique identifier echoed back from call to a PortalOne operation. UUID
paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. PaymentCategory
accountType Returns the account type of the bank account: Checking or Saving. String
bankName Returns the name of a bank associated with a provided account. String
customerName Name that was provided with a card or bank account inforamtion. Passed back as Customer Name String
tokenId Unique identifier that represents a saved card or bank account. Can be used to safely make payments of with the save payment method. String
lastFourDigits Last 4 digits of the card or bank account that was tokenized String
transactionDate Date Stamp of the save operation with time zone Date
ECheck SavePaymentInfo Object Example:

let info = SaveBankAccountResponse()
info.sessionId = UUID(uuidString: "aec2b965-87a2-49b2-89b7-ef96d26f7764")
info.lastFourDigits = "1234"
info.transactionDate = DateFormatter.portalOneDateFormat("PST")
    .date(from: "Tue Feb 11 02:56:11 GMT+00:00 2020")
info.batchNumber = 2
info.tokenId = "c99c5aca-16c8-491f-ab10-45bac17a1111"
info.paymentCategory = .eCheck
info.customerName = "Test"
info.accountType = "Checking"
info.bankName = "Test bank"

Save Canceled Event

Occurs when save operation is canceled.

Example:


DPSavePaymentMethod
    .initialize(sessionKey: "xxxxxx-xxxx-xxxx-xxxxxxxxxxxx", url: "http://baseUrl")
    .savePaymentMethod(request: saveRequest)
    .onSaveCanceled(do: { print("onSaveCanceled") })
    .startWebView(hostViewController: self)

Test Data

Credit Card Test Data

You can use the following card numbers for testing purposes.

Card Type Card number Cvv2 Expiration date Comments
Visa 4111111111111111 Any 3 digit Any future date
MasterCard 5431111111111111 Any 3 digit Any future date
Discover 6011601160116611 Any 3 digit Any future date
AmericanExpress 341111111111111 Any 4 digit Any future date
Hybrid Visa PinlessDebit Star 4024007167282317 Any 3 digit Any future date This is as a Hybrid Visa card. If your Merchant is provisioned for Pinless Debit cards, the card will process as a pinless debit Star. If your merchant account is not setup for Pinless Debit, it will process as a Visa
Hybrid Discover PinlessDebit Pulse 6011172923498605 Any 3 digit Any future date This is as a Hybrid Discover card. If your Merchant is provisioned for Pinless Debit cards, the card will process as a pinless debit Pulse. If your merchant account is not setup for Pinless Debit, it will process as a Discover
Hybrid MasterCard PinlessDebit Nyce 5384483278305365 Any 3 digit Any future date This is as a Hybrid Mastercard. If your Merchant is provisioned for Pinless Debit cards, the card will process as a pinless debit Nyce. If your merchant account is not setup for Pinless Debit, it will process as a Mastercard

Use the following card number and amount combination to simulate different API response codes

Card number Amount Response Code Description
4444444444444448 1.00 or any not listed amount Success Test: Charge approved
4444444444444448 2.00 or 12.00 IncorrectValidationValue Test: CVV2 code is invalid
4444444444444448 3.00 or 13.00 Declined Test: Declined
4444444444444448 4.00 OverMaximumPayment Test: Exceed max payment amount
4444444444444448 5.00 or 15.00 DuplicateTransaction Test: Duplicate transaction
4444444444444448 6.00 or 16.00 GatewayInternalError Test: System is down
4444444444444448 7.00 or 17.00 InvalidCardNumber Test: Invalid card number returned by gateway
4444444444444448 14.00 AvsVerificationFailed Test: Avs verification failed
4444444444444448 18.00 Call Test: Issuer wants voice contact with cardholder
4444444444444448 19.00 NoProcessorResponse Test: No response from Processor

Bank Account Test Data

You can use the following EFT data for testing purposes.

Account Number Routing Number Account Type
123456789 121042882 Checking

Use the following bank account number and amount combination to simulate different API response codes.

Test Data for Credit and Debit transaction types.
Account Number Amount Response Code Description
1234567890 $0.00 Success Test: Successfully saved
1234567890 $1.00 Success Test: Transaction approved
1234567890 $2.00 ACHTransactionFailed Test: Not able to process bank account payment
1234567890 $3.00 GatewayInternalError Test: System is down
1234567890 $4.00 NoProcessorResponse Test: No response from Processor
Test Data for Void and Refund transaction types. You can only void or refund an already existing transaction.
Account Number Amount Response Code Description
1234567890 $11.00 ACHTransactionFailed Test: Not able to process bank account payment
1234567890 $12.00 GatewayInternalError Test: System is down
1234567890 $13.00 NoProcessorResponse No response from Processor

You can use the following EFT data to simulate Bank Account Validation response codes.

For testing, any valid routing number shall be used. The results will depend on bank account number.
Account Number Response Code Description
1234567890 Success Test: Charge approved
2234567890 InvalidAccountNumber Test: Invalid Account Number
3234567890 InvalidRoutingNumber Test: Invalid Routing Number
4234567890 GatewayInternalError Test: System is down