API Documentation

Finance Product Management

The Finance Product Management API allows you to create and maintain root level finance products.

The Finance Product Resource

Properties

  • Name
    id
    Required
    Type
    integer
    Description

    Unique Identifier for the finance product

  • Name
    product
    Required
    Type
    object
    Description
    • Name
      name
      Required
      Type
      string
      Description

      User friendly name of the finance product which can be shown to customers

    • Name
      key
      Required
      Type
      string
      Description

      Machine friendly name of the finance product which can be used for product comparisons

    • Name
      description
      Required
      Type
      string
      Description

      A brief description that explains the finance product in a way the customer will understand

  • Name
    features
    Required
    Type
    object
    Description
    • Name
      who
      Required
      Type
      string
      Description

      Explains who this product is aimed at, or who it may be suitable for

    • Name
      deposit
      Required
      Type
      string
      Description

      What kind of deposit would be required for this product

    • Name
      period
      Required
      Type
      string
      Description

      The rough payment period typical for this product

    • Name
      options
      Required
      Type
      string
      Description

      Options available to the customer at the end of the finance period

    • Name
      ownership
      Required
      Type
      string
      Description

      Will the customer own the vehicle at the end of the agreement?

    • Name
      mileage
      Required
      Type
      string
      Description

      Could mileage restrictions apply?

    • Name
      term
      Required
      Type
      string
      Description

      Are the term and payments / rentals fixed or variable?

    • Name
      balloon
      Required
      Type
      string
      Description

      Is there a balloon or lump sum due at the end of the agreement?

    • Name
      vat
      Required
      Type
      string
      Description

      Do payments / rentals attract VAT?

    • Name
      cca
      Required
      Type
      string
      Description

      Am I protected by the Consumer Credit Act? Subject to balance financed (restrictions may apply)

    • Name
      keeper
      Required
      Type
      string
      Description

      Will the customer be the registered keeper of the vehicle?

    • Name
      insurance
      Required
      Type
      string
      Description

      Will the customer require fully comprehensive motor insurance?

    • Name
      risk
      Required
      Type
      string
      Description

      Is the vehicle is at risk of repossession if the customer does not maintain the contractual payments?

  • Name
    dates
    Required
    Type
    object
    Description
    • Name
      created_at
      Required
      Type
      datetime
      Description

      The date the product was created, represented in YYYY-MM-DD HH:MM:SS format

    • Name
      updated_at
      Required
      Type
      datetime
      Description

      The date the product was last updated, represented in YYYY-MM-DD HH:MM:SS format

    • Name
      deleted_at
      Required
      Type
      datetime | null
      Description

      The date the product was deleted, represented in YYYY-MM-DD HH:MM:SS format. Will be set to null if not deleted.

Finance Product Resource

{
  "id": 1,
  "product": {
    "name": "Hire Purchase",
    "key": "hp",
    "description": "I am happy to put down a deposit, make equal monthly payments for a fixed term and own the vehicle at the end of the agreement"
  },
  "features": {
    "who": "Consumers, sole traders and partnerships",
    "deposit": "Available from nil deposit dependent upon status",
    "period": "12 - 60 months",
    "options": "Retain vehicle or part exchange",
    "ownership": "Yes",
    "mileage": "No",
    "term": "Fixed",
    "balloon": "No",
    "vat": "No",
    "cca": "Yes",
    "keeper": "Yes",
    "insurance": "Yes",
    "risk": "Yes"
  },
  "dates": {
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-02 12:00:00",
    "deleted_at": null
  }
}
GET/v2/finance/products

Search Products

The search finance products endpoint uses the standard Search package from the SDK.

An array of finance product resources are returned. If no results are found, an empty collection is returned.

