Create repayment

POST /api/v2/household/{HouseholdGUID}/liabilities/{LiabilityGUID}/repayments

This endpoint allows users to create a new liability repayment.

Only one calculated repayment is permitted for each liability. If a calculated repayment already exists for the liability, the request will return a 403 error.

Path parameters

  • HouseholdGUID string(uuid) Required

    The HouseholdGUID of the client.

  • LiabilityGUID string(uuid) Required

    The LiabilityGUID you want to create a repayment for.

application/json

Body Required

  • TransactionType integer Required

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • TransactionAmount number(float) | null

    This field is required if TransactionType = not 8.

  • InterestPayment integer | null

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • Frequency integer | null

    This field is required if TransactionType = not 8.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • StartBasis integer Required

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • StartEventGUID string(uuid) | null

    This field is required if the value of StartBasis = 4.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • StartAge integer | null

    This field is required if the value of StartBasis = 2 or 7.

    Minimum value is 0, maximum value is 130.

  • StartDate string | null

    This field is required if the value of StartBasis = 3. Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.

  • EndBasis integer | null

    This field is required if the value of Frequency = not 120 and the value of TransactionType = not 8.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • EndEventGUID string(uuid) | null

    This field is required if the value of EndBasis = 4 and the value of Frequency = not 120 and the value of TransactionType = not 8. Event end must be after starting.

    To retrieve a comprehensive list of acceptable values and their corresponding formatted values, you may make a request to the designated endpoint: /api/v2/household/{HouseholdGUID}/liabilities/repayments/options

  • EndAge integer | null

    This field is required if the value of EndBasis = 2 or 7 and the value of Frequency is not = 120 and the value of TransactionType is not = 8. EndAge must be after starting.

    Minimum value is 0, maximum value is 130.

  • EndDate string | null

    This field is required if the value of EndBasis = 3 and the value of Frequency is not = 120 and the value of TransactionType is not = 8. EndDate must be after starting. Dates should be provided in the format "Y-m-d", where "Y" represents the year, "m" represents the month and "d" represents the day. For example, "2023-07-24" represents 24th July, 2023.

  • BackOfficeID string | null

    Maximum length is 255.

  • BackOfficeSync integer | null

    An integer representing the status of the back office sync:

    • 1: Yes
    • 2: No
    • 3: Only update from back office
  • ExcludeFormattedValues string | null

    If set to any value, formatted values will be excluded from the response.

  • CalculatedRepayment integer | null

    This is an optional field. When provided, it must be set to 1. Once set, it overrides all other existing validation rules. Only one calculated repayment can exist for the corresponding liability. Additionally, when set, the transaction type will be automatically updated to 4. If the field is not provided, other validations will be applied as usual.

Responses

  • 201 application/json

    Success

    Hide response attributes Show response attributes object
    • success boolean

      Default value is true.

    • data object
      Hide data attributes Show data attributes object
      • TransactionGUID string(uuid)
      • TransactionType integer
      • LiabilityGUID string(uuid)
      • TransactionAmount number(float)
      • InterestPayment integer
      • Frequency integer
      • StartBasis integer
      • StartEventGUID string(uuid)
      • StartAge integer
      • StartDate string
      • EndBasis integer
      • EndEventGUID string(uuid)
      • EndAge integer
      • EndDate string
      • BackOfficeID string
      • BackOfficeSync integer
      • CalculatedRepayment integer | null
      • FormattedValues object
  • 403 application/json

    Permission error.

    Hide response attributes Show response attributes object
    • success boolean

      Default value is false.

    • message string
  • 404 application/json

    Household not found

    Hide response attributes Show response attributes object
    • success boolean

      Default value is false.

    • message string
  • 422 application/json

    Validation error.

    Hide response attributes Show response attributes object
    • success boolean

      Default value is false.

    • message string
    • data object

      Example validation error message.

      Hide data attribute Show data attribute object
      • ClientGUID array[string]
  • 500 application/json

    Internal server error.

    Hide response attributes Show response attributes object
    • success boolean

      Default value is false.

    • message string
POST /api/v2/household/{HouseholdGUID}/liabilities/{LiabilityGUID}/repayments
curl \
 --request POST 'https://api.fincalc.co.uk/api/v2/household/{HouseholdGUID}/liabilities/{LiabilityGUID}/repayments' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"TransactionType":4,"TransactionAmount":5000.1,"InterestPayment":1,"Frequency":26,"StartBasis":3,"StartEventGUID":"F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7","StartAge":42,"StartDate":"2024-01-01","EndBasis":3,"EndEventGUID":"F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7","EndAge":65,"EndDate":"2025-01-01","BackOfficeID":13573,"BackOfficeSync":1,"ExcludeFormattedValues":1,"CalculatedRepayment":2}'
Request examples
{
  "TransactionType": 4,
  "TransactionAmount": 5000.1,
  "InterestPayment": 1,
  "Frequency": 26,
  "StartBasis": 3,
  "StartEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
  "StartAge": 42,
  "StartDate": "2024-01-01",
  "EndBasis": 3,
  "EndEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
  "EndAge": 65,
  "EndDate": "2025-01-01",
  "BackOfficeID": 13573,
  "BackOfficeSync": 1,
  "ExcludeFormattedValues": 1,
  "CalculatedRepayment": 2
}
Response examples (201)
{
  "success": true,
  "data": {
    "TransactionGUID": "055CAE9F-6167-4186-8DE2-EC994D2222A2",
    "TransactionType": 4,
    "LiabilityGUID": "246C6E3A-3A3D-42A6-BEA3-85A8E3272C2C",
    "TransactionAmount": 5000.1,
    "InterestPayment": 1,
    "Frequency": 26,
    "StartBasis": 3,
    "StartEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
    "StartAge": 42,
    "StartDate": "2024-01-01",
    "EndBasis": 3,
    "EndEventGUID": "F3AAED8D-3A5F-44B5-BC6D-9E8C7646C9D7",
    "EndAge": 65,
    "EndDate": "2025-01-01",
    "BackOfficeID": "F7FBB6B1-2D90-485C-AE89-9F9FA0426F1E",
    "BackOfficeSync": 1,
    "CalculatedRepayment": 2,
    "FormattedValues": {
      "EndDate": "01/01/2025",
      "EndBasis": "Specific Date",
      "Frequency": "per fortnight",
      "StartDate": "01/01/2024",
      "StartBasis": "Specific Date",
      "LiabilityGUID": "API Test",
      "TransactionType": "Liability Repayment",
      "TransactionAmount": "£5,000",
      "CalculatedRepayment": "No"
    }
  }
}
Response examples (403)
{
  "success": false,
  "message": "You do not have permission to edit the household."
}
Response examples (404)
{
  "success": false,
  "message": "Household not found."
}
Response examples (422)
{
  "success": false,
  "message": "Validation Error.",
  "data": {
    "ClientGUID": [
      "The client guid field is required."
    ]
  }
}
Response examples (500)
{
  "success": false,
  "message": "Failed to create liability repayment in household"
}