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

One Inc supports latest versions of the browsers and platforms listed below. Support for earlier browsers may be available at the time of contract negotiation. More specific information is provided below.

You might be able to use other browsers without encountering errors. Our goal is to provide the best experience to majority of our customers and we recommend using the browsers listed below for optimal experience.

Chrome Firefox Internet Explorer Safari Microsoft Edge
Android Supported Supported N/A N/A N/A
iOS Supported N/A N/A Supported N/A
Mac OS X Supported Supported N/A Supported N/A
Windows Supported Supported Supported Not Supported 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/Api/Api/Cdn/GenericModalV2/assets/js/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 portalOne.load 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). The ID of this element MUST be portalOneContainer, the plugin is searching for a slot by this ID.

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

GET https://stgportalone.processonepayments.com/Api/Api/Session/Create

Get Session Id Request

Parameter Name Description Type Note
PortalOneAuthenticationKey Unique Identifier for the modal template. string Required
Role The user role with which the modal should be opened. UserRole Optional field
TargetOperation Unique operation identifier TargetOperation Optional field. The type of operation for which the Session Id will be used.
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.
CustomerId Unique customer identifier string Optional. If a customer ID is provided, it will be saved in the session. In this case, when any API method is called, the equality of passed CustomerId to CustomerId stored in the session will be checked. If the IDs are different, an error will be thrown.

Target Operation

Operation NameDescriptionType
makePayment

Starts a payment process

string

quickPay

Starts a quick payment process

string

savePaymentMethod

Starts a save payment method process

string

managePaymentMethods

Launching a Manage Payment Methods

string

manageNotifications

Launching a Manage Notifications

string

enrollAutoPay

Launching an Enroll AutoPay tool

string

Request Example:
        https://stgportalone.processonepayments.com/Api/Api/Session/Create?portalOneAuthenticationKey=928DA7CD-7B57-4697-BA84-F50518196329&targetOperation=quickPay
                

Get Session Id Response

Field Name Description Type Note
ResponseCode Operation response code string

ResponseCode should be used for programmatic handling of the response.

ResponseMessage Error description string

ResponseMessage is human readable, subject to change and should not be used for programmatic handling of the response.

PortalOneSessionKey Unique Session Id returned from PortalOne. Valid for one operation string
Response Example:
{
    "ResponseCode": "Success",
    "PortalOneSessionKey": "5BB90EE4-19A2-43E4-9DCF-835579D3AF7C"
}

Creating Account

Payment Widget provides the ability to use a wallet for making payments.

First you need to create an account for the customer. To do this call the account creation method from the PortalOne API which will return a unique identifier of the customer. If you pass this identifier to the makePayment method, the wallet feature will be activated. Pass the identifier to the savePayment method to add a new payment method to the wallet.

For each customer you need to create an account only once. After that you may save the generated identifier in your system and pass it as parameter to savePaymentMethod, managePaymentMethods and makePayment methods whenever you call them.

If the CreateAccount method is called for the same customer with the same ExternalCustomerId again, new customer account and new wallet will not be created and the unique identifier created at first call will be returned.

POST https://stgportalone.processonepayments.com/Api/Api/Customer/CreateAccount

Create Account Request

Field Name Description Type Note
PortalOneAuthenticationKey Authentication key string Required
ExternalCustomerId An identifier of a customer in your system. You can use ExternalCompanyContactId or ExternalIndividualId fields from the response by the https://stgportalone.processonepayments.com/ClaimsPay/Api/Account/GetInfo method string Optional. If in your system there is a unique customer identifier, you may pass it. It will be saved in our system and can be used for retrieving information in the future.
CustomerName Customer name string Optional
Request Example:
{
    "PortalOneAuthenticationKey": "5BB90EE4-19A2-43E4-9DCF-835579D3AF7C",
    "ExternalCustomerId": "someIdentifier",
    "CustomerName": "John Smith"
}

Create Account Response

Field Name Description Type Note
ResponseCode Operation response code string

ResponseCode should be used for programmatic handling of the response.

ResponseMessage Error description string

ResponseMessage is human readable, subject to change and should not be used for programmatic handling of the response.

CustomerId Generated Customer identifier string
Response Example:
{
    "ResponseCode": "Success",
    "CustomerId": "058910F9-B228-456B-AF3E-3D3FE6DD7B28"
}

PortalOne™ JavaScript Plugin Usage

In order to get result of the operation, you must wire up to the Events exposed by the plugin before execution of the operation.

