Making ad hoc and scheduled credit card and ACH payments

The following InsuranceNow API endpoints support both ad hoc and scheduled payments using credit card and automated clearing house (ACH) payments:
POST /billingAccounts/{systemId}/paymentRequest
Make ad hoc credit card or ACH payment requests for existing or new payment profiles.
POST /billingAccounts/{systemId}/scheduledPaymentRequest
Make scheduled credit card or ACH payment requests for existing or new payment profiles.
Each of these endpoints has five distinct usage scenarios.

Credit card from an existing payment profile

  1. Issue a GET /billingAccounts/{systemId}/paymentSources request.
    You can optionally pass the sourceName parameter to get just the payment profiles that were made from a specific source, such as Service Portal or Sales Portal.
    Note: Be aware that SourceName is a relatively new feature and therefore prior payments might not be marked with this parameter. You can use any value for the sourceName parameter. But a best practice is to use consistent values to enable reliable filtering when performing lookups in the core InsuranceNow user interface.
    Select the appropriate prior payment with methodCd=Credit Card. The following code shows an example of a typical response:
    {
      "id": "APIPaymentSourceList-1625703649-940996514",
    
    "electronicPaymentSource": [
    { "id": "!X8pYzI63yyqIhtjsfHt9T4IlnXY=", "sourceName": "Account Payment", "methodCd": "Credit Card", "action": "None", "paymentServiceAccountId": "IIC", "transactionId": "2528036", "creditCardNumber": "****1111", "creditCardTypeCd": "Visa"
    }
    ] }
    JSON
  2. Use the values from the previous endpoint result in a call to the POST /billingAccounts/{systemId}/paymentRequest or scheduledPaymentRequest endpoint as follows:
    • Copy the masked credit card number value from creditCardNumber field to the field of the same name.
    • Copy the value in the id field to the paymentOnFileId field.
    Note: Certain fields are required based on the validation for the type of payment you are handling. For example, creditCardNumber is required when dealing with a credit card payment.
    The following code shows an example of a typical paymentRequest or scheduledPaymentRequest POST event:
    {
      "paymentMethod": "Credit Card",
      "_comment": Following element used only in scheduledPaymentRequest and must be in YYYY-mm-dd format.
      "scheduledDate": "2024-04-18" 
    
    "payments": [
    { "sourceRef": "4", "sourceCd": "Web Portal", "checkAmt": "87.50", "receiptAmt": "87.50", "paymentOnFileId": "!X8pYzI63yyqIhtjsfHt9T4IlnXY=",
    "electronicPaymentSource": { "sourceName": "Service Portal", "creditCardNumber": "****1111",
    }
    }
    ] }
    JSON
    Note: creditCardNumber must be a masked value. If you are dealing with an unmasked credit card number, you must mask it before sending it to InsuranceNow. Guidewire security practices do not allow storing full credit card numbers in InsuranceNow.

Credit card through a payment service

To make a credit card payment through an external payment service, such as Authorize.net or through One Inc via the Guidewire Payments API, requires your API caller to have a PCI-compliant integrated iFrame for secure payment processing. If properly configured, the payment service returns a transaction ID or payment profile ID that InsuranceNow uses to confirm via the payment service.

The following code shows an example of a typical paymentRequest or scheduledPaymentRequest POST event:
{
  "paymentMethod": "Credit Card",
  "_comment": Following element used only in scheduledPaymentRequest and must be in YYYY-mm-dd format.
  "scheduledDate": "2024-04-18" 
  "payments": [
    {
      "sourceRef": "4",
      "sourceCd": "Web Portal",
      "checkAmt": "87.50",
      "receiptAmt": "87.50",
      "electronicPaymentSource": {
        "sourceName": "Service Portal",
        "creditCardNumber": "XXXX1234",
        "customerProfileId": "<customerProfileId>",
        "customerPaymentProfileId": "<paymentProfileId>",
        "paymentServiceAccountId": "<carrierCd>"
      }
    }
  ]
}
Java
Obtain creditCardNumber, customerProfileId, and customerPaymentProfileId from the iFrame or from your payment service interface. These values are required if you are making an ad hoc payment with a new credit card.
Note: creditCardNumber must be a masked value. If your payment service does not provide a masked value, you must mask it before sending it to InsuranceNow. Guidewire security practices do not allow storing full credit card numbers in InsuranceNow.

The customerProfileId and customerPaymentProfileId values are the customer account number and customer current transaction number from your payment service. Authorize.net provides both values. One Inc via Guidewire Payments API uses the same value for both fields.

The paymentServiceAccountId field is generally the carrier code for the policy being paid. You can retrieve this value in several ways. For example:

  • Get the value from the current Policy or Account resource, which you could have retrieved prior to this call by using GET /policies/{systemId} or GET /billingAccounts/{systemId} respectively.
  • Use the GET /billingAccounts/{systemId}/paymentSources endpoint as described in the previous example to determine whether there were any prior payments on the account. This endpoint returns the paymentServiceAccountId in any prior payments, which is the carrier code.