Search Filters

  • Name
    filters.id.equals
    Required
    Type
    integer
    Description

    Match a single product by ID

  • Name
    filters.id.in
    Required
    Type
    array<integer>
    Description

    Match products by multiple IDs

  • Name
    filters.[key|product_key].equals
    Required
    Type
    string
    Description

    Match products by key

  • Name
    filters.[key|product_key].in
    Required
    Type
    array<stringr>
    Description

    Match products by multiple keys

  • Name
    filters.[name|product_name].equals
    Required
    Type
    string
    Description

    Match a single product by name

  • Name
    filters.[name|product_name].in
    Required
    Type
    array<string>
    Description

    Match products by multiple names

  • Name
    filters.[name|product_name].contains
    Required
    Type
    string
    Description

    Match products by partial name

  • Name
    filters.is_deleted.equals
    Required
    Type
    boolean
    Description

    Filter records by whether its been deleted or not

Search Ordering

  • id
  • product_key / key
  • product_name / name
  • description
  • eligibility_who / who
  • eligibility_deposit / deposit
  • eligibility_period / period
  • eligibility_options / options
  • eligibility_ownership / ownership
  • eligibility_mileage / mileage
  • eligibility_term / term
  • eligibility_balloon / balloon
  • eligibility_vat / vat
  • eligibility_cca / cca
  • eligibility_keeper / keeper
  • eligibility_insurance / insurance
  • eligibility_risk / risk
  • created_at / created
  • updated_at / updated
  • deleted_at / deleted

Request

GET
/v2/finance/products
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;
use Compliance\Sdk\Search\Search;

private ApexV3SdkInterface $sdk;

$search = new Search();

$response = $this->sdk
  ->v2(new Machine())
  ->finance()
  ->products()
  ->search($search);

Response

{
  "data": [
    {
      "id": 1,
      "product": {
        "name": "Hire Purchase",
        "key": "hp",
        "description": "I am happy to put down a deposit, make equal monthly payments for a fixed term and own the vehicle at the end of the agreement"
      },
      "features": {
        "who": "Consumers, sole traders and partnerships",
        "deposit": "Available from nil deposit dependent upon status",
        "period": "12 - 60 months",
        "options": "Retain vehicle or part exchange",
        "ownership": "Yes",
        "mileage": "No",
        "term": "Fixed",
        "balloon": "No",
        "vat": "No",
        "cca": "Yes",
        "keeper": "Yes",
        "insurance": "Yes",
        "risk": "Yes"
      },
      "dates": {
        "created_at": "2024-01-01 00:00:00",
        "updated_at": "2024-01-02 12:00:00",
        "deleted_at": null
      }
    }
  ]
}
GET/v2/finance/products/:identifier

Retrieve Product

Will retrieve a specific generation record by ID or key. If a numeric identifier is provided, the lookup will be done by ID. If an identifier contains non-numeric characters, the lookup will be done by key. The latest record is returned.

URL Parameters

  • Name
    identifier
    Required
    required
    Type
    integer|string
    Description

    ID or key of the finance product to return

Error Codes

Status Description
404 The requested product could not be found

Request

GET
/v2/finance/products/:identifier
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->finance()
  ->product(1)
  ->get();

Response

{
  "data": {
    "id": 1,
    "product": {
      "name": "Hire Purchase",
      "key": "hp",
      "description": "I am happy to put down a deposit, make equal monthly payments for a fixed term and own the vehicle at the end of the agreement"
    },
    "features": {
      "who": "Consumers, sole traders and partnerships",
      "deposit": "Available from nil deposit dependent upon status",
      "period": "12 - 60 months",
      "options": "Retain vehicle or part exchange",
      "ownership": "Yes",
      "mileage": "No",
      "term": "Fixed",
      "balloon": "No",
      "vat": "No",
      "cca": "Yes",
      "keeper": "Yes",
      "insurance": "Yes",
      "risk": "Yes"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null
    }
  }
}
POST/v2/finance/products

Create Product

This endpoint can be called to create a finance product.