There are several ways to deal with PortalOne™ JavaScript API. They'll be explained on the Making a payment for single policy example

  • Invoking functions of the PortalOne™ JavaScript API directly.

    Obtain reference to element with id='#portalOneContainer' in the browser's document object model (DOM) and initialize PortalOne™ JavaScript API by invoking portalOne() function. After that you can call desired function.
    For example, let's make a payment:

    • First of all, initialize script:

                  $('#portalOneContainer').portalOne();
              

    • After that you can directly invoke a function to open modal (on Make Payment flow in this case) and use proper Request Object as parameter of the function:

      $('#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',
              'customerId': 'e3a6fa12-d448-4686-a5ff-7f821f0b0c5d',
              'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce'
      });
      

  • Using Embedded Form functionality.

    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).

    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.

    Let's make a payment, again:

    <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-customer-id="e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
        data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Make a payment</button>
    

  • Using Access Token functionality.

    This way provides much greater security, but requires more communications and operations.
    Below is the sequence of steps for using an access token:

    • Create Access Token by calling the PortalOne API. It is server-side operation, so do not try to it from web page.

      There is single endpoint for creation of all types of Access Tokens, only parameters differs.

      See more about Access Token

      POST https://stgportalone.processonepayments.com/Api/Api/AccessToken/Create

      Create Access Token Request

      Parameter Name Description Type Note
      PortalOneAuthenticationKey Unique Identifier for the modal template. string Required
      Type 'Client' token used to start modal, 'Server' token used for redirection AccessTokenType Required. If access token will be used to open modal, value should be "Client"
      Payload JSON which contains operations essence. Changes according to operation and other parameters. AccessTokenPayload Required, depends on operation
      ExpirationDate Moment when token will expires. string Optional

      Payload of Access Token relies of operation which token is creating for, it is a special case of Access Token Payload related to modal operations.

      Whatever operation is selected, payload JSON should contains 'operation' field.

      Operation

      PortalOne requires you to provide a type of operation which will associated with created access token.

      Operation NameDescriptionType
      makePayment

      Starts a payment process

      string

      quickPay

      Starts a quick payment process

      string

      savePaymentMethod

      Starts a save payment method process

      string

      managePaymentMethods

      Launching a Manage Payment Methods

      string

      manageNotifications

      Launching a Manage Notifications

      string

      enrollAutoPay

      Launching an Enroll AutoPay tool

      string

      How to map data object fields to AccessTokenPayload JSON.

      In order to map any of the data object to proper JSON select Operation type and put it into "operation" field. Other fields of JSON has the same names as data object fields and have same behavior, except of sessionId, displayMode and allowClosing. SessionId useless in Access Token stored at server side, cause each usage of Access Token requires new sessionId. displayMode and allowClosing can be optionally provided in open modal method (see example below).

      Access Token payload for Make Payment Operation with such parameters as above:

                  { 
         "operation":"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",
         "customerId":"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
      }
              

    • Deliver that token to your frontend.

    • Next substeps looks similar with direct invocation of API functions:

      • Initialize script:

                    $('#portalOneContainer').portalOne();
                

      • Directly invoke a method to open modal (workflow of modal is depends on token's payload):

        $('#portalOneContainer').data('portalOne')
            .run({
                'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce',
                'accessTokenId': 'ff111428-f868-482c-b1fa-871ba4091d01',
                'displayMode': 'Modal',
                'allowClosing': "true"
            });
        


  • Making a payment

    The following example demonstrates how to start a payment process by invoking the functions in the library directly by writing JavaScript. Important Note: In order to get payment results, you must wire up to the events exposed by the library.

    Making a payment for single policy:

                $('#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', 'customerId': 'e3a6fa12-d448-4686-a5ff-7f821f0b0c5d', 'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce' });

    Making a payment for multiple policies:

            
                $('#portalOneContainer').portalOne();

    $('#portalOneContainer').data('portalOne') .makePayment({ 'paymentCategory': 'CreditCard', 'amountContext': 'SelectOrEnterAmount', 'billingZip': '95630', 'billingAddressStreet': '602 Coolidge Dr., Folsom, CA', 'confirmationDisplay': 'true', 'saveOption': 'Save', 'token': 'ed8dc0a5-686e-4836-854c-3dd1dcea1111', 'acknowledgmentRequired': 'true', 'customerId': 'e3a6fa12-d448-4686-a5ff-7f821f0b0c5d', 'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce', 'policies':[ { 'feeContext': 'PaymentWithFee' 'minAmountDue': '12.00', 'accountBalance': '120.00', 'policyHolderName': 'John Smith', 'accountGroupCode': 'FallsLake', 'clientReferenceData1': 'POL330701-01', 'clientReferenceData2': 'someData2', 'clientReferenceData3': 'someData3', 'clientReferenceData4': 'someData4', 'clientReferenceData5': 'someData5' }, { 'feeContext': 'PaymentWithFee' 'minAmountDue': '12.00', 'accountBalance': '120.00', 'policyHolderName': 'John Smith', 'accountGroupCode': 'FallsLake', 'clientReferenceData1': 'POL330701-02', 'clientReferenceData2': 'someData2', 'clientReferenceData3': 'someData3', 'clientReferenceData4': 'someData4', 'clientReferenceData5': 'someData5' } ] });

    You can also start a payment process using HTML data attributes. The following example calls the same function as the example above, see How to map data object fields to HTML 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-customer-id="e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
        data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Make a payment</button>
    

    And also you can create Access Token for the operation. Type of Operation is makePayment. The following example creates Access Token which will expands to the same function as the example above, see How to map data object fields to AccessTokenPayload JSON :

    Access Token for making a payment for single policy

                { 
       "operation":"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",
       "customerId":"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
    }
            

    Access Token for making a payment for multiple policies

                {
        "operation":"makePayment",
        "paymentCategory": "CreditCard",
        "amountContext": "SelectOrEnterAmount",
        "billingZip": "95630",
        "billingAddressStreet": "602 Coolidge Dr., Folsom, CA",
        "confirmationDisplay": "true",
        "saveOption": "Save",
        "token": "ed8dc0a5-686e-4836-854c-3dd1dcea1111",
        "acknowledgmentRequired": "true",
        "customerId": "e3a6fa12-d448-4686-a5ff-7f821f0b0c5d",
        "policies":[
                {
                    "feeContext": "PaymentWithFee",
                    "minAmountDue": "12.00",
                    "accountBalance": "120.00",
                    "policyHolderName": "John Smith",
                    "accountGroupCode": "FallsLake",
                    "clientReferenceData1": "POL330701-01",
                    "clientReferenceData2": "someData2",
                    "clientReferenceData3": "someData3",
                    "clientReferenceData4": "someData4",
                    "clientReferenceData5": "someData5"
                },
                {
                    "feeContext": "PaymentWithFee",
                    "minAmountDue": "12.00",
                    "accountBalance": "120.00",
                    "policyHolderName": "John Smith",
                    "accountGroupCode": "FallsLake",
                    "clientReferenceData1": "POL330701-02",
                    "clientReferenceData2": "someData2",
                    "clientReferenceData3": "someData3",
                    "clientReferenceData4": "someData4",
                    "clientReferenceData5": "someData5"
                }
            ]
    }
            
  • Making a Quick Payment

    Making a payment also can be provided through Quick Pay Function. The following example demonstrates how to start a quick payment process by invoking the functions in the library directly by writing JavaScript. Important Note: In order to get payment results, you must wire up to the events exposed by the library.

    Making a quick payment

                $('#portalOneContainer').portalOne();

    $('#portalOneContainer').data('portalOne') .quickPay({ 'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce' });

    You can also start a quick payment process using HTML data attributes. The following example calls the same function as the example above, see How to map data object fields to HTML attributes :

    <button type="button"
        data-toggle="portalone"
        data-method="quickPay"
        data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Make a quick payment</button>
    

    And also you can create Access Token for the operation. Type of Operation is quickPay. The following example creates Access Token which will expands to the same function as the example above, see How to map data object fields to AccessTokenPayload JSON :

    Access Token for making a quick payment

                { 
       "operation":"quickPay"
    }
            
  • Saving a payment method

    The following example demonstrates how to start a save payment method process using a Programmatic JavaScript API approach:

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

    Starting a save payment method process using HTML data attributes. The following example calls the same function as the example above, see How to map data object fields to HTML 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-customer-id="e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
      data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Save a payment</button>
    

    And also you can create Access Token for the operation. Type of Operation is savePaymentMethod. The following example creates Access Token which will expands to the same function as the example above, see How to map data object fields to AccessTokenPayload JSON :

                { 
       "operation":"savePaymentMethod",
       "paymentCategory":"CreditCard",
       "billingZip":"95630",
       "billingAddressStreet":"602 Coolidge Dr., Folsom, CA",
       "policyHolderName":"John Smith",
       "clientReferenceData1":"POL330701-02",
       "confirmationDisplay":"true",
       "customerId":"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
    }
            
  • Manage payment methods

    The following example demonstrates how to start a manage payment methods process using a Programmatic JavaScript API approach:

    portalOne.managePaymentMethods({
      'customerId': 'e3a6fa12-d448-4686-a5ff-7f821f0b0c5d',
      'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce'
    });
    

    Starting a manage payment methods process using HTML data attributes. The following example calls the same function as the example above, see How to map data object fields to HTML attributes

    <button type="button"
      data-toggle="portalone"
      data-method="managePaymentMethods"
      data-option-customer-id="e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
      data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Manage payment methods</button>
    

    And also you can create Access Token for the operation. Type of Operation is managePaymentMethods. The following example creates Access Token which will expands to the same function as the example above, see How to map data object fields to AccessTokenPayload JSON :

                { 
       "operation":"managePaymentMethods",
       "customerId":"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
    }
            
  • Manage notifications

    Starting a manage notifications process using Access Token for the operation. Type of Operation is manageNotifications. The following example creates Access Token which will expands to the same function as the example above, see How to map data object fields to AccessTokenPayload JSON :

                {
        "operation" : "manageNotifications",
        "customerId": "e3a6fa12-d448-4686-a5ff-7f821f0b0c5d",
        "userRole": "insured"
    }
            

    or

                {
        "operation" : "manageNotifications",
        "externalCustomerId": "some external customer ID",
        "userRole": "insured"
    }
            

    Deliver that token to your frontend.

    Directly invoke a method to open manage notifications modal:

    portalOne.run({
        'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce',
        'accessTokenId': 'ff111428-f868-482c-b1fa-871ba4091d01'
        });
    

    Also you can starting a manage notifications process using HTML data attributes. The following example calls the same function as the example above, see How to map data object fields to HTML attributes

    
        <button type="button"
        data-toggle="portalone"
        data-method="manageNotifications"
        data-option-user-role="insured"
        data-option-customer-id="e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
        data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Manage notifications</button>
    

    or

    
        <button type="button"
        data-toggle="portalone"
        data-method="manageNotifications"
        data-option-user-role="insured"
        data-option-external-customer-id="some external customer ID"
        data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Manage notifications</button>
    
    For using manage notifications modal for ClaimsPay users, you must to Create new customer account calling the CreateAccount method using ExternalCompanyContactId or ExternalIndividualId fields from the response by the https://stgportalone.processonepayments.com/ClaimsPay/Api/Account/GetInfo method as ExternalCustomerId.
  • Enroll AutoPay

    The following example demonstrates how to launch an Enroll AutoPay tool using a Programmatic JavaScript API approach:

    portalOne.enrollAutoPay({
      'customerId': 'e3a6fa12-d448-4686-a5ff-7f821f0b0c5d',
      'clientReferenceData1': 'POL330701-02',
      'paymentCategory': 'CreditCard',
      'feeContext': 'PaymentWithFee'
      'policyHolderName': 'John Smith',
      'email': [email protected],
      'autoPayOptions': [{'frequency':'Monthly','amount':100,'numberOfInstallments':12,'withdrawalDates':[1,2,3,4,5]},{'frequency':'Quarterly','amount':300,'numberOfInstallments':6,'withdrawalDates':[5,6,7,8,9,10]}],
      'autoPayEngineType': 'InstallmentsEngine',
      'sessionId': 'a3ed1852-642b-4d0c-a5aa-a89b575af4ce'
    });
    

    Launching an Enroll AutoPay tool using using HTML data attributes. The following example calls the same function as the example above, see How to map data object fields to HTML attributes

    <button type="button"
      data-toggle="portalone"
      data-method="enrollAutoPay"
      data-option-customer-id="e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
      data-option-client-reference-data1="POL330701-02"
      data-option-payment-category="CreditCard"
      data-option-fee-context="PaymentWithFee"
      data-option-policy-holder-name="John Smith"
      data-option-email="[email protected]"
      data-option-autopay-options="[{'frequency':'Monthly','amount':100,'numberOfInstallments':12,'withdrawalDates':[1,2,3,4,5]},{'frequency':'Quarterly','amount':300,'numberOfInstallments':6,'withdrawalDates':[5,6,7,8,9,10]}]"
      data-option-autopay-engine-type="Carrier"
      data-option-external-scheduler-endpoint="https://example.com/autopay/installmentPlanChanged"
      data-option-session-id="a3ed1852-642b-4d0c-a5aa-a89b575af4ce">Enroll AutoPay</button>
    

    And also you can create Access Token for the operation. Type of Operation is enrollAutoPay. The following example creates Access Token which will expands to the same function as the example above, see How to map data object fields to AccessTokenPayload JSON :

                { 
       "operation":"enrollAutoPay",
       "customerId":"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d",
       "clientReferenceData1":"POL330701-02",
       "paymentCategory":"CreditCard",
       "feeContext":"PaymentWithFee",
       "policyHolderName":"John Smith",
       "email":"[email protected]",
       "autoPayEngineType": "InstallmentsEngine",
       "autoPayOptions":[ 
          { 
             "frequency":"Monthly",
             "amount":100,
             "numberOfInstallments":12,
             "withdrawalDates":[ 
                1,
                2,
                3,
                4,
                5
             ]
          },
          { 
             "frequency":"Quarterly",
             "amount":300,
             "numberOfInstallments":6,
             "withdrawalDates":[ 
                5,
                6,
                7,
                8,
                9,
                10
             ]
          }
       ]
    }
            