ACH payment on a prior payment profile

  1. Issue a GET /billingAccounts/{systemId}/paymentSources request.
    You can optionally pass the SourceName parameter to get just the payment profiles that were made from a specific source, such as Service Portal or Sales Portal.
    Note: Be aware that SourceName is a relatively new feature and therefore prior payments might not be marked with this parameter. You can use any value for the sourceName parameter. But a best practice is to use consistent values to enable reliable filtering when performing lookups in the core InsuranceNow user interface.
    Select the appropriate prior payment that has methodCd=ACH. The following code shows an example of a typical response:
    {
      "id": "APIPaymentSourceList-1625703649-940996514",
    
    "electronicPaymentSource": [
    { "id": "!ZDM3clTwYGtrtqCb08tvWRdkH3o=", "sourceName": "Account Payment", "methodCd": "ACH", "action": "None", "achName": "Doe, John", "achBankAccountTypeCd": "Checking", "achBankAccountNumber": "****0393", "paymentServiceAccountId": "IIC", "transactionId": "2512501"
    }
    ] }
    JSON
  2. Copy the value in the id field to the paymentOnFileId field from the previous endpoint result in a call to the POST /billingAccounts/{systemId}/paymentRequest or scheduledPaymentRequest endpoint.
    Note: Certain fields are required based on the validation for the type of payment you are handling.
    The following code shows an example of a typical paymentRequest or scheduledPaymentRequest POST event:
    {
      "paymentMethod": "ACH",
      "_comment": Following element used only in scheduledPaymentRequest and must be in YYYY-mm-dd format.
      "scheduledDate": "2024-04-18" 
      "payments": [
        {
          "sourceRef": "4",
          "sourceCd": "Web Portal",
          "checkAmt": "3.25",
          "receiptAmt": "3.25",
          "paymentOnFileId": "!ZDM3clTwYGtrtqCb08tvWRdkH3o=",
          "electronicPaymentSource": {
            "sourceName": "Service Portal"
          }
        }
      ]
    }
    Java

ACH payment through a payment service

To make an ACH payment request through an external payment service, such as Authorize.net or through One Inc via the Guidewire Payments API, requires your API caller to have a PCI-compliant integrated iFrame for secure payment processing. If properly configured, the payment service will return a transaction ID or payment profile ID that InsuranceNow uses to confirm via the payment service.

The following code shows an example of a typical paymentRequest or scheduledPaymentRequest POST event:
{
  "paymentMethod": "ACH",
  "_comment": Following element used only in scheduledPaymentRequest and must be in YYYY-mm-dd format.
  "scheduledDate": "2024-04-18" 
"payments": [
{ "sourceRef": "4", "sourceCd": "Web Portal", "checkAmt": "1.35", "receiptAmt": "1.35",
"electronicPaymentSource": { "sourceName": "Service Portal", "achBankAccountTypeCd": "Checking", "achBankAccountNumber": "XXXX0293", "customerProfileId": "", "customerPaymentProfileId": "", "paymentServiceAccountId": ""
}
}
] }
JSON
Obtain achBankAccountNumber, customerProfileId, and customerPaymentProfileId from the iFrame or from your payment service interface. These values are required if you are making an ad hoc payment with new ACH information.
Note: achBankAccountNumber must be a masked value. If your payment service does not provide a masked value, you must mask it before sending it to InsuranceNow. Guidewire security practices do not allow storing full account numbers in InsuranceNow.

The customerProfileId and customerPaymentProfileId values are the customer account number and customer current transaction number from your payment service. Authorize.net provides both values. One Inc via Guidewire Payments API uses the same value for both fields.

The paymentServiceAccountId field is generally the carrier code for this policy being paid. You can retrieve this value in several ways. For example:
  • From the current Policy or Account resource which you could have retrieved prior to this call by using GET /policies/{systemId} or GET /billingAccounts/{systemId} respectively.
  • If you attempted to determine whether there were any prior payments on the account, from the GET /billingAccounts/{systemId}/paymentSources endpoint as described in the previous example. This endpoint returns the paymentServiceAccountId in any prior payments, which is essentially the carrier code.

The achBankAccountTypeCd field is optional. Typical values are "Checking" and "Savings". You can provide this value if the iFrame or payment service interface provides it. If included, it enhances the details that InsuranceNow displays from the core user interface.

ACH payment not from a prior payment or payment service

To make an ACH payment request that does not a prior payment profile and not through an external payment service, such as Authorize.net or One Inc via the Guidewire Payments API, requires ACH details such as the bank account number, bank routing number, and other information.

The following code shows an example of a typical paymentRequest or scheduledPaymentRequest POST event that requires these manual details:
{
  "paymentMethod": "ACH",
  "_comment": Following element used only in scheduledPaymentRequest and must be in YYYY-mm-dd format.
  "scheduledDate": "2024-04-18" 
"payments": [
{ "sourceRef": "8", "sourceCd": "Web Portal", "checkAmt": "2.77", "receiptAmt": "2.77",
"electronicPaymentSource": { "methodCd": "ACH", "sourceName": "Service Portal", "achName": "Smith, Joe", "achBankName": "Wells Fargo", "achBankAccountTypeCd": "Checking", "achBankAccountNumber": "1234567", "achRoutingNumber": "011001959", "achStandardEntryClassCd": "Personal"
}
}
] }
JSON
Note:
  • Because this is a manual ACH payment, the following fields are required: achName, achBankName, achBankAccountTypeCd, achBankAccountNumber, achRoutingNumber, and achStandardEntryClassCd (Personal, Commercial, or other valid value.)
  • The achBankAccountNumber can be in clear text (unmasked) because this is the account number on the check of the payer. When stored in InsuranceNow, this value is masked.
  • The achRoutingNumber must be a valid routing number for the bank location of the check origination.