Table of contents

Payment acknowledgment

Pay attention: this api is obsolete and will not supported in the future. Obsolete acknowledgment does NOT support acknowledgment for making a payment for multiple policies at once.

We strongly recommend update your current api to using External API

PortalOne allows you to receive acknowledgment of successful payment. To do this your service need to implement the REST or SOAP contracts described below. Also, payment could be acknowledged by calling code, but this way STRONGLY not recommended.

Server Side Acknowledgment

REST and SOAP acknowledgments contain the following set of fields:
Field Name Description Type
CardType Will be returned for payments with PaymentCategory of creditCard only. Returns the card type that was processed. string
AccountType Will be returned for payments with PaymentCategory of eCheck only. Returns the account type of the bank account: Checking or Saving. string
BankName Will be returned for payments with PaymentCategory of eCheck only. Returns the name of a bank associated with a provided account. string
CustomerName Name that was provided with a card or bank account inforamtion. Passed back as Customer Name string
HolderZip Will be returned for payments with PaymentCategory of creditCard only. Returns zip code of card holder passed back from billingZip on request. string
AuthCode Will be returned for payments with PaymentCategory of creditCard only. Returns authorization code provided by issuing bank. string
CardExpirationMonth Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration month. number
CardExpirationYear Will be returned for payments with PaymentCategory of creditCard only. Returns the card expiration year. number
TokenId Unique identifier that represents a saved card or bank account. Can be used to safely make payments of with the save payment method. string
BatchNumber ProcessOne Batch ID, file identifier. Identifies which batch is associated with a transaction. string
TransactionId ProcessOne Transaction ID, payment identifier. Will be displayed as Confirmation number on the modal and web pages. Can be used to search for a specific payment in the ProcessOne Transaction Report string
SessionId Unique identifier echoed back from call to a PortalOne operation. string
PaymentAmount The premium payment amount excluding any convenience fees. number
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
OutboundApiKey Unique Identifier for the outbound API. string
ClientReferenceData1 Reference number such as Policy, Quote, or Claim Number. string
ClientReferenceData2 External TransactionId value. string
ClientReferenceData3 Location data such as the office the transaction originated. string
ClientReferenceData4 Transaction additional information. string
ClientReferenceData5 Additional reference source account data such as an account number for a multi-policy account. string
  • Acknowledgment REST contract

    For confirmation of payment via the REST protocol, you need to implement the contract described in the swagger file.
    Request example for card payment:
    
    {
        "CardType": "Visa",
        "AccountType": "Undefined",
        "BankName": null,
        "CustomerName": "John Smith",
        "HolderZip": "12345",
        "AuthCode": "70AD493B-6A61-4F85-BDA4-256DDA56B58D",
        "CardExpirationMonth": 12,
        "CardExpirationMonth": 2023,
        "TokenId": null,
        "BatchNumber": 100,
        "TransactionId": "123",
        "SessionId": "821FFD86-CEFF-4A0B-B72B-795029B7D522",
        "PaymentAmount": 500,
        "LastFourDigits": "1111",
        "Timezone": "PST",
        "TransactionDate": "8/29/2021 9:12:33 AM",
        "OutboundApiKey": "312CEE97-5AA7-4987-AB84-AD21FBB67D4A",
        "ClientReferenceData1": "ClientReferenceData1",
        "ClientReferenceData2": "ClientReferenceData2",
        "ClientReferenceData3": "ClientReferenceData3",
        "ClientReferenceData4": "ClientReferenceData4",
        "ClientReferenceData5": "ClientReferenceData5"
    }
    
                    
    Request example for charge by card token:
    
    {
        "CardType": "Undefined",
        "AccountType": "Undefined",
        "BankName": null,
        "CustomerName": null,
        "HolderZip": "12345",
        "AuthCode": "70AD493B-6A61-4F85-BDA4-256DDA56B58D",
        "CardExpirationMonth": null,
        "CardExpirationMonth": null,
        "TokenId": "975AEBE4-4501-4CCF-A297-95895448E4D1",
        "BatchNumber": 100,
        "TransactionId": "123",
        "SessionId": "821FFD86-CEFF-4A0B-B72B-795029B7D522",
        "PaymentAmount": 500,
        "LastFourDigits": null,
        "Timezone": "PST",
        "TransactionDate": "8/29/2021 9:12:33 AM",
        "OutboundApiKey": "312CEE97-5AA7-4987-AB84-AD21FBB67D4A",
        "ClientReferenceData1": null,
        "ClientReferenceData2": null,
        "ClientReferenceData3": null,
        "ClientReferenceData4": null,
        "ClientReferenceData5": null
    }
    
                    
    Request example for eft payment:
    
    {
        "CardType": "Undefined",
        "AccountType": "Checking",
        "BankName": "Wells Fargo",
        "CustomerName": "John Smith",
        "HolderZip": null,
        "AuthCode": null,
        "CardExpirationMonth": null,
        "CardExpirationMonth": null,
        "TokenId": null,
        "BatchNumber": 100,
        "TransactionId": "123",
        "SessionId": "821FFD86-CEFF-4A0B-B72B-795029B7D522",
        "PaymentAmount": 500,
        "LastFourDigits": "1111",
        "Timezone": "PST",
        "TransactionDate": "8/29/2021 9:12:33 AM",
        "OutboundApiKey": "312CEE97-5AA7-4987-AB84-AD21FBB67D4A",
        "ClientReferenceData1": "ClientReferenceData1",
        "ClientReferenceData2": "ClientReferenceData2",
        "ClientReferenceData3": "ClientReferenceData3",
        "ClientReferenceData4": "ClientReferenceData4",
        "ClientReferenceData5": "ClientReferenceData5"
    }
    
                    
    Request example for charge by eft token:
    
    {
        "CardType": "Undefined",
        "AccountType": "Undefined",
        "BankName": "Wells Fargo",
        "CustomerName": null,
        "HolderZip": null,
        "AuthCode": null,
        "CardExpirationMonth": null,
        "CardExpirationMonth": null,
        "TokenId": "975AEBE4-4501-4CCF-A297-95895448E4D1",
        "BatchNumber": 100,
        "TransactionId": "123",
        "SessionId": "821FFD86-CEFF-4A0B-B72B-795029B7D522",
        "PaymentAmount": 500,
        "LastFourDigits": null,
        "Timezone": "PST",
        "TransactionDate": "8/29/2021 9:12:33 AM",
        "OutboundApiKey": "312CEE97-5AA7-4987-AB84-AD21FBB67D4A",
        "ClientReferenceData1": null,
        "ClientReferenceData2": null,
        "ClientReferenceData3": null,
        "ClientReferenceData4": null,
        "ClientReferenceData5": null
    }
    
                    
  • Acknowledgment REST contract signature

    To ensure greater reliability of the transmitted data, PortalOne adds the X-OneInc-Signature header to the sent request. This header contains hash calculated using the HMAC-SHA256 algorithm (see https://en.wikipedia.org/wiki/HMAC for details). The request body is first serialized to JSON, and then HMAC-SHA256 is used for it, the PortalOneAuthKey is used as the secret key.
    Request body example:
    
    {
        "CardType":"Visa",
        "AccountType":"Undefined",
        "BankName":null,
        "CustomerName":"John Smith",
        "HolderZip":"12345",
        "AuthCode":"70AD493B-6A61-4F85-BDA4-256DDA56B58D",
        "CardExpirationMonth":12,
        "CardExpirationMonth":2023,
        "TokenId":null,
        "BatchNumber":100,
        "TransactionId":"123",
        "SessionId":"821FFD86-CEFF-4A0B-B72B-795029B7D522",
        "PaymentAmount":500,
        "LastFourDigits":"1111",
        "Timezone":"PST",
        "TransactionDate":"8/29/2021 9:12:33 AM",
        "OutboundApiKey":"312CEE97-5AA7-4987-AB84-AD21FBB67D4A",
        "ClientReferenceData1":"ClientReferenceData1",
        "ClientReferenceData2":"ClientReferenceData2",
        "ClientReferenceData3":"ClientReferenceData3",
        "ClientReferenceData4":"ClientReferenceData4",
        "ClientReferenceData5":"ClientReferenceData5"
    }
    
                    
    PortalOneAuthKey: D30A423F-FA43-4DFA-AE3A-45AB55FFE6AE
    X-OneInc-Signature: 281586EDEF72245E86F9DD2F3CFA0F6FC286BA9EEA2926A8DBB2428722627728
  • Acknowledgment SOAP contract

    For confirmation of payment via the SOAP protocol, you need to implement the contract described in the WSDL file.
    Request example for card payment:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:one="http://schemas.datacontract.org/2004/07/OneInc.PortalOne.Common.Core.DataContracts">
        <soapenv:Header/>
        <soapenv:Body>
            <tem:Post>
                <tem:request>
                    <one:AccountType>Undefined</one:AccountType>
                    <one:AuthCode>70AD493B-6A61-4F85-BDA4-256DDA56B58D</one:AuthCode>
                    <one:BatchNumber>100</one:BatchNumber>
                    <one:CardExpirationMonth>12</one:CardExpirationMonth>
                    <one:CardExpirationYear>2023</one:CardExpirationYear>
                    <one:CardType>Visa</one:CardType>
                    <one:ClientReferenceData1>ClientReferenceData1</one:ClientReferenceData1>
                    <one:ClientReferenceData2>ClientReferenceData2</one:ClientReferenceData2>
                    <one:ClientReferenceData3>ClientReferenceData3</one:ClientReferenceData3>
                    <one:ClientReferenceData4>ClientReferenceData4</one:ClientReferenceData4>
                    <one:ClientReferenceData5>ClientReferenceData5</one:ClientReferenceData5>
                    <one:CustomerName>John Smith</one:CustomerName>
                    <one:HolderZip>12345</one:HolderZip>
                    <one:LastFourDigits>1111</one:LastFourDigits>
                    <one:OutboundApiKey>312CEE97-5AA7-4987-AB84-AD21FBB67D4A</one:OutboundApiKey>
                    <one:PaymentAmount>500</one:PaymentAmount>
                    <one:Timezone>PST</one:Timezone>
                    <one:TransactionDate>8/29/2021 9:12:33 AM</one:TransactionDate>
                    <one:TransactionId>123</one:TransactionId>
                    <one:SessionId>821FFD86-CEFF-4A0B-B72B-795029B7D522</one:SessionId>
                </tem:request>
            </tem:Post>
        </soapenv:Body>
    </soapenv:Envelope>
    Request example for charge by card token:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:one="http://schemas.datacontract.org/2004/07/OneInc.PortalOne.Common.Core.DataContracts">
        <soapenv:Header/>
        <soapenv:Body>
            <tem:Post>
                <tem:request>
                    <one:AccountType>Undefined</one:AccountType>
                    <one:AuthCode>70AD493B-6A61-4F85-BDA4-256DDA56B58D</one:AuthCode>
                    <one:BatchNumber>100</one:BatchNumber>
                    <one:CardType>Undefined</one:CardType>
                    <one:HolderZip>12345</one:HolderZip>
                    <one:OutboundApiKey>312CEE97-5AA7-4987-AB84-AD21FBB67D4A</one:OutboundApiKey>
                    <one:PaymentAmount>500</one:PaymentAmount>
                    <one:Timezone>PST</one:Timezone>
                    <one:TokenId>51EFBCB8-739F-4475-945E-A55666766B08</one:TokenId>
                    <one:TransactionDate>8/29/2021 9:12:33 AM</one:TransactionDate>
                    <one:TransactionId>123</one:TransactionId>
                    <one:SessionId>821FFD86-CEFF-4A0B-B72B-795029B7D522</one:SessionId>
                </tem:request>
            </tem:Post>
        </soapenv:Body>
    </soapenv:Envelope>
    Request example for eft payment:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:one="http://schemas.datacontract.org/2004/07/OneInc.PortalOne.Common.Core.DataContracts">
        <soapenv:Header/>
        <soapenv:Body>
            <tem:Post>
                <tem:request>
                    <one:AccountType>Checking</one:AccountType>
                    <one:AuthCode>70AD493B-6A61-4F85-BDA4-256DDA56B58D</one:AuthCode>
                    <one:BankName>Wells Fargo</one:BankName>
                    <one:BatchNumber>100</one:BatchNumber>
                    <one:CardType>Undefined</one:CardType>
                    <one:ClientReferenceData1>ClientReferenceData1</one:ClientReferenceData1>
                    <one:ClientReferenceData2>ClientReferenceData2</one:ClientReferenceData2>
                    <one:ClientReferenceData3>ClientReferenceData3</one:ClientReferenceData3>
                    <one:ClientReferenceData4>ClientReferenceData4</one:ClientReferenceData4>
                    <one:ClientReferenceData5>ClientReferenceData5</one:ClientReferenceData5>
                    <one:CustomerName>John Smith</one:CustomerName>
                    <one:LastFourDigits>1111</one:LastFourDigits>
                    <one:OutboundApiKey>312CEE97-5AA7-4987-AB84-AD21FBB67D4A</one:OutboundApiKey>
                    <one:PaymentAmount>500</one:PaymentAmount>
                    <one:Timezone>PST</one:Timezone>
                    <one:TransactionDate>8/29/2021 9:12:33 AM</one:TransactionDate>
                    <one:TransactionId>123</one:TransactionId>
                    <one:SessionId>821FFD86-CEFF-4A0B-B72B-795029B7D522</one:SessionId>
                </tem:request>
            </tem:Post>
        </soapenv:Body>
    </soapenv:Envelope>
    Request example for charge by eft token:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/" xmlns:one="http://schemas.datacontract.org/2004/07/OneInc.PortalOne.Common.Core.DataContracts">
        <soapenv:Header/>
        <soapenv:Body>
            <tem:Post>
                <tem:request>
                    <one:AccountType>"Wells Fargo"</one:AccountType>
                    <one:BankName>Wells Fargo</one:BankName>
                    <one:BatchNumber>100</one:BatchNumber>
                    <one:CardType>Undefined</one:CardType>
                    <one:OutboundApiKey>312CEE97-5AA7-4987-AB84-AD21FBB67D4A</one:OutboundApiKey>
                    <one:PaymentAmount>500</one:PaymentAmount>
                    <one:Timezone>PST</one:Timezone>
                    <one:TokenId>51EFBCB8-739F-4475-945E-A55666766B08</one:TokenId>
                    <one:TransactionDate>8/29/2021 9:12:33 AM</one:TransactionDate>
                    <one:TransactionId>123</one:TransactionId>
                    <one:SessionId>821FFD86-CEFF-4A0B-B72B-795029B7D522</one:SessionId>
                </tem:request>
            </tem:Post>
        </soapenv:Body>
    </soapenv:Envelope>
  • Acknowledgment by calling code

    We strongly recommend update your current api to using External API instead of using acknowledgment process, described below.

    As described at Making a payment operation, if you set acknowledgmentRequired to true, you should acknowledge payment by calling code. If such payment will not be acknowledged, the payment will be voided. To acknowledge payment you should subscribe on payment complete event and call acknowledge() method of the event argument.

    $('#portalOneContainer')
            .on('portalOne.paymentComplete', function(e, data) {
                console.info(
                    new Date() + ' portalOne.paymentComplete. Transaction id is ',
                    data.transactionId
                );
    
                // Call some backend checks here
    
                let shouldBeAcknowledged = false;
    
                let request = new XMLHttpRequest();
                request.open =( 'GET',
                                'https://example.com/api/v1/acknowledgePayment/' + data.clientReferenceData1);
                request.send();
                request.onload = () => {
                    if (request.status === 200) {
                        shouldBeAcknowledged = true;
                    }
                    else {
                        shouldBeAcknowledged = false;
                    }
                }
    
                if(data.acknowledge && shouldBeAcknowledged) {
                    data.acknowledge();
                }
            });
        

    PaymentComplete Event Object Parameter

    Payment could be made for single or multiple policies. But obsolete acknowledgment support single payments only.

    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"
                }
           ]
        }
        
    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"
                }
            ]
        }