Request Objects

In order to successfully 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.

Request Data Objects

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 .
If you are using Access Token feature, see How to map data object fields to AccessTokenPayload JSON .

  • Make Payment Request Data Object

    You can load modal window in case to start payment process in two different workflows:


    Also, it is possible to save the payment method while making a payment. The Event will not be different from the event caused by separated call of Saving a payment method. The parameters for Saving a payment method request are mapped from Make payment request object by the names of their fields. In this case [ignoredMultiple] indicates that the field value will be taken from the first item of policies field array instead of the Make payment request object itself.


    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 [ignoredMultiple]
    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. 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
    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
    minAmountDue The minimum amount that is due for a policy. Must be greater than zero. number Required [ignoredMultiple]
    accountBalance The outstanding balance for the policy. number Required [ignoredMultiple]
    policyHolderName Name that will be linked to the payment. The value will be pre-populated on the form if provided. string Optional [ignoredMultiple]
    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 [ignoredMultiple]
    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 [ignoredMultiple]
    clientReferenceData2 An External TransactionId value. The value will be searchable in the transaction search report. string Optional [ignoredMultiple]
    clientReferenceData3 Location data such as the office the transaction originated. The value will be searchable in the transaction search report. string Optional [ignoredMultiple]
    clientReferenceData4 Additional information with the transaction. The value will be displayed in the transaction details. string Optional [ignoredMultiple]
    clientReferenceData5 Source account information. Additional reference number such as an account number. The value will be searchable in the transaction search report. string Optional [ignoredMultiple]
    token Token that identifies credit card or bank account. string Optional
    acknowledgmentRequired Indicates whether receiving of Payment Complete Event has to be confirmed by calling code. Available by request and needs to be enabled on the server side. A timeout duration can be requested and equals 60 seconds.
    If this field is equals to true, an obsolete acknowledgment must be called to finish Making a payment operation successfuly.
    Boolean Optional. If not sent default will be false. Must be enabled on client and server side, or else an error will show for the client. Obsolete in modal 2.0, will be replaced by server side postbacks.
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. string Optional
    policies Collection of Policy Details Data Object. Payment workflow will be started for all policies at once if there is more than one item, or like for a single policy if there is a single item.
    Restrictions:
    -collection should contain less or equal than 5 items
    -clientReferenceData1 should be unique for each item
    -payment workflow will not allow user to change payment amount
    Policy Details Optional,
    if contains at least one item, fields marked with [ignoredMultiple] will be ignored
    displayMode Allows to specify how the dialog should be displayed. Display Mode Optional, if not sent default will be Modal
    allowClosing Allows to specify if dialog can be closed. Be careful when using values displayMode="Modal" and allowClosing="false" together. With this combination the modal window cannot be closed. It should be a well-considered case. Boolean Optional, if not sent default will be true for displayMode="Modal" and false for displayMode="Inline"
  • Save Payment Method Request Data Object

    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
    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
    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 operations only
    policyHolderName Name that will be linked to the payment. The value will be pre-populated on the form if provided. 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
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. string Optional
    displayMode Allows to specify how the dialog should be displayed. Display Mode Optional, if not sent default will be Modal
    allowClosing Allows to specify if dialog can be closed. Be careful when using values displayMode="Modal" and allowClosing="false" together. With this combination the modal window cannot be closed. It should be a well-considered case. Boolean Optional, if not sent default will be true for displayMode="Modal" and false for displayMode="Inline"
  • Manage Payment Methods Request Data Object

    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
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. string Required
    displayMode Allows to specify how the dialog should be displayed. Display Mode Optional, if not sent default will be Modal
    allowClosing Allows to specify if dialog can be closed. Be careful when using values displayMode="Modal" and allowClosing="false" together. With this combination the modal window cannot be closed. It should be a well-considered case. Boolean Optional, if not sent default will be true for displayMode="Modal" and false for displayMode="Inline"
  • Manage Notifications Request Data Object

    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. Must be generated with a role field for manage notifications modal. string Required
    customerId Unique customer identifier. Used to access the account subscriptions. Call the CreateAccount method from PortalOne API to acquire the identifier. string one of the fields must be specified - customerId or externalCustomerId
    externalCustomerId An identifier of a customer in your system. You can use ExternalCompanyContactId or ExternalIndividualId fields from the response by the https://stgportalone.processonepayments.com/ClaimsPay/Api/Account/GetInfo method string one of the fields must be specified - customerId or externalCustomerId
    userRole The user role with which the manage notifications modal should be opened. UserRole Required
    displayMode Allows to specify how the dialog should be displayed. Display Mode Optional, if not sent default will be Modal
    allowClosing Allows to specify if dialog can be closed. Be careful when using values displayMode="Modal" and allowClosing="false" together. With this combination the modal window cannot be closed. It should be a well-considered case. Boolean Optional, if not sent default will be true for displayMode="Modal" and false for displayMode="Inline"
  • Enroll AutoPay Request Data Object

    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
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. 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
    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
    policyHolderName Name that will be linked to the payment. The value will be pre-populated on the form if provided. string Optional
    email Email which will be used for notifications string Optional
    autoPayOptions Collection of AutoPay Options AutoPay Options Required
    autoPayEngineType This field will define who will control the AutoPay Payment Plan generation and recurring scheduling - whether it is Carrier Controlled or InstallmentsEngine controlled. Defaulted to "InstallmentsEngine". AutoPay Engine Type Optional
    externalSchedulerEndpoint This field value should only be sent when autoPayEngineType = "Carrier". This maps to a Carrier System Scheduler Engine endpoint. Digital Payments will then use this endpoint to eventually send user-selected Payment Preferences for Auto-Pay Plan creation and scheduling. string Optional
    displayMode Allows to specify how the dialog should be displayed. Display Mode Optional, if not sent default will be Modal
    allowClosing Allows to specify if dialog can be closed. Be careful when using values displayMode="Modal" and allowClosing="false" together. With this combination the modal window cannot be closed. It should be a well-considered case. Boolean Optional, if not sent default will be true for displayMode="Modal" and false for displayMode="Inline"
  • User Role

    PortalOne requires you to provide a user role option in order to determine with what permissions the form should be open.

    Option NameDescriptionType
    Insured

    User role for external Users are Insureds who will use the manage notifications modal to record communication preferences for themselves.

    string

    Claimant

    User role for external Users are Claimants who will use the manage notifications modal to record communication preferences for themselves.

    string

    Agent

    User role for internal Users are a Carrier's representatives. These are Customer Service Representatives - Agents who will use the Modal to record Communication Preferences on behalf of the Insured.

    string

    Adjustor

    User role for internal Users are a Carrier's representatives. These are Customer Service Representatives - Adjustors who will use the Modal to record Communication Preferences on behalf of the Claimant.

    string

  • 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 supported 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

    EnterAmountOnly

    Will allow the user to specify the payment amount by entering a value in a text field. Introduced amount must be greater than zero and less than or equal to accountBalance if it is provided

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

  • Policy Details

    PortalOne let you to provide not only single policy for payment, but also for multiple. Multiple payment should be considered as single operation, but not like batch of separated payments for single policy. Generic part of data stores in Payment Request Data Object, unique part of data related to each particular policy at multiple policies payment workflow stores in Policy Details

    Field Name Description Type Note
    feeContext Indicates whether a fee will be applied to the payment. FeeContext Required
    minAmountDue The minimum amount that is due for a policy. Must be greater than zero. number Required
    accountBalance The outstanding balance for the policy. number Required
    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
    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
  • AutoPay Options

    PortalOne requires you to provide a collection of AutoPay Options objects which are available to setup AutoPay plan. The AutoPay Options field is required for every AutoPay operations. If this field is not included in the request, the PortalOne API will trigger an error event. Each AutoPay Options object have to contain following fields:

    Field Name Description Type Note
    frequency Specifies how often payments should be made. Withdrawal Frequency Required
    amount Payment amount for each installment. number Required
    numberOfInstallments Number of total installments number Required
    withdrawalDates Available dates for withdrawal number Required
  • Withdrawal Frequency

    Option NameDescriptionType
    Monthly

    Payment occurs every month

    string

    Quarterly

    Payment occurs every 3 months

    string

    Semiannually

    Payment occurs every 6 months

    string

    Annually

    Payment occurs every 12 months

    string

  • AutoPay Engine Type

    Option NameDescriptionType
    InstallmentsEngine

    One Inc. will control Auto-Pay via current functionality in InstallmentsEngine.

    string

    Carrier

    Carrier's Billing System will control Auto-Pay Payment Plan creation and scheduling.

    string

  • Display Mode

    Option NameDescriptionType
    Modal

    Modal dialog will be displayed (content of host page will be overlapped).

    string

    Inline

    Dialog will be built into the specified container and will not overlap content of host page.

    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');
        });
    
  • Modal Error Event

    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
            );
        });
    

    PaymentComplete Event Object Parameter

    Payment could be made for single or multiple policies. Content of vary depending on whether it is single payment or multiple. So in table below fields marked with [singleOnly] will be returned only when it is payment for a single policy.

    Field/Function Name Description Type Note
    clientReferenceData1 The reference number that was provided. string [singleOnly]
    cardType Will be returned for payments with PaymentCategory of creditCard only. Returns the card type that was processed. string [singleOnly]
    accountType Will be returned for payments with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string [singleOnly]
    bankName Will be returned for payments with PaymentCategory of eCheck only. Returns the name of a bank associated with a provided account. string [singleOnly]
    customerName Name that was provided with a card or bank account inforamtion. Passed back as Customer Name string [singleOnly]
    holderZip Will be returned for payments with PaymentCategory of creditCard only. Returns zip code of card holder passed back from billingZip on request. string [singleOnly]
    authCode Will be returned for payments with PaymentCategory of creditCard only. Returns authorization code provided by issuing bank. string [singleOnly]
    cardExpirationMonth Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration month. number [singleOnly]
    cardExpirationYear Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration year. number [singleOnly]
    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 [singleOnly]
    batchNumber ProcessOne Batch ID, file identifier. Identifies which batch is associated with a transaction. string [singleOnly]
    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 [singleOnly]
    sessionId Unique identifier echoed back from call to a PortalOne operation. string [singleOnly]
    paymentAmount The premium payment amount excluding any convenience fees. number [singleOnly]
    convenienceFee The convenience fee applied to premium amount. number [singleOnly]
    totalPaymentAmount The total payment amount that was processed including convenience fees. number [singleOnly]
    lastFourDigits Last 4 digits of the card or bank account string [singleOnly]
    timezone Time zone code. (PST, EST) string [singleOnly]
    transactionDate Date Stamp of the payment Date [singleOnly]
    paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. string [singleOnly]
    acknowledgmentRequired Indicates whether receiving of Payment Complete Event have to be confirmed by calling code. Boolean [singleOnly]
    transactions Collection of completed transactions. [Payment Result]

    Payment Result

    Field/Function Name Description Type
    clientReferenceData1 The reference number that was provided. string
    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
    acknowledgmentRequired Indicates whether receiving of Payment Complete Event have to be confirmed by calling code. Boolean
    Credit Card PaymentInfo Object Example for single policy payment:
    {
      "clientReferenceData1": "POL330701-01",
      "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",
      "transactions": [
            {
                "clientReferenceData1": "POL330701-01",
                "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"
            }
       ]
    }
    
    Credit Card PaymentInfo Object Example for multiple policies payment:
    {
        "transactions": [
            {
                "clientReferenceData1": "POL330701-01",
                "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"
            },
            {
                "clientReferenceData1": "POL330701-02",
                "cardType": "Visa",
                "customerName": "One Inc",
                "holderZip": "95630",
                "authCode": "TEST0000",
                "cardExpirationYear": 2021,
                "cardExpirationMonth": 4,
                "transactionId": "3",
                "batchNumber": 2,
                "sessionId": "807e341c-3e18-456e-a5b4-678ed232012d",
                "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 for single policy payment:
    {
      "clientReferenceData1": "POL330701-01",
      "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",
      "transactions": [
            {
              "clientReferenceData1": "POL330701-01",
              "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"
            }
        ]
    }
    
    ECheck PaymentInfo Object Example for multiple policies payment:
    {
        "transactions": [
            {
                "clientReferenceData1": "POL330701-01",
                "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"
            },
            {
                "clientReferenceData1": "POL330701-02",
                "accountType": "Checking",
                "bankName": null,
                "customerName": "One Inc",
                "transactionId": "4",
                "batchNumber": 2,
                "sessionId": "807e341c-3e18-456e-a5b4-678ed232012d",
                "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 before a payment operation is requested (i.e., if an error occurs after a payment request, and after that the user closes modal, event will NOT fire).
    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.

    That event can occurs on successfull execution of Save payment method , and also after saving payment method during execution of Make payment operation .

    Example:
    $('#portalOneContainer')
        .on('portalOne.saveComplete', function(e, data) {
            console.info(
                new Date() + ' portalOne.saveComplete. Token Id is ',
                data.tokenId
            );
        });
    

    Save Payment Complete Result

    Content of Save Payment Complete payload is depends on method, which by that event was produced.

    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 before a save operation is requested (i.e., if an error occurs after a save request, and after that the user closes modal, event will NOT fire).
    Example:
    $('#portalOneContainer')
        .on('portalOne.saveCanceled', function() {
            console.log(new Date() + ' portalOne.saveCanceled');
        });
    
  • AutoPay Enroll Complete Event

    Code: portalOne.enrollAutoPayComplete
    Occurs when AutoPay successfully enrolled.
    Example:
    $('#portalOneContainer')
        .on('portalOne.enrollAutoPayComplete', function() {
            console.log(new Date() + 'portalOne.enrollAutoPayComplete');
        });

    Enroll AutoPay Complete Result

    Content of Enroll AutoPay Complete payload is depends on parameters with which it was produced.

    Field/Function Name Description Type
    sessionId Unique identifier echoed back from call to a PortalOne operation. string
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. string
    clientReferenceData1 The reference number that was provided. 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
    chargeFee Indicates if the payments will are/were processed with or without a fee. boolean
    autoPayEngineType This field will define who will control the AutoPay Payment Plan generation and recurring scheduling - whether it is Carrier Controlled or InstallmentsEngine controlled. Defaulted to "InstallmentsEngine". AutoPay Engine Type
    withdrawalFrequency Specifies how often payments should be made. WithdrawalFrequency
    withdrawalDay Specifies day of month when payments should be made. string
    numberOfInstallments Number of total installments number
    amountPerInstallment Payment amount for each installment. decimal number
    externalSchedulerEndpoint This field value should only be sent when autoPayEngineType = "Carrier". This maps to a Carrier System Scheduler Engine endpoint. Digital Payments will then use this endpoint to eventually send user-selected Payment Preferences for Auto-Pay Plan creation and scheduling. string
    paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. string
    lastFourDigits Last 4 digits of the card or bank account string
    cardType Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card type that will used. string
    holderZip Will be returned for AutoPay with PaymentCategory of creditCard only. Returns zip code of card holder. string
    cardExpirationMonth Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card expiration month. number
    cardExpirationYear Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card expiration year. number
    accountType Will be returned for AutoPay with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string
    bankName Will be returned for AutoPay with PaymentCategory of eCheck only. Returns the name of a bank associated with a provided account. string
    Enroll AutoPay for Credit Card Object Example:
    {
        "sessionId": "4e3e61fb-0090-4e05-b6bc-1a1ac99686bf",
        "customerId": "cfab921e-1b0d-4c2c-96d4-c72503dea270",
        "clientReferenceData1": "POL330701-02",
        "chargeFee": true,
        "autoPayEngineType": "Carrier",
        "withdrawalFrequency": "Monthly",
        "withdrawalDay": 1,
        "numberOfInstallments": 12,
        "amountPerInstallment": 100,
        "externalSchedulerEndpoint": "http://example.com/scheduler",
        "tokenId": "d7203ace-91d3-407e-a0fb-95dbc1081111",
        "lastFourDigits": "1111",
        "paymentCategory": "CreditCard",
        "cardType": "Visa",
        "cardExpirationMonth": 12,
        "cardExpirationYear": 2031,
        "holderZip": "11111"
    }
    
    Enroll AutoPay for ECheck Object Example:
    {
        "sessionId": "de1e0aac-3e2c-4855-bf2d-846c61e04e87",
        "customerId": "39ead4c2-be9e-44fd-b0c6-02d9f296aec8",
        "clientReferenceData1": "POL330701-02",
        "chargeFee": true,
        "autoPayEngineType": "Carrier",
        "withdrawalFrequency": "Monthly",
        "withdrawalDay": 1,
        "numberOfInstallments": 12,
        "amountPerInstallment": 100,
        "externalSchedulerEndpoint": "http://example.com/scheduler",
        "tokenId": "e3b28ed7-f3d9-477e-b25b-4b6cf9f53b3e",
        "lastFourDigits": "1111",
        "paymentCategory": "ECheck",
        "accountType": "Checking",
        "bankName": "Test bank"
    }
    
  • AutoPay Enroll Canceled Event

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

    Code: portalOne.updateAutoPayComplete
    Occurs when AutoPay successfully updated.
    Example:
    $('#portalOneContainer')
        .on('portalOne.updateAutoPayComplete', function() {
            console.log(new Date() + 'portalOne.updateAutoPayComplete');
        });

    Update AutoPay Complete Result

    Content of Update AutoPay Complete payload is depends on parameters with which it was produced.

    Field/Function Name Description Type
    sessionId Unique identifier echoed back from call to a PortalOne operation. string
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. string
    clientReferenceData1 The reference number that was provided. 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
    chargeFee Indicates if the payments will are/were processed with or without a fee. boolean
    autoPayEngineType This field will define who will control the AutoPay Payment Plan generation and recurring scheduling - whether it is Carrier Controlled or InstallmentsEngine controlled. Defaulted to "InstallmentsEngine". AutoPay Engine Type
    withdrawalFrequency Specifies how often payments should be made. WithdrawalFrequency
    withdrawalDay Specifies day of month when payments should be made. string
    numberOfInstallments Number of total installments number
    amountPerInstallment Payment amount for each installment. decimal number
    externalSchedulerEndpoint This field value should only be sent when autoPayEngineType = "Carrier". This maps to a Carrier System Scheduler Engine endpoint. Digital Payments will then use this endpoint to eventually send user-selected Payment Preferences for Auto-Pay Plan creation and scheduling. string
    paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. string
    lastFourDigits Last 4 digits of the card or bank account string
    cardType Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card type that will used. string
    holderZip Will be returned for AutoPay with PaymentCategory of creditCard only. Returns zip code of card holder. string
    cardExpirationMonth Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card expiration month. number
    cardExpirationYear Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card expiration year. number
    accountType Will be returned for AutoPay with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string
    bankName Will be returned for AutoPay with PaymentCategory of eCheck only. Returns the name of a bank associated with a provided account. string
    Update AutoPay for Credit Card Object Example:
    {
        "sessionId": "4e3e61fb-0090-4e05-b6bc-1a1ac99686bf",
        "customerId": "cfab921e-1b0d-4c2c-96d4-c72503dea270",
        "clientReferenceData1": "POL330701-02",
        "chargeFee": true,
        "autoPayEngineType": "Carrier",
        "withdrawalFrequency": "Monthly",
        "withdrawalDay": 1,
        "numberOfInstallments": 12,
        "amountPerInstallment": 100,
        "externalSchedulerEndpoint": "http://example.com/scheduler",
        "tokenId": "d7203ace-91d3-407e-a0fb-95dbc1081111",
        "lastFourDigits": "1111",
        "paymentCategory": "CreditCard",
        "cardType": "Visa",
        "cardExpirationMonth": 12,
        "cardExpirationYear": 2031,
        "holderZip": "11111"
    }
    
    Update AutoPay for ECheck Object Example:
    {
        "sessionId": "de1e0aac-3e2c-4855-bf2d-846c61e04e87",
        "customerId": "39ead4c2-be9e-44fd-b0c6-02d9f296aec8",
        "clientReferenceData1": "POL330701-02",
        "chargeFee": true,
        "autoPayEngineType": "Carrier",
        "withdrawalFrequency": "Monthly",
        "withdrawalDay": 1,
        "numberOfInstallments": 12,
        "amountPerInstallment": 100,
        "externalSchedulerEndpoint": "http://example.com/scheduler",
        "tokenId": "e3b28ed7-f3d9-477e-b25b-4b6cf9f53b3e",
        "lastFourDigits": "1111",
        "paymentCategory": "ECheck",
        "accountType": "Checking",
        "bankName": "Test bank"
    }
    
  • AutoPay Update Canceled Event

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

    Code: portalOne.stopAutoPayComplete
    Occurs when AutoPay successfully updated.
    Example:
    $('#portalOneContainer')
        .on('portalOne.stopAutoPayComplete', function() {
            console.log(new Date() + 'portalOne.stopAutoPayComplete');
        });

    Stop AutoPay Complete Result

    Content of Stop AutoPay Complete payload is depends on parameters with which it was produced.

    Field/Function Name Description Type
    sessionId Unique identifier echoed back from call to a PortalOne operation. string
    customerId Unique customer identifier. Used to access the wallet. Call the CreateAccount method from PortalOne API to acquire the identifier. string
    clientReferenceData1 The reference number that was provided. 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
    chargeFee Indicates if the payments will are/were processed with or without a fee. boolean
    autoPayEngineType This field will define who will control the AutoPay Payment Plan generation and recurring scheduling - whether it is Carrier Controlled or InstallmentsEngine controlled. Defaulted to "InstallmentsEngine". AutoPay Engine Type
    withdrawalFrequency Specifies how often payments should be made. WithdrawalFrequency
    withdrawalDay Specifies day of month when payments should be made. string
    numberOfInstallments Number of total installments number
    amountPerInstallment Payment amount for each installment. decimal number
    externalSchedulerEndpoint This field value should only be sent when autoPayEngineType = "Carrier". This maps to a Carrier System Scheduler Engine endpoint. Digital Payments will then use this endpoint to eventually send user-selected Payment Preferences for Auto-Pay Plan creation and scheduling. string
    paymentCategory Indicates if the requested operation will be predefined as a credit card or bank account operation. string
    lastFourDigits Last 4 digits of the card or bank account string
    cardType Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card type that will used. string
    holderZip Will be returned for AutoPay with PaymentCategory of creditCard only. Returns zip code of card holder. string
    cardExpirationMonth Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card expiration month. number
    cardExpirationYear Will be returned for AutoPay with PaymentCategory of creditCard only. Returns the card expiration year. number
    accountType Will be returned for AutoPay with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string
    bankName Will be returned for AutoPay with PaymentCategory of eCheck only. Returns the name of a bank associated with a provided account. string
    Stop AutoPay for Credit Card Object Example:
    {
        "sessionId": "4e3e61fb-0090-4e05-b6bc-1a1ac99686bf",
        "customerId": "cfab921e-1b0d-4c2c-96d4-c72503dea270",
        "clientReferenceData1": "POL330701-02",
        "chargeFee": true,
        "autoPayEngineType": "Carrier",
        "withdrawalFrequency": "Monthly",
        "withdrawalDay": 1,
        "numberOfInstallments": 12,
        "amountPerInstallment": 100,
        "externalSchedulerEndpoint": "http://example.com/scheduler",
        "tokenId": "d7203ace-91d3-407e-a0fb-95dbc1081111",
        "lastFourDigits": "1111",
        "paymentCategory": "CreditCard",
        "cardType": "Visa",
        "cardExpirationMonth": 12,
        "cardExpirationYear": 2031,
        "holderZip": "11111"
    }
    Stop AutoPay for ECheck Object Example:
    {
        "sessionId": "de1e0aac-3e2c-4855-bf2d-846c61e04e87",
        "customerId": "39ead4c2-be9e-44fd-b0c6-02d9f296aec8",
        "clientReferenceData1": "POL330701-02",
        "chargeFee": true,
        "autoPayEngineType": "Carrier",
        "withdrawalFrequency": "Monthly",
        "withdrawalDay": 1,
        "numberOfInstallments": 12,
        "amountPerInstallment": 100,
        "externalSchedulerEndpoint": "http://example.com/scheduler",
        "tokenId": "e3b28ed7-f3d9-477e-b25b-4b6cf9f53b3e",
        "lastFourDigits": "1111",
        "paymentCategory": "ECheck",
        "accountType": "Checking",
        "bankName": "Test bank"
    }

Payment acknowledgment

What is payment acknowledgment

It is a feature that lets our clients acknowledge payments in real-time. This functionality is tightly coupled with making a payment. Usually it is used to submit payments in client's billing systems and update policy-related information. Moreover, our clients can return us Failure result if the payment should be declined. Such payments will be voided.


Please refer ExternalApi documentation to integrate acknowledgment functionality.


Also, there are obsolete types of acknowledgment.

NB! Obsolete acknowledgment does NOT support acknowledgment for making a payment for multiple policies at once.

These types are not recommended for using by the new customers. Actual documentation of old API is described here.

Test Data

You can use the following card numbers for testing purposes. Numbers marked with an * apply to testing of ClaimsPay Card/PushFunds.

Card Type Card number Cvv2 Expiration date Comments
Visa 4111111111111111* Any 3 digit Any future date *will be successful for ClaimsPay Push to Card
MasterCard 5431111111111111* Any 3 digit Any future date See available amount combinations below.
*Will always return an error when using token for a ClaimsPay Push to Card payment
Discover 6011601160116611 Any 3 digit Any future date See available amount combinations below.
AmericanExpress 341111111111111 Any 4 digit Any future date See available amount combinations below.
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. Numbers marked with an * apply to testing of ClaimsPay Push to Card functionality.

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

Use the following card numbers to simulate specific API response codes regardless of amount.

Test Data for Save transaction type.
Card number Response Code Description
4444444444444117 Success Test: Successfully saved
Test Data for Charge transaction type.
Card number Response Code Description
4444444444444125 Success Test: Charge approved
4444444444444133 IncorrectValidationValue Test: CVV2 code is invalid
4444444444444141 Declined Test: Insufficient funds
4444444444444158 OverMaximumPayment Test: Amount sent exceeds maximum allowable amount.
4444444444444166 DuplicateTransaction Test: Duplicate transaction
4444444444444174 GatewayInternalError Test: System is down
4444444444444182 InvalidCardNumber Test: Invalid card number returned by gateway
4444444444444190 Success Test: Charge approved
4444444444444208 IncorrectValidationValue Test: CVV2 code is invalid
4444444444444216 Declined Test: Insufficient funds
4444444444444224 AvsVerificationFailed Test: Avs verification failed
4444444444444232 DuplicateTransaction Test: Duplicate transaction
4444444444444240 GatewayInternalError Test: System is down
4444444444444257 InvalidCardNumber Test: Invalid card number returned by gateway
4444444444444265 Call Test: Issuer wants voice contact with cardholder
4444444444444273 NoProcessorResponse Test: No response from Processor
Test Data for Charge transaction type (for subsequent void / refund).
Card number Response Code Description
4444444444444299 Success Test: Charge approved
4444444444444307 Success Test: Charge approved
4444444444444315 Success Test: Charge approved
4444444444444323 Success Test: Charge approved
4444444444444331 Success Test: Charge approved
4444444444444349 Success Test: Charge approved
4444444444444356 Success Test: Charge approved
4444444444444364 Success Test: Charge approved
4444444444444372 Success Test: Charge approved
4444444444444380 Success Test: Charge approved
4444444444444398 Success Test: Charge approved
4444444444444505 Success Test: Charge approved
4444444444444513 Success Test: Charge approved
Test Data for void / refund transaction type.
Card number Response Code Description
4444444444444299 InvalidCardNumber Test: This is an invalid card number or account is closed
4444444444444307 IncorrectValidationValue Test: CVV2 code is invalid
4444444444444315 Declined Test: Insufficient funds
4444444444444323 InvalidCreditCardAmount Test: Amount sent exceeds maximum allowable amount.
4444444444444331 DuplicateTransaction Test: Duplicate transaction
4444444444444349 GatewayInternalError Test: System is down
4444444444444356 AvsVerificationFailed Test: Avs Verification Failed
4444444444444364 CardTypeNotAccepted Test: The card type provided is not supported
4444444444444372 CardExpired Test: The Card is Expired
4444444444444380 Call Test: Issuer wants voice contact with cardholder
4444444444444398 NoProcessorResponse Test: No response from Processor
4444444444444505 Success Test: Refund successful
4444444444444513 Success Test: Void successful

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 Test: No response from Processor

Use the following bank account number to simulate specific API response codes regardless of amount.

Transaction Type Account Number Response Code Description
SaveEft 1234567891 Success Test: Successfully saved
Credit or Debit 1234567892 Success Test: Bank account transaction is successfully approved
Credit or Debit 1234567893 ACHTransactionFailed Test: Not able to process bank account payment
Credit or Debit 1234567894 GatewayInternalError Test: System is down
Credit or Debit 1234567895 NoProcessorResponse Test: No response from Processor
Credit or Debit for subsequent Void or refund 1234567896 Success Test: Bank account transaction is successfully approved
Credit or Debit for subsequent Void or refund 1234567897 Success Test: Bank account transaction is successfully approved
Credit or Debit for subsequent Void or refund 1234567898 Success Test: Bank account transaction is successfully approved
Void or Refund 1234567896 ACHTransactionFailed Test: Not able to process bank account payment
Credit or Debit for subsequent Void or refund 1234567897 GatewayInternalError Test: System is down
Credit or Debit for subsequent Void or refund 1234567898 NoProcessorResponse Test: 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

Access Tokens

Access Tokens summary

Access Token functionality allows API consumer to tokenize data stored in JSON and call overloads of methods which are using tokens instead of raw data. Tokenization allow you to create token in the safe place (e.g. on server side), and send to JavaScript only that token which is not allows to determine sensitive data from response.

Creation of Access Token

Creation of Access Token is server-side operation, so do not try to create it from web page.

Endpoint for creation Access Tokens

POST https://stgportalone.processonepayments.com/Api/Api/AccessToken/Create

Create Access Token Request

Parameter Name Description Type Note
PortalOneAuthenticationKey Unique of the API caller. string Required
Type 'Client' token used to start modal, 'Server' token used for redirection AccessTokenType Required
Payload JSON which contains operations essence. Changes according to operation and other parameters. AccessTokenPayload Required
ExpirationDate Moment when token will expires. string Optional, if not selected, token will expires in 24 hours after creation

Access Token Type

PortalOne requires you to provide a type of access token which allows you to toggle from client to server token. "Client" and "Server" tokens are differs by destination. If you are going to start modal you should use "Client" access token.

Option NameDescriptionType
Client

Specifies an Access Token which will open modal on usage.

string

Server

Specifies an Access Token which contains URL for redirection.

string

Access Token Payload

Access Token Payload either can be JSON object and JSON serilized to string.

Structure of payload has single common restriction: it should be valid JSON. But each portal could have some settings which could extend validation of payload.

Create Access Token Request Sample

        https://stgportalone.processonepayments.com/Api/Api/AccessToken/Create
                

That POST request should have body with Content-Type: application/json. Cause Payload could be as object so string request body could looks like this:


        {
   "PortalOneAuthenticationKey":"00000000-0000-0000-0000-000000000000",
   "Type":"Client",
   "Payload":"{\"operation\":\"managePaymentMethods\",
              \"customerId\":\"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d\"}"
}
        

Or like this:


        {
   "PortalOneAuthenticationKey":"00000000-0000-0000-0000-000000000000",
   "Type":"Client",
   "Payload":{
      "operation":"managePaymentMethods",
      "customerId":"e3a6fa12-d448-4686-a5ff-7f821f0b0c5d"
   }
}
        

Both request will creates Access Token with the same content.

Create Access Token Response

Field Name Description Type Note
ResponseCode Operation response code string

ResponseCode should be used for programmatic handling of the response.

ResponseMessage Error description string

ResponseMessage is human readable, subject to change and should not be used for programmatic handling of the response.

Token Access Token returned from PortalOne API. string Valid for single operation, may become expired.
Response Example:
{
    "ResponseCode": "Success",
    "Token": "ff111428-f868-482c-b1fa-871ba4091d01"
}

Create Access Token Errors

Response MessageDescription

Access Token type is not supported

Type of Access Token should one of Access Token Type

Access Token validation rule is not valid

Portal internal error. There is error inside validation logic, not in request

Access Token payload is not valid JSON

Payload should be JSON object or JSON serilized to string

Access Token payload validation by rule failed [ValidationMessage]

Access Token payload is valid JSON, but it is not requires specific verification rules. ValidationExceptionMessage could looks like this:

    [Payload validation failed]
    Regex has no matches [[*]*]
    On the path [$.operation]
                    

Message above is means that payload shoud contain "operation" field and that field shoud contain any value (even empty string).

An internal server error has occurred

Unspecified internal server error.

Access Token LifeCycle

Each token can became invalidated. This is means if some operation will be called with that token as argument, if will failed. There are two ways how token can became invalidated:

  • Each token can be used to successfully complete the operation only once while the number of failed attempts is not limited.

  • It is possible to explicitly select 'ExpirationDate' on creation of new token. If 'ExpirationDate' field is omitted, token will become expired 24 hours after creation. When token is expired, it becomes invalid.

AutoPay REST API

AutoPay REST API Summary

AutoPay REST API allows to call AutoPay operations with existing installment plans. Methods described below are supported for AutoPay Engine Type equals Carrier.

ChargePayment AutoPay

ChargePayment refers to AutoPay methods. It is used to make a payment for a particular policy with an existing AutoPay installment plan. When payment has been processed a postback about result and payment information will be sent to Carrier.


This API method is only to be used if a client wants several instances of a AutoPay modal that will communicate with several Billing systems. In that case, PortalOneAuthenticationKey can be used as an Identifying factor for the specific Modal Instance.


Endpoint for charge payment

POST https://stgportalone.processonepayments.com/Api/Api/AutoPay/ChargePayment


ChargePayment AutoPay Request

Field Name Description Type Note
PortalOneAuthenticationKey Unique Identifier for the modal template. string Required
PolicyRefNumber Used to pass policy number or quote number for reference. This value is also referred to as ClientReferenceData1 field in ExtendedParameters dictionary. If ClientReferenceData1 field is presented in the ExtendedParameters the value should be same. This value is searchable and displayed in the Transaction search. string Required
Amount Amount to charge excludes fees. Must be more than 0.00 and less than 100000. decimal number Required
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
ExtendedParameters The collection of key value pairs for optional parameters Dictionary of string and string

Request Example:

{
    "PortalOneAuthenticationKey" : "999ACE73-E84A-4330-0032-C92310A39D89",
    "PolicyRefNumber": "POL-1234567890",
    "Amount": 100,
    "AccountGroupCode":"Default",
    "ExtendedParameters": {
        "ClientReferenceData1": "POL-1234567890",
        "ClientReferenceData2": "ClientReferenceData2",
        "ClientReferenceData3": "ClientReferenceData3",
        "ClientReferenceData4": "ClientReferenceData4",
        "ClientReferenceData5": "ClientReferenceData5"
    }
}

Charge Payment Response

Field Name Description Type Note
ResponseCode Operation response code string

ResponseCode should be used for programmatic handling of the response.

ResponseMessage Error description string

ResponseMessage is human readable, subject to change and should not be used for programmatic handling of the response.

AuthCode Authorization code sent from Bank. Can be used for reference. string
BatchNumber The batch number to which the ProcessOne transaction was attached. integer
CustomerId One Inc customer identifier. string
ExternalCustomerId External generated ID of Customer. string
CustomerName Name that was provided with a card or bank account information. Passed back as Customer Name. string
OutboundApiKey Unique Identifier for the outbound API. string
PaymentAmount The premium payment amount excluding any convenience fees. decimal number
ConvenienceFee The convenience fee applied to payment amount. decimal number
Timezone Time zone code. (PST, EST) string
TokenId Payment method TokenId that will be used for the payments. string
TransactionDate Date Stamp of the payment decimal number
TransactionId Transaction identifier for the payment. decimal number
PaymentMethod Payment Method PaymentDetailsBase Can be one of the following types: ProcessedCreditCardDetails ProcessedEftDetails
PolicyNumber Policy Number string
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
ExtendedParameters The collection of key value pairs for optional parameters Dictionary of string and string

PaymentDetailsBase

NameDescriptionType
ClientName Client name string
ClientPhoneNumber Client phone Number string
ClientReferenceData1 Used to pass a reference number such as Policy, Quote, or Claim Number. [Deprecated] string
Timezone Time zone code. (PST, EST) string
ConvenienceFee The convenience fee applied to payment amount. string
CustomerName Customer Number string
PaymentAmount Payment method TokenId that will be used for the payments. string
TransactionDate Date Stamp of the payment date
TransactionId Transaction identifier for the payment. string
Type Name of the Payment Method Details Type, like "CreditCard", "Eft" PaymentType

ProcessedCreditCardDetails

Field Name Description Type
CardType Will be returned for payments with PaymentCategory of creditCard only. Returns the card type that was processed. CreditCardType
LastFourDigits Last four digits for the credit card number. 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
CardExpirationMonth Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration month. integer
CardExpirationYear Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration month. integer

ProcessedEftDetails

NameDescriptionTypeAdditional information
AccountType Will be returned for payments with PaymentCategory of eCheck only. Returns type of bank account: checking or savings. EftAccountType
LastFourDigits Last four digits of the bank account. string
BankName Will be returned for payments with PaymentCategory of eCheck only. Returns the name of the Bank based off of Routing Number. string

EftAccountType

Possible enumeration values:

NameValueDescription
Checking

1

Checking.

Savings

2

Savings.

CreditCardType

Possible enumeration values:

Field Name Value Description
Visa

1

Visa

MasterCard

2

MasterCard

AmericanExpress

3

AmericanExpress

Discover

4

Discover

PinlessDebitGeneric

5

PinlessDebitGeneric

Star

6

Star

Nyce

7

Nyce

Pulse

8

Pulse

Other

99

Other

PaymentType

Possible enumeration values:

NameValueDescription
CreditCard

1

Credit card payment type.

Eft

2

EFT payment type.

Response Example:

{
    "AuthCode": "TEST3088",
    "BatchNumber": 2,
    "CustomerId": "9f4491cd-690c-4335-902b-2463fb0f1a14",
    "ExternalCustomerId": "EX-0001",
    "CustomerName": "Test Name",
    "OutboundApiKey": null,
    "PaymentAmount": 100.00,
    "ConvenienceFee": 5.00,
    "TimeZone": "PST",
    "TokenId": "48939a48-f25e-4199-a00a-2d5fe6801111",
    "TransactionDate": "2020-01-01T11:00:00.0000000",
    "TransactionId": "00000001",
    "PaymentMethod": {
        "CardType": "Visa",
        "LastFourDigits": "1111",
        "HolderZip": "11111",
        "CardExpirationMonth": 12,
        "CardExpirationYear": 2022,
        "ClientName": null,
        "ClientPhoneNumber": null,
        "ClientReferenceData1": null,
        "ConvenienceFee": 0.0,
        "CustomerName": null,
        "PaymentAmount": 0.0,
        "TimeZone": null,
        "TransactionDate": null,
        "TransactionId": null,
        "Type": "CreditCardPaymentMethodDetails",
    },
    "PolicyNumber": "POL-1234567890",
    "AccountGroupCode":"Default",
    "ExtendedParameters": {
        "ClientReferenceData1": "POL-1234567890",
        "ClientReferenceData2": "ClientReferenceData2",
        "ClientReferenceData3": "ClientReferenceData3",
        "ClientReferenceData4": "ClientReferenceData4",
        "ClientReferenceData5": "ClientReferenceData5"
    },
    "ResponseCode": "Success",
    "ResponseMessage": null
}
            
        

Modify AutoPay

Modify refers to AutoPay methods. This method is used to change an existing installment plan and receive installment plan information changing from Carrier side. A postback will be received when an installment plan changes are received from Carrier to notify that InstallmentPlan has changed.


This API method is only to be used if a client wants several instances of a AutoPay modal that will communicate with several Billing systems. In that case, PortalOneAuthenticationKey can be used as an Identifying factor for the specific Modal Instance.


Endpoint for modify

POST https://stgportalone.processonepayments.com/Api/Api/AutoPay/Modify


Modify AutoPay Request

Field Name Description Type Note
PortalOneAuthenticationKey Unique Identifier for the modal template. string Required
PolicyRefNumber Used to pass policy number or quote number for reference. This value is searchable and displayed in the Transaction search. Cannot be more than 100 characters. string Required
ChargeFee Indicates if the payment will be/was processed with or without a fee. boolean Optional
ExternalSchedulerEndpoint Carrier System Scheduler Engine endpoint. Cannot be more than 255 characters. string Optional
Token Payment Method Token. string Optional
Email Customer email address. Cannot be more than 250 characters. string Optional
WithdrawalFrequency Specifies how often payments should be made. WithdrawalFrequency Required
AmountPerInstallment Payment amount for each installment. Must be more than 0.00 and less than 100000.00. decimal number Optional
NumberOfInstallments Number of total installments. Must be between 1 and 300. integer Optional
WithdrawalDay Specifies day of month when payments should be made. Must be between 1 and 31. string Required

Request Example:

    {
        "AmountPerInstallment": 100,
        "ChargeFee": true,
        "Email": "[email protected]",
        "ExternalSchedulerEndpoint": "https://example.com",
        "NumberOfInstallments": 3,
        "PolicyRefNumber": "AB-211223",
        "PortalOneAuthenticationKey": "999ACE73-E84A-4330-0032-C92310A39D89",
        "Token": "23231-44244A-24330-02032-4210A39D89",
        "WithdrawalDay": 24,
        "WithdrawalFrequency": 6
    }
        

Modify Payment Response

Field Name Description Type Note
ResponseCode Operation response code string

ResponseCode should be used for programmatic handling of the response.

ResponseMessage Error description string

ResponseMessage is human readable, subject to change and should not be used for programmatic handling of the response.

Response Example:

    {
        "ResponseCode": "Success",
        "ResponseMessage": null
    }