EPF Endorsements
The EPF Endorsement APIs enable merchants to add an endorsement to a policy that is financed through IPFS.
When a customer requests to add an endorsement to a policy after the policy has been created and financed through IPFS, the IPFS finance agreement must be updated to reflect the new premium amount. The EPF Endorsement feature enables merchants to add an endorsement to a policy that is financed through IPFS.
The EPF Endorsement process comprises the following steps:
- A customer contacts the merchant and requests to add an endorsement to their existing policy that is financed through IPFS.
- The merchant calls the POST Retrieve Endorsement Eligibility method to see if the IPFS finance agreement for the current policy is eligible to be modified for the endorsement.
- If the POST Retrieve Endorsement Eligibility method returns true, the merchant calls the POST Update Policy Endorsements method to request an IPFS finance quote for the updated policy.
- The POST Update Policy Endorsements method returns the premium finance quote information for the new policy. It also returns a paymentToken which is used to initialize AndDoneJS if a down payment or e-signature is required.
- If an e-signature or down payment is required from the customer, the merchant initializes AndDoneJS so that the customer can complete the e-signature process and/or submit a down payment.
- If no e-signature or down payment is required, the merchant calls the POST Confirm (Book) Endorsement method to confirm that the customer has completed the endorsement process and accepted the updated IPFS premium finance agreement.
Prerequisites
To use EPF Endorsement the merchant must have Embedded Premium Finance enabled and all related prerequisites in place. For more information, see Embedded Premium Finance - Prerequisites.
Checking Endorsement Eligibility
When adding an endorsement to a policy that is financed through IPFS, the merchant must first verify that the finance agreement is eligible for endorsement. Some IPFS financing agreements allow for changes to the policy during the finance period, while others may require the insured to pay for the endorsement separately.
To check the eligibility of the finance agreement for endorsement, call the POST Retrieve Endorsement Eligibility method. This method requires the IPFS account number (accountNumber) for the current finance agreement. You must also confirm that the endorsement is for a commercial policy (isCommercial = true).
Example: POST Get Endorsement Eligibility request body
{
"accountNumber": "217139",
"isCommercial": true
}The POST Retrieve Endorsement Eligibility method returns the eligibility status of the policy.
Example: POST Get Endorsement Eligibility response body
{
"integrationID": "c21f2188-69bf-4032-b85b-a6a5e531d21a",
"isSuccess": true,
"isEndorsementEligible": true,
"message": "OK",
"item": {
"agreementID": 7062406,
"clientID": 5585132,
"accountNumber": "217139",
"clientName": "SAM",
"isCommercial": true,
"policies": [
{
"policyID": 10221116,
"companyName": "LEXINGTON INSURANCE COMPANY",
"policyNumber": "PENDING",
"premium": 5000.0,
"coverageType": "FIRE",
"coverageTypeDescription": "FIRE",
"companyTypeID": 4
}
]
}
}
If the policy is eligible for endorsement the request returns an isEndorsementEligible value of true and an agreementID which is required when submitting the policy update information in the next step.
Generating the Updated Premium Finance Quote
Next, the POST Update Policy Endorsements method is called to generate an IPFS Premium Finance Quote for the updated policy. This method requires the agreementID returned by the endorsement eligibility request and the accountNumber of the existing IPFS finance agreement.
This method also requires the ID of the insurance policy policyId the updated premium amount premium with the addition of the endorsement, the policy effective date effectiveDate and expiration date expirationDate.
Note: The effectiveDate for the policy must be set to a date prior to the original policy effective date.
Example: POST Update Policy Endorsements request body
{
"quote": {
"accountNumber" : "222533",
"agreementId": 6977670,
"policies": [
{
"policyId" : 10087597,
"premium": 1200,
"effectiveDate": "2023-04-06T03:29:44.605Z",
"expirationDate": "2024-04-05T03:29:44.605Z",
"coverage": "FIRE",
"company": {
"bestNumber": "",
"uniqueID": "UniqueCompany",
"name": "string",
"careOf": "string",
"address1": "string",
"address2": "string",
"city": "string",
"state": "string",
"zip": "string",
"phone": "string"
}
}
],
"insured": {
"AgentCustomerNumber": "Suyash",
"Email": "[email protected]",
"CareOf": "",
"Address": {
"Name": "Sam",
"Address1": "1055 Broadway",
"Address2": "",
"City": "Kansas City",
"State": "MO",
"Zip": "64105",
"Phone": ""
}
}
}
}If successful, the POST Update Policy Endorsements method returns:
- The
quoteKeyfor the updated premium finance quote. - The details of the updated agreement, including down payment amount, if required, amount financed, total finance charge, installment amount and the total number of installments to be paid.
- If an e-signature or down payment is required, a
paymentTokenis returned which is used to initialize AndDoneJS.
Example: POST Update Policy Endorsements response
{
"integrationID": "85c02638-22e1-4da8-8f9f-4f82233dbd5c",
"isSuccess": true,
"message": "Sucess",
"item": {
"saveStatus": "Success",
"quote": {
"pfa": "https://v1-252010964968-pfastore.s3.amazonaws.com/UnsignedPFA/24013629_unsigned?AWSAccessKeyId=ASIATVLIGE7UAPLAHKNI&Expires=1694195435&x-amz-security-token=IQoJb3JpZ2luX2VjENL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJGMEQCIF%2Bw%2FOOjvN8xvfpGXs4PwnCPakaf2JhvstWdl%2F4JCdgCAiBbJmEED9O%2FiobLxKBsiJ%2B3zKZL96mnce9AVlLt3soTMyqHAwir%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDI1MjAxMDk2NDk2OCIMuNh%2FNsoeeYsA6tMoKtsCZSYZglGL%2BUh351Yv2u44zWHMAudLvD7lINDrpP1Zst2X3ZsYA4462rA4hTtfpBCz%2BGmY82TL6ZFEzkLTYGWBulJ2cDKbAV2UGXXOZ6Kzxw3Q71OOiX79DodywTKLu71%2FuEvwasbuphz6NGYfkyqHp6iMLEiLKQ4alXcYIR75kiH%2BwQUOySdUhIZpjgTgGrZe7S0K82fvngzf82CMDu4wAb5R%2F0RjKnR884jcSsiwITrbty0CX6a4JgxDT%2FSzBKe3XhFQcBqiBDfEBozWEnl%2Bq%2BhTa9NX%2Bnzr2U915NWAWyeyA9DIUTrmjkr3Lz3HsKHuuY8TY6HMrYv1BELcMnPGv1vA6nIQ0WAXeriRZi31r1DW5UKy1jSES4ytlV%2B6pN%2FNCTkPJfXt8iHCx6Yi26zsrI6UJlrQUx%2Fl0r06hyR3O0qyJ5QiRpoilUPQL1LoUalAdzO3xjcocFhrr%2BYwp7jtpwY6nwEAnwKs8%2FMuNi2IxpmvhYSMJ55L48G5YqcyIyZ%2FGA2wu2pAwMx42Zf7YWl9BZkMld6%2BqUefUYNPc2UVC2vdsg6OTIc43dy9nSJ%2FTezSYBy25%2BSZG545VU2zJWjvLt2dv2ll%2B0XRDM4AP%2BS%2FAKiZD7INlte%2BY7DyNnzbz2VAMTnnsf1cKOJvKzkTJdi54osgyVPGPQcmU6%2BsUGOswMTz31k%3D&Signature=2cBuS0X4h3O9Fk1LqzZdaxgMc2c%3D",
"quoteKey": 24013629,
"premium": 8000.0,
"downAmount": 2613.36,
"amountFinanced": 5386.64,
"financeCharge": 331.26,
"totalPayments": 5717.9,
"paymentAmount": 571.79,
"docStamp": 0,
"firstDueDate": "11/16/2023",
"apr": 13.2,
"installments": 10,
"paymentsRetained": 0,
"paymentRetainedAmount": 0.0,
"eSignResult": {
"processed": false,
"message": null,
"batchID": null,
"agentURL": null,
"insuredURL": null,
"eSignOption": 0
},
"isDownPaymentRequired": true,
"isEsignRequired": false,
"isEndorsement": true
},
"paymentIntent": {
"paymentToken": "ZdOOw3Pd",
"title": "DEV-PRS-000000-0908232",
"amount": 2613.36,
"invoiceNumber": null,
"expireOn": "09-15-2023 13:45:38",
"shortDescription": null,
"paymentDescription": null,
"intent": {
"paymentTypes": [
"ACH",
"CreditCard",
"DebitCard"
]
}
}
}
}Collecting a Down Payment or E-Signature
Depending on the existing premium finance agreement and the new premium amount after the endorsement is added, IPFS may require a down payment for the new policy premium. Also, residents of Alaska and Kentucky are required by state law to electronically sign the updated finance agreement. In either case, the customer must access the AndDoneJS payment widget to provide their e-signature and/or submit the down payment.
To collect an e-signature or down payment, initialize the AndDoneJS payment widget using the paymentToken returned from the POST Update Policy Endorsements method.
- If an e-signature is required, the customer is prompted to accept the terms of the updated premium finance agreement and enter their name.
- If a down payment is required, the customer is prompted to provide their name and payment account information and submit the down payment.
Once the customer completes the e-signature and/or down payment process, AndDoneJS confirms the endorsement with IPFS and returns the transaction status and information regarding the updated premium financing agreement to the merchant server via webhook.
Booking the Endorsement: No E-Signature or Down Payment
If no e-signature or down payment is required for the updated policy, no action is required by the customer. The merchant must confirm that the customer has purchased the endorsement and accepted the updated premium finance agreement by calling the POST Confirm (Book) Endorsement method, passing the quoteKey that was returned by the POST Update Policy Endorsements method.
Example: POST Update Policy Endorsements request
{
"quotekey" : 23400043
}If successful, the POST Confirm (Book) Endorsement method returns the confirmation status in the response.
Example: POST Update Policy Endorsements response
{
"message": "Submit PFA success for Quote 24023980.",
"isSuccess": true,
"integrationID": "f64a50a7-115b-4249-83d4-240f806df73e"
}