Summary

This document describes how to integrate the One Inc’s PortalOne Javascript Library into an existing web based 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

Browsers Compatibility

We support the latest versions of the following browsers and platforms. On Windows, we support Internet Explorer 10+. Support of older verions of Internet Explorer may be available at the time of contract negotiation. More specific support information is provided below.

Chrome Firefox Internet Explorer Safari
Android Supported Supported N/A N/A
iOS Supported N/A N/A Supported
Mac OS X Supported Supported N/A Supported
Windows Supported Supported Supported Not Supported

Embedded Payment Form

Plugin dependencies

jQuery library is required to display the modal. Add a script tag to a web page like the one in the following example:

<script src="https://code.jquery.com/jquery-2.2.1.min.js" type="text/javascript"></script>

Loading plugin

To load the One Inc PortalOne JavaScript API, use a script tag like the one in the following example:

<script async defer src="https://stgportalone.processonepayments.com/GenericModal/Cdn/PortalOne.js" type="text/javascript"></script>

The URL contained in the script tag is the location of a JavaScript file that loads all of the symbols and definitions you need to use the PortalOne™ JavaScript API. The async attribute instructs the browser to render the rest of your website while the PortalOne JavaScript API loads. When the API is ready, it will trigger a corresponding event as described in the Events section below.

Plugin initialization

For the modal to display on a web page, you must reserve a spot for it. Commonly you do this by creating a named div element and obtaining a reference to this element in the browser's document object model (DOM).

<div id="portalOneContainer"></div>

Getting Session Id

The next thing you should do before initiating your client side invocation is to obtain a Session Id from the PortalOne API. This step establishes an additional server to server handshake which significantly increases security of every subsequent operation.

In order to complete your integration 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 Id is required. If you do not have your PortalOne Authentication Key, please feel free to reach out to us and we can issue one.

POST https://stgportalone.processonepayments.com/GenericModal/SessionKey/Create

Get Session Id Request

Field Name Description Type Note
PortalOneAuthenticationKey Unique Identifier for the modal template. string Required
ProcessOneAuthenticationKey Unique identifier for ProcessOne Instance. Providing a value will allow the modal to be used for multiple ProcessOne Instances. string Optional field. If a value is not present, the system will use the ProcessOneAuthenticationKey that configured to the PortalOneAuthenticationKey.
Request Example:
{
    "PortalOneAuthenticationKey": "AuthenticationKey",
    "ProcessOneAuthenticationKey": "ProcessOneAuthenticationKey"
}

Get Session Id Response

Field Name Description Type
SessionKey Unique Session Id returned from PortalOne. Valid for one operation string
Response Example:
{
  "IsSuccessful":true,
  "SessionKey":"345a0fc6-e46c-4cc3-ada7-f4629d6b3f5e"
}

Embedded Form API

Nearly all Embedded Form functionality can be enabled and configured through HTML by simply utilizing data attributes. Be sure to only use one set of data attributes on a single element (e.g., you cannot open a save and credit card modal from the same button).

  • Making a payment

    The following example demonstrates how to start a payment process using HTML data attributes:

    <button type="button"
      data-toggle="portalone"
      data-method="makePayment"
      data-option-payment-category="CreditCard"
      data-option-fee-context="PaymentWithFee"
      data-option-amount-context="SelectOrEnterAmount"
      data-option-min-amount-due="12.00"
      data-option-account-balance="120.00"
      data-option-billing-zip="95630"
      data-option-billing-address-street="602 Coolidge Dr., Folsom, CA"
      data-option-policy-holder-name="John Smith"
      data-option-client-reference-data1="POL330701-02"
      data-option-confirmation-display="true"
      data-option-save-option="Save"
      data-option-account-group-code="FallsLake"
      data-option-token="ed8dc0a5-686e-4836-854c-3dd1dcea1111"
      data-option-acknowledgment-required="true"
      data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Make a payment</button>
    

    You can also invoke the functions in the library directly by writing JavaScript. The following example calls the same function as the example above. Important Note: In order to get payment results, you must wire up to the events exposed by the library.

    $('#portalOneContainer').portalOne();
        $('#portalOneContainer').data('portalOne')
        .makePayment({
            'paymentCategory': 'CreditCard',
            'feeContext': 'PaymentWithFee',
            'amountContext': 'SelectOrEnterAmount',
            'minAmountDue': '12.00',
            'accountBalance': '120.00',
            'billingZip': '95630',
            'billingAddressStreet': '602 Coolidge Dr., Folsom, CA',
            'policyHolderName': 'John Smith',
            'clientReferenceData1': 'POL330701-02',
            'confirmationDisplay': 'true',
            'saveOption': 'Save',
            'accountGroupCode': 'FallsLake',
            'token': 'ed8dc0a5-686e-4836-854c-3dd1dcea1111',
            'acknowledgmentRequired': 'true',
            'sessionId': 'Your Session Id From Previous Step'
        });
    
  • Saving a payment method

    The following example demonstrates how to start a save payment method process using HTML data attributes:

    <button type="button"
      data-toggle="portalone"
      data-method="savePaymentMethod"
      data-option-payment-category="CreditCard"
      data-option-billing-zip="95630"
      data-option-billing-address-street="602 Coolidge Dr., Folsom, CA"
      data-option-policy-holder-name="John Smith"
      data-option-client-reference-data1="POL330701-02"
      data-option-confirmation-display="true"
      data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Save a payment</button>
    

    Starting a save payment method process using a Programmatic JavaScript API approach. The following example calls the same function as the example above.

    portalOne.savePaymentMethod({
      'paymentCategory': 'CreditCard',
      'billingZip': '95630',
      'billingAddressStreet': '602 Coolidge Dr., Folsom, CA',
      'policyHolderName': 'John Smith',
      'clientReferenceData1': 'POL330701-02',
      'confirmationDisplay': 'true',
      'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce'
    });
    

Request Objects

In order to succesfully load the PortalOne modal window, you need to pass a proper data object to PortalOne plug-in. If you are using the HTML attributes approach then each required field of the data object must be represented by a corresponding attribute. For the Programmatic JavaScript API approach, the data object is a simple JSON object. If any of the required fields are not included in the data object, the PortalOne API will trigger an error event.

How to map data object fields to HTML attributes.

We use Camel case as our naming convention. In order to map any of the data object fields to the proper HTML attribute, replace the Camel case name of the field with lowercase words delimited by a dash (-) and prefix it with data-option-. For example: a camelCaseFieldName would map to data-option-camel-case-field-name.

  • Request Data Object

    Here you can find a detailed explanation of every field in the data object that is required to load a PortalOne modal window. If you are using HTML attributes, see How to map data object fields to HTML attributes .

    Field Name Description Type Note
    sessionId Unique identifier acquired from PortalOne Api. Session Id is only valid for a single operation. Once that operation is completed a new Session Id must be acquired. string Required
    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. Make payment operations only
    amountContext Indicates if the user will be able to set the payment amount and if so, which options will be provided. AmountContext Optional. Make payment operations only
    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. Applicable to Make payment operations only.
    confirmationDisplay Indicates whether the flow for the requested operation will display a final confirmation screen upon the completion of the primary operation. Boolean Optional, if not sent default will be true
    referenceNumber 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. string Obsolete
    minAmountDue The minimum amount that is due for a policy. Must be greater than zero. number Required. Make payment operations only
    accountBalance The outstanding balance for the policy. number Required. Make payment operations only
    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. Card make payment operation only
    policyHolderName Name that will be linked to the payment. The value will be pre-populated on the form if provided. string 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 for all make payment operations
    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
    acknowledgmentRequired Indicates whether receiving of Payment Complete Event have to be confirmed by calling code. Boolean Optional, if not sent default will be false
  • Payment Category

    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 NameDescriptionType
    CreditCard

    Specifies a Credit/Debit card operation

    string

    ECheck

    Specifies a bank account operation

    string

    UserSelect

    Allows the user to select the payment type. This value is not support with percentage based processing fees.

    string

  • Fee Context

    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 NameDescriptionType
    PaymentWithFee

    Specifies that a fee will be added to the payment amount

    string

    PaymentWithoutFee

    Specifies that the payment will be processed without any additional fee

    string

  • Amount Context

    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 NameDescriptionType
    AmountDueOnly

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

    string

    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

    string

    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

    string

    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

    string

  • Save Option

    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 NameDescriptionType
    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

    string

    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

    string

    DoNotSave

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

    string

Events

The PortalOne provides custom events for most plugins’ unique actions. You can attach and detach event handler functions using standard JavaScript API. The PortalOne library declares the following events:

  • Modal Load Event

    Code: portalOne.load
    Occurs when modal dialog is loaded.
    Example:
    $('#portalOneContainer')
        .on('portalOne.load', function() {
            console.log(new Date() + ' portalOne.load');
        });
  • Modal Unload Event

    Code: portalOne.unload
    Occurs when modal dialog is unloaded.

    Example:
    $('#portalOneContainer')
        .on('portalOne.unload', function() {
            console.log(new Date() + ' portalOne.unload');
        });
    
  • Code: portalOne.error
    Occurs on errors.
    Example:
    $('#portalOneContainer')
        .on('portalOne.error', function (e, data) {
            console.error(new Date() + ' portalOne.error.', data.Description, data.Details);
        });
    

    Event Object Parameter

    Field Name Description Type
    Description Error description string
    Details Collection of error messages Array of Array of string
    Event Object Example:
    {
      "Description": "There are validation errors",
      "Details": {
        "paymentCategory": [
          "The paymentCategory is a required field"
        ],
       "paymentUid": [
          "Incorrect format"
        ]
      }
    }
  • Payment Complete Event

    Code: portalOne.paymentComplete
    Occurs when payment is successfully completed.
    Example:
    $('#portalOneContainer')
        .on('portalOne.paymentComplete', function(e, data) {
            console.info(
                new Date() + ' portalOne.paymentComplete. Transaction id is ',
                data.transactionId
            );
    
            if(data.acknowledge){
                data.acknowledge();
            }
        });
    

    Event Object Parameter

    Field/Function Name Description Type
    cardType Will be returned for payments with PaymentCategory of creditCard only. Returns the card type that was processed. string
    accountType Will be returned for payments with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string
    bankName Will be returned for payments with PaymentCategory of eCheck only. 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
    holderZip Will be returned for payments with PaymentCategory of creditCard only. Returns zip code of card holder passed back from billingZip on request. string
    authCode Will be returned for payments with PaymentCategory of creditCard only. Returns authorization code provided by issuing bank. string
    cardExpirationMonth Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration month. number
    cardExpirationYear Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration year. number
    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. string
    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
    sessionId Unique identifier echoed back from call to a PortalOne operation. string
    paymentAmount The premium payment amount excluding any convenience fees. number
    convenienceFee The convenience fee applied to premium amount. number
    totalPaymentAmount The total payment amount that was processed including convenience fees. number
    lastFourDigits Last 4 digits of the card or bank account string
    timezone Time zone code. (PST, EST) string
    transactionDate Date Stamp of the payment Date
    paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. string
    acknowledge() Callback which should be called to confirm event receiving. This callback is available only for payment request with acknowledgmentRequired=true. Function
    Credit Card PaymentInfo Object Example:
    {
      "cardType": "Visa",
      "customerName": "One Inc",
      "holderZip": "95630",
      "authCode": "TEST0000",
      "cardExpirationYear": 2021,
      "cardExpirationMonth": 4,
      "transactionId": "3",
      "batchNumber": 2,
      "sessionId": "807e341c-3e18-456e-a5b4-678ed232011d",
      "paymentAmount": 10,
      "convenienceFee": 5,
      "totalPaymentAmount": 15,
      "lastFourDigits": "1111",
      "timeZone": "PST",
      "transactionDate": "01/25/2018 03:38:07 PM",
      "tokenId": "c99c5aca-16c8-491f-ab10-45bac17a1111",
      "paymentCategory": "CreditCard",
      "acknowledgmentRequired": "true"
    }
    
    ECheck PaymentInfo Object Example:
    {
      "accountType": "Checking",
      "bankName": null,
      "customerName": "One Inc",
      "transactionId": "4",
      "batchNumber": 2,
      "sessionId": "58e39506-6651-4d58-b431-5f7dd3de1adb",
      "paymentAmount": 10,
      "convenienceFee": 5,
      "totalPaymentAmount": 15,
      "lastFourDigits": "1111",
      "timeZone": "PST",
      "transactionDate": "01/25/2018 03:38:07 PM",
      "tokenId": "f3e9e1e6-2562-46e8-ba74-3fcdd658dc8f",
      "paymentCategory": "ECheck",
      "acknowledgmentRequired": "true"
    }
    
  • Payment Canceled Event

    Code: portalOne.paymentCanceled
    Occurs when payment operation is canceled.
    Example:
    $('#portalOneContainer')
        .on('portalOne.paymentCanceled', function() {
            console.log(new Date() + ' portalOne.paymentCanceled');
        });
    
  • Save Complete Event

    Code: portalOne.saveComplete
    Occurs when payment method was successfully saved.
    Example:
    $('#portalOneContainer')
        .on('portalOne.saveComplete', function(e, data) {
            console.info(
                new Date() + ' portalOne.saveComplete. Token Id is ',
                data.tokenId
            );
        });
    

    Event Object Parameter

    Field Name Description Type
    cardType Will be returned for operations with PaymentCategory of creditCard only. Returns the card type that was processed. string
    cardExpirationMonth Will be returned for operations with PaymentCategory of creditCard only. Returns the card expiration month. number
    cardExpirationYear Will be returned for operations with PaymentCategory of creditCard only. Returns the card expiration year. number
    accountType Will be returned for operations with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string
    bankName Will be returned for payments with PaymentCategory of eCheck only. 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
    holderZip Will be returned for operations with PaymentCategory of creditCard only. Returns zip code of cardholder passed back from billingZip on request. string
    sessionId Unique identifier echoed back from call to a PortalOne operation. 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
    timezone Time zone code. (PST, EST) string
    transactionDate Date Stamp of the payment Date
    paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. string
    Credit Card SavePaymentInfo Object Example:
    {
      "cardType": "Visa",
      "cardExpirationMonth": 3,
      "cardExpirationYear": 2022,
      "customerName": "One Inc",
      "holderZip": "95630",
      "sessionId": "58e39506-6651-4d58-b431-5f7dd3de1adb",
      "tokenId": "598ae221-2720-4382-88c7-8b3b46921111",
      "lastFourDigits": "1111",
      "transactionDate": "01/26/2018 02:00:43 PM",
      "timeZone": "PST",
      "paymentCategory": "CreditCard"
    }
    
    ECheck SavePaymentInfo Object Example:
    {
      "accountType": "Checking",
      "bankName": "JPMORGAN CHASE",
      "customerName": "One Inc",
      "sessionId": "58e39506-6651-4d58-b431-5f7dd3de1adb",
      "tokenId": "4f9ca1b3-4631-4253-9b1c-8e1fe1ff6b64",
      "lastFourDigits": "1111",
      "transactionDate": "01/26/2018 02:00:43 PM",
      "timeZone": "PST",
      "paymentCategory": "ECheck"
    }
    
  • Save Canceled Event

    Code: portalOne.saveCanceled
    Occurs when save operation is canceled.
    Example:
    $('#portalOneContainer')
        .on('portalOne.saveCanceled', function() {
            console.log(new Date() + ' portalOne.saveCanceled');
        });
    

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

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