Payload

  • Name
    name
    Required
    required
    Type
    string
    Description

    The user friendly name of the finance product

  • Name
    key
    Required
    required
    Type
    string
    Description

    The machine friendly name of the finance product

  • Name
    description
    Required
    required
    Type
    string
    Description

    The user friendly description for this finance product

  • Name
    features
    Required
    required
    Type
    object
    Description
    • Name
      who
      Required
      required
      Type
      string
      Description

      Explains who this product is aimed at, or who it may be suitable for

    • Name
      deposit
      Required
      required
      Type
      string
      Description

      What kind of deposit would be required for this product

    • Name
      period
      Required
      required
      Type
      string
      Description

      The rough payment period typical for this product

    • Name
      options
      Required
      required
      Type
      string
      Description

      Options available to the customer at the end of the finance period

    • Name
      ownership
      Required
      required
      Type
      string
      Description

      Will the customer own the vehicle at the end of the agreement?

    • Name
      mileage
      Required
      required
      Type
      string
      Description

      Could mileage restrictions apply?

    • Name
      term
      Required
      required
      Type
      string
      Description

      Are the term and payments / rentals fixed or variable?

    • Name
      balloon
      Required
      required
      Type
      string
      Description

      Is there a balloon or lump sum due at the end of the agreement?

    • Name
      vat
      Required
      required
      Type
      string
      Description

      Do payments / rentals attract VAT?

    • Name
      cca
      Required
      required
      Type
      string
      Description

      Am I protected by the Consumer Credit Act? Subject to balance financed (restrictions may apply)

    • Name
      keeper
      Required
      required
      Type
      string
      Description

      Will the customer be the registered keeper of the vehicle?

    • Name
      insurance
      Required
      required
      Type
      string
      Description

      Will the customer require fully comprehensive motor insurance?

    • Name
      risk
      Required
      required
      Type
      string
      Description

      Is the vehicle is at risk of repossession if the customer does not maintain the contractual payments?

Error Codes

Status Description
409 The key provided is already being used by an existing product
422 The data provided was invalid. Review the response for details.

Request

POST
/v2/finance/products
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->finance()
  ->products()
  ->create(
    'Test Product',
    'test-product',
    'This is a test product',
    'who' => 'Who details',
    'deposit' => 'Deposit details',
    'period' => 'Period details',
    'options' => 'Options details',
    'ownership' => 'Ownership details',
    'mileage' => 'Mileage details',
    'term' => 'Term details',
    'balloon' => 'Balloon details',
    'vat' => 'VAT details',
    'cca' => 'CCA details',
    'keeper' => 'Keeper details',
    'insurance' => 'Insurance details',
    'risk' => 'Risk Details',
  );

Response

{
  "data": {
    "id": 2,
    "product": {
      "name": "Test Product",
      "key": "test-product",
      "description": "This is a test"
    },
    "features": {
      "who": "Who details",
      "deposit": "Deposit details",
      "period": "Period details",
      "options": "Options details",
      "ownership": "Ownership details",
      "mileage": "Mileage details",
      "term": "Term details",
      "balloon": "Balloon details",
      "vat": "VAT details",
      "cca": "CCA details",
      "keeper": "Keeper details",
      "insurance": "Insurance details",
      "risk": "Risk details"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null
    }
  }
}
POST/v2/finance/products/:product_id

Update Product

This endpoint can be called to update an existing finance product.

Only fields provided in the request are updated. Any fields not explicitly sent in the request will remain unchanged.

Unlike the retrieval endpoint, a product can only be updated using its numeric key

URL Parameters

  • Name
    product_id
    Required
    required
    Type
    integer
    Description

    ID of the product to update

Payload

  • Name
    name
    Required
    Type
    string
    Description

    The user friendly name of the finance product

  • Name
    description
    Required
    Type
    string
    Description

    The user friendly description for this finance product

  • Name
    who
    Required
    Type
    string
    Description

    Explains who this product is aimed at, or who it may be suitable for

  • Name
    deposit
    Required
    Type
    string
    Description

    What kind of deposit would be required for this product

  • Name
    period
    Required
    Type
    string
    Description

    The rough payment period typical for this product

  • Name
    options
    Required
    Type
    string
    Description

    Options available to the customer at the end of the finance period

  • Name
    ownership
    Required
    Type
    string
    Description

    Will the customer own the vehicle at the end of the agreement?

  • Name
    mileage
    Required
    Type
    string
    Description

    Could mileage restrictions apply?

  • Name
    term
    Required
    Type
    string
    Description

    Are the term and payments / rentals fixed or variable?

  • Name
    balloon
    Required
    Type
    string
    Description

    Is there a balloon or lump sum due at the end of the agreement?

  • Name
    vat
    Required
    Type
    string
    Description

    Do payments / rentals attract VAT?

  • Name
    cca
    Required
    Type
    string
    Description

    Am I protected by the Consumer Credit Act? Subject to balance financed (restrictions may apply)

  • Name
    keeper
    Required
    Type
    string
    Description

    Will the customer be the registered keeper of the vehicle?

  • Name
    insurance
    Required
    Type
    string
    Description

    Will the customer require fully comprehensive motor insurance?

  • Name
    risk
    Required
    Type
    string
    Description

    Is the vehicle is at risk of repossession if the customer does not maintain the contractual payments?

Error Codes

Status Description
409 The key provided is already being used by an existing product
422 The data provided was invalid. Review the response for details.

Request

PUT
/v2/finance/products/:product_id
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->finance()
  ->product(2)
  ->update([
    'name' => 'Test Product',
    'description' => 'This is a test product',
    'who' => 'Who details',
    'deposit' => 'Deposit details',
    'period' => 'Period details',
    'options' => 'Options details',
    'ownership' => 'Ownership details',
    'mileage' => 'Mileage details',
    'term' => 'Term details',
    'balloon' => 'Balloon details',
    'vat' => 'VAT details',
    'cca' => 'CCA details',
    'keeper' => 'Keeper details',
    'insurance' => 'Insurance details',
    'risk' => 'Risk Details',
  ]);

Response

{
  "data": {
    "id": 2,
    "product": {
      "name": "Test Product",
      "key": "test-product",
      "description": "This is a test"
    },
    "features": {
      "who": "Who details",
      "deposit": "Deposit details",
      "period": "Period details",
      "options": "Options details",
      "ownership": "Ownership details",
      "mileage": "Mileage details",
      "term": "Term details",
      "balloon": "Balloon details",
      "vat": "VAT details",
      "cca": "CCA details",
      "keeper": "Keeper details",
      "insurance": "Insurance details",
      "risk": "Risk details"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": null
    }
  }
}
DELETE/v2/finance/products/:product_id

Delete Product

This endpoint can be called to delete a finance product.

Unlike the retrieval endpoint, a product can only be deleted using its numeric key

URL Parameters

  • Name
    product_id
    Required
    required
    Type
    integer
    Description

    ID of the product to delete

Error Codes

Status Description
404 The product couldn't be found

Request

DELETE
/v2/finance/products/:product_id
use Compliance\Sdk\ApexV3\Contracts\ApexV3SdkInterface;
use Compliance\Sdk\Authentication\Types\Machine;

private ApexV3SdkInterface $sdk;

$response = $this->sdk
  ->v2(new Machine())
  ->finance()
  ->product(1)
  ->delete();

Response

{
  "data": {
    "id": 1,
    "product": {
      "name": "Hire Purchase",
      "key": "hp",
      "description": "I am happy to put down a deposit, make equal monthly payments for a fixed term and own the vehicle at the end of the agreement"
    },
    "features": {
      "who": "Consumers, sole traders and partnerships",
      "deposit": "Available from nil deposit dependent upon status",
      "period": "12 - 60 months",
      "options": "Retain vehicle or part exchange",
      "ownership": "Yes",
      "mileage": "No",
      "term": "Fixed",
      "balloon": "No",
      "vat": "No",
      "cca": "Yes",
      "keeper": "Yes",
      "insurance": "Yes",
      "risk": "Yes"
    },
    "dates": {
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-02 12:00:00",
      "deleted_at": "2025-01-01 00:00:00"
    }
  }
}