experience-calculator-api

API Type

• Experience API

Overview:

Pepper Mule to expose Calculator API for digital consumption across Pepper and external partner websites. This lightweight API allows Pepper to provide the appropriate calculations. The Experience Calculator API provides calculator-related services to business consumers through a unified and secure interface. It serves as the Experience Layer within the MuleSoft API-led connectivity architecture, orchestrating requests between business applications and downstream systems.

The API performs authentication, request validation, payload transformation, backend invocation through the System Mortgage API, and response transformation before returning standardized responses to consumers.

Features

• Basic Authentication
• Request Header Validation
• Payload Validation (POST)
• Query Parameter Validation (GET)
• Request Transformation
• Response Transformation
• Standardized Error Responses
• Secure communication with downstream services

Available Resources

Architecture

Architecture Description

The Experience Calculator API receives requests from business consumers and forwards them to the System Mortgage API. The System Mortgage API transforms the request and communicates with Appian, which interacts with backend services. Responses follow the reverse path, with transformations applied before the final response is returned to the consumer.

Step-by-Step Integration Flow:

The Calculator API follows a common processing flow for all endpoints. The API acts as an orchestration layer between the business consumers and Appian by performing authentication, validation, request transformation, backend invocation, and response transformation.

Common Processing Flow

1. Business consumer sends a request to the Calculator API.
2. Validate Basic Authentication credentials.
3. Validate mandatory request headers.
4. Validate the incoming request payload (applicable for POST endpoints) and validate query parameters (applicable for the GET Postcode Lookup endpoint).
5. For the Get Postcode Lookup endpoint (GET), prepare the Appian request using the following query parameters:`searchTextcountrystate`
6. Prepare the Appian request payload based on the incoming request.
7. Invoke the corresponding Appian service.
8. Appian communicates with the backend services and retrieves the required data.
9. Receive the response from Appian.
10. Transform the Appian response into the Calculator API response model.
11. Return the transformed response to the business consumer.

Authentication:

• Basic Auth
• Rate Limiting
• IP Allowlist

Endpoints

Error Handling

Authentication Errors:

• Invalid Basic Authentication credentials
• Unauthorized access response returned

Validation Errors:

• Missing mandatory fields
• Invalid request structure
• Code Validation

Downstream API Errors:

• System Mortgage API failure
• Appian backend failure

All errors are transformed into standardized API error responses before returning to the source system.

Status Response Codes:

• 200: OK
• 401: Unauthorized - Check whether your credentials are correct
• 404: Resource Not Found - Check if you have correct resource URI
• 405: Method Not Allowed - Check if you have valid methods for the resource
• 408: Request Timeout - The API could be still processing your request, try to adjust connection timeout
• 500: Unexpected Server Error - If this issue persists, contact support for troubleshooting
• 503: Service Unavailable - Server is handling too many request at this moment. try again later or reach out to support if issue persists
• 504: Gateway Timeout - There might be a problem with the load-balancer, reach out to support if issue persists

Contact

Code Repository:

Notes:

• Feature development should be done using feature/* branches.
• Pull request approval is mandatory before merge.
• Release tags should follow versioning standards.

Test API Endpoint:

Basic Authentication Details:

Calculate LPF with Payment Sample Request:

{
"portfolio": "PRIME",
"channel": "Retail",
"loanamount": 40000,
"doctype": "Full Doc",
"loanPurpose": "Purchase",
"isPlus": false,
"isConstruction": true,
"isVacantLand": false,
"paymentMethod": "DeductedFromLoan",
"aggregatorCode": "PEP",
"securities": [
{
        "propertyType": "House",
            "numberOfUnits": 0,
            "constructionLandSize": 0,
            "propertyLandSize": 0,
            "floorArea": 0,
            "securityValue": 80000,
            "securityPostcodeDetails": {
                "unformated_address": "34 Test",
                "postcode": 2000,
                "suburb": "BARANGAROO",
                "state": "NSW",
                "country": "AU"
            }
        },
        {
            "propertyType": "House",
            "numberOfUnits": 0,
            "constructionLandSize": 0,
            "propertyLandSize": 0,
            "floorArea": 0,
            "securityValue": 4000,
            "securityPostcodeDetails": {
                "unformated_address": "34 Test",
                "postcode": 7469,
                "suburb": "ZEEHAN",
                "state": "TAS",
                "country": "AU"
            }
        }
    ]
}

Calculate LPF with Payment Sample Success Response:

{
    "LPFResult": {
        "feeType": "LPF",
        "feeValue": 1223.71,
        "initialLVR": 47.62,
        "finalLVR": 47.62,
        "maxLVR": 95,
        "totalLoanValue": 40000,
        "totalSecurityValue": 84000,
        "netProceeds": 38776.29,
        "message": ""
    },
    "LPFRequestData": {
        "channel": "Retail",
        "loanPurpose": "Purchase",
        "loanAmount": 40000,
        "isPlus": false,
        "productName": "PRIME",
        "isConstruction": true,
        "isVacantLand": false,
        "docType": "Full Doc",
        "paymentMethod": "DeductedFromLoan",
        "aggregatorCode": "PEP",
        "securities": [
            {
                "propertyType": "House",
                "numberOfUnits": 0,
                "constructionLandSize": 0,
                "propertyLandSize": 0,
                "floorArea": 0,
                "securityValue": 80000,
                "securityPostcodeDetails": {
                    "unformated_address": "34 Test",
                    "postcode": 2000,
                    "suburb": "BARANGAROO",
                    "state": "NSW",
                    "country": "AU"
                }
            },
            {
                "propertyType": "House",
                "numberOfUnits": 0,
                "constructionLandSize": 0,
                "propertyLandSize": 0,
                "floorArea": 0,
                "securityValue": 4000,
                "securityPostcodeDetails": {
                    "unformated_address": "34 Test",
                    "postcode": 7469,
                    "suburb": "ZEEHAN",
                    "state": "TAS",
                    "country": "AU"
                }
            }
        ]
    }
}

Calculate LPF without Payment Sample Request:

{
  "propertyValue": "800000",
  "loanPurpose": "Refinance",
  "loanAmount": "750000",
  "isInvestment": "true",
  "productName": "Prime",
  "isConstruction": "false",
  "docType": "Full Doc"
}

Calculate LPF without Payment Sample Success Response:

{
    "LPFResult": {
        "feeType": "LPF",
        "feeValue": 1223.71,
        "initialLVR": 47.62,
        "finalLVR": 47.62,
        "maxLVR": 95,
        "totalLoanValue": 40000,
        "totalSecurityValue": 84000,
        "netProceeds": 38776.29,
        "message": ""
    },
    "LPFRequestData": {
        "propertyValue": "800000",
        "channel": null,
        "loanPurpose": "Refinance",
        "loanAmount": "750000",
        "isInvestment": "true",
        "productName": "Prime",
        "isConstruction": "false",
        "isVacantLand": null,
        "docType": "Full Doc",
        "paymentMethod": null
    }
}

Post Code Risk Rating Sample Request:

{
    "postcode": "6210",
    "suburb": "FURNISSDALE",
    "country": "AU",
    "loanPurpose": "Purchase",
    "isConstruction": "true",
    "noOfDwelling": "One Dwelling",
    "dwellingType": "New Unit",
    "isInvestment": false
}

Post Code Risk Rating Sample Success Response:

{
    "Result": {
        "locationLimitMatrix": {
            "Residential": [
                {
                    "ProductGroup": "Prime",
                    "DocType": "Full Doc",
                    "PlusFlag": false,
                    "LVRFrom": "0.00",
                    "LVRUpto": "0.65",
                    "Amount": 2000000,
                    "Portfolio": "Residential"
                },
                {
                    "ProductGroup": "Prime",
                    "DocType": "Full Doc",
                    "PlusFlag": false,
                    "LVRFrom": "0.65",
                    "LVRUpto": "0.70",
                    "Amount": 2000000,
                    "Portfolio": "Residential"
                }
            ],
            "Commercial": [],
            "SMSF": []
        },
        "category": 2,
        "success": true,
        "message": "",
        "disclaimer": [
            "Maximum LVR on new units (< 12 months old) of 75%, when product is not prime."
        ]
    },
    "RequestData": {
        "postcode": "6210",
        "suburb": "FURNISSDALE",
        "country": "AU",
        "loanPurpose": "Purchase",
        "isConstruction": "true",
        "dwellingType": "New Unit",
        "noOfSecurities": null,
        "isInvestment": false,
        "loanType": null,
        "isVacant": null,
        "assetType": null,
        "isSMSF": null,
        "noOfDwelling": "One Dwelling"
    }
}

Post Code Lookup Sample Request:

https://api-test.pepper.com.au/sit/v1/postcodeLookup?SearchText=2000&country=AU&state=NWS

Calculate LPF with Payment Sample Success Response:

{
    "PostcodeLookupResult": {
        "message": "Success",
        "Address": [
            {
                "@Suburb": "BARANGAROO",
                "@Postcode": "2000",
                "@PostcodeRiskRating": 1,
                "@HighDensityFlag": true,
                "@State": "NSW"
            },
            {
                "@Suburb": "DARLING HARBOUR",
                "@Postcode": "2000",
                "@PostcodeRiskRating": 1,
                "@HighDensityFlag": true,
                "@State": "NSW"
            }
        ]
    },
    "PostcodeLookupRequestData": {
        "@SearchText": "2000",
        "@State": "NSW",
        "@Country": "AU"
    }
}

Lender's Protection Fee Calculator:

Lender protection Fee is a one-off, non-refundable fee used to offset the risk associated with loans of a higher Loan to Value Ratio (LVR).

• LPF amount get calculated on basis of ProductType, docType, isConstruction, isInvestment and Final LVR.
• Lender's Protection Fee is charged on Prime loans - Full Doc Owner Occupier loans >85% LVR, Full Doc Investment loans >80% LVR and Alt Doc >70% LVR.

Note : "productName": "Prime", in all cases.

Max LVR limit is 95%.

Postcode Risk Rating:

Enter the postcode of the security property to determine the maximum loan amount we will lend.

• To Get detailed risk and limits matrix for a postcode and loan details.

Postcode Lookup:

This API endpoint allows users to retrieve the suburbs associated with a specific postcode in Australia (AU) and New Zealand (NZ). It returns a list of suburbs that correspond to the provided postcode, facilitating location-based searches and services.