Using the Premium Finance Lite API
The Premium Finance Lite secure API enables merchants to integrate premium finance quoting capabilities into their existing applications. Using the API, the merchant generates an IPFS financing quote and then provides a payment link to the customer, allowing them to submit a payment.
The Premium Finance Lite API payment flow comprises the following steps:
- The customer elects to purchase an insurance policy at a dollar amount quoted by the merchant.
- The merchant application calls the POST Generate Premium Finance Lite Quote method using the information collected about the insured, the policy, the total premium amount, and the IPFS program ID.
- The AndDone server generates the premium finance quote and returns the quote details including a unique
quoteKeyto the merchant server. - The merchant application uses the
quoteKeyto call the POST Generate Premium Finance Lite Payment Link method. - The POST Generate Premium Finance Lite Payment Link method returns the
paymentLinkURL, which the merchant shares with the customer. - The customer accesses the payment link URL and submits their payment.
Generating a Premium Finance Lite Quote
The Premium Finance Lite process is initiated by calling the POST Generate Premium Finance Lite Quote method.
POST Generate Premium Finance Lite Quote Request
The POST Generate Premium Finance Lite Quote Request body includes the following information.
Merchant Information
The the unique merchant ID and contact information:
"merchantId": "4bvl9KxM",
"merchant": {
"contactName": "Azhar Dave",
"contactPhone": "0123456789"
},Insured Information
The Insured object includes names, contact numbers, and address details of the insured:
"insured": {
"firstName": "Pawan",
"lastName": "Final",
"mobilePhoneNumber": "9876009870",
"faxNumber": null,
"emailAddress": "[email protected]",
"isCancellationWarningViaTextEnabled": true,
"address": {
"Address1": "1055",
"Address2": "Broadway Blvd",
"City": "Kansas City",
"State": "MO",
"Zip": "64105",
"PhoneNumber": null
}
},Program Information
The program object indicates the IPFS finance program programId to be used for the quote and the type of loan loanTyperequested: Commercial or Personal.
To automate the EPF process, it is essential to have logic in place that can determine the appropriate program to use for a specific insured or policy. The Premium Finance Lite API does not provide the logic for selecting the optimal program. It generates a quote against the program ID that is specified in the POST Generate Premium Finance Lite Quote request.
"program": {
"programId": 82262,
"loanType": "Personal"
},Policy Information
The policies array contains information about the insurance policies that are being financed, including premium amounts, policy dates, coverage types, and details about the insurance carrier.
"policies": [
{
"premium": 32728,
"effectiveDate": "04-24-2024 00:00:00",
"expirationDate": "08-30-2024 00:00:00",
"coverageType": "FIRE",
"cancelDays": "Item20",
"additionalFees": 00,
"minimumEarnedPercent": null,
"policyNumber": "TestNumber2",
"carrier": {
"name": "OCCIDENTAL FIRE & CASUALTY CO OF NO",
"bestNumber": "2312",
"uniqueId": "23248"
}
}
]
}Premium Finance Lite Quote Response
The POST Generate Premium Finance Lite Quote method returns the details of the finance quote, including the down payment amount, amount financed, finance charge, installment amount, and number of installments. The response also includes the quoteKey, which is used in the POST Generate Premium Finance Lite Payment Link method to generate a payment link.
{
"isSuccess": true,
"message": "Sucess",
"integrationID": "6635e4df-bbe7-421a-804f-8f5f53a3059d",
"item": {
"quoteKey": 26065385,
"premium": 32728.0,
"downAmount": 4909.2,
"amountFinanced": 27818.8,
"financeCharge": 1447.9,
"totalPayments": 29266.7,
"paymentAmount": 2926.67,
"docStamp": 0.0,
"firstDueDate": "2024-05-24T00:00:00",
"apr": 0.112,
"installments": 10,
"batchId": null,
"paymentsRetained": 0,
"paymentRetainedAmount": 0.0,
"unsignedPFAUrl": "https://v1-252010964968-pfastore.s3.amazonaws.com/UnsignedPFA...",
"retailAgentRegisterLoginURL": "",
"eSignResult": {
"processed": false,
"message": null,
"batchId": null,
"agentUrl": null,
"insuredUrl": null,
"eSignOption": 0
},
"errors": null,
"pfa": null,
"electronicSignatureURL": "https://app-stage.ipfs.com/Private/Quoting/ViewPFA.aspx?QuoteID%3d16449801-c965-4709-a679-6231e6c9254c%26SessionID%3d3716fd0b-5a05-429d-ba8d-3790ee0bfcf9%26BranchID%3d3%26EntityType%3d1%26EntityID%3d1603078"
}
}POST Generate Quote Response Fields
| Field Name | Data Type | Description |
| isSuccess | Boolean | Indicates if the quote generation was successful. |
| message | String | API call success status. |
| IntegrationID | String | Unique identifier for the API call generated by IPFS. |
| item | Object | This object contains the details of the premium finance quote. |
| quoteKey | Numeric | Uniques IPFS identifier for the generated quote. |
| premium | Numeric | Quoted premium amount of policy. |
| downAmount | Numeric | Amount to be collected as the down payment. |
| amountFinanced | Numeric | Amount that will be financed after the down payment. |
| financeCharge | Numeric | Cost of financing charged by IPFS. |
| totalPayments | Numeric | Total amount to be paid after down payment. This is amountFinanced + financeCharge. |
| paymentAmount | Numeric | The amount of the individual installments. |
| docStamp | Numeric | Not currently in use. In the future, this will indicate the documentation filing fee from IPFS for states that require it (based on the state where the Insured resides). |
| firstDueDate | String | Date on which the first installment payment is due. |
| apr | Numeric | The annual percentage rate charged on the financed amount (4.56 = 4.56%). |
| Installments | Numeric | Total number of installment payments to be made. |
| batchID | String | The intent token associated with this quote. |
| paymentsRetained | Numeric | Number of installments included in the down payment if the effective date of the policy is in the past. |
| paymentsRetainedAmount | Numeric | Amount of installments included in the down payment if the effective date of the policy is in the past. |
| unsignedPFAUrl | String | Link to hosted PFA (Not Signed) |
| retailAgentRegisterLogin | String | Not currently in use. |
| eSignResult | Object | This object contains details about the eSign process. |
| processed | boolean | Indicates whether the Esignature was processed. |
| message | string | Status message related to esign process. |
| batchID | string | The unique batch ID for the Esignature. |
| agentURL | string | URL to agent eSign. |
| insuredURL | string | URL to insured eSign. |
| eSignOption | string | 2 = eSign for agent only 3 = eSign the PFA then send to the insured (via email link) for their signature via ESign 4 = Insured signs (via email link or return URL) the PFA then sends to Agent (via email link for agent signature. 5 = eSign for agent and insured both (existing 2a still supported). |
| errors | String | Description of any error returned by the API call. |
| pfa | String | Not used at this time. |
| electronicSignatureURL | String | The URL of the agent login with IPFS that can be used to make a payment directly on the IPFS system. The user must have an IPFS username and password to access this URL. |
Generating a Payment Link
To generate a payment link, the quoteKey returned from the quote request is passed in the POST Generate Premium Finance Lite Payment Link method.
If the customer has opted for the premium finance option, set the isPayInFull parameter to false. If the customer has opted to pay the total premium amount in full, set isPayInFull to true.
{
"quoteKey": "26065373",
"isPayInFull": false
}Premium Finance Lite Payment Link Response
The paymentLink URL is returned in the POST Generate PF Lite Payment Link response. This URL can be shared with customers through Email, SMS, or social media. When a customer accesses the payment link URL, they are directed to a secure, AndDone-hosted payment page, where they can submit their payment.
{
"id": "RdQRnobv",
"merchantId": "4jdew2xz",
"title": "PL-26068787",
"paymentLink": "https://link.dev.anddone.com/#/RdQRnobv",
"shortLink": "https://link.dev.anddone.com/#/RdQRnobv",
"amount": 4909.2,
"paymentDescription": "26068787",
"expireIn": 10,
"expireInUnit": "Weeks",
"expireOn": "07-08-2024 20:26:32",
"applyPaymentAdjustments": null,
"enablePartialPayment": false,
"enableMultiplePayment": false,
"noOfPaymentMade": 0,
"totalPaidAmount": 0.0,
"enableProtection": false,
"protectionMode": null,
"displayReceipt": null,
"linkStatus": "Enabled",
"invoiceNumber": null,
"createdOn": "04-29-2024 20:26:32",
"createdBy": "MerchantABC",
"modifiedOn": "04-29-2024 20:26:32",
"modifiedBy": "MerchantABC",
"shortDescription": null,
"responseType": "OnScreen",
"callbackParameters": null,
"displaySettings": {
"selectedCustomerFields": null,
"additionalDetailsPreference": "NoAdditionalDetails",
"displaySummary": false,
"acceptCustomerInfo": false,
"removeHeader": false,
"acceptCard": false,
"acceptBankAccount": false,
"saveCustomer": false,
"saveCustomerAccount": false,
"intent": {
"paymentTypes": [
"ACH",
"CreditCard",
"DebitCard"
]
}
},
"splits": [
{
"virtualAccount": "IPFS_DEFAULT",
"amount": 4909.2,
"reference": null,
"chargeIndicator": false
}
],
"saveForFuture": null,
"quoteKey": "26068787",
"accountNumber": null,
"referenceType": "None",
"referenceNumber": null,
"referenceKey": null,
"referenceDataList": [
{
"referenceType": "QuoteId",
"referenceNumber": "26068787",
"referenceKey": null
}
],
"enablePremiumFinance": true,
"suppressTechnologyFee": false
}