v1

latestOpenAPI 3.0.32026-07-131211345.4 KB

Payments and Liabilities

Retrieve Self Assessment Balance and Transactions

This endpoint enables you to retrieve the overall liability broken down into overdue, currently due (payable), and pending (not yet due) amounts. A National Insurance number must be provided.

Test data

Scenario simulation using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
NOT_FOUND	Simulates the scenario where no data is found.

get/accounts/self-assessment/{nino}/balance-and-transactions

Path parameters

ninostring required

Example:TC663795B

National Insurance number, in the format AA999999A.

Query parameters

docNumberstring

Example:3060013199

The docNumber is a unique number per tax grouping in the Account display. (When onlyOpenItems has been set to false, either the date range (fromDate and toDate) or doc number should be supplied.)

fromDatestring

Example:2019-01-02

The inclusive start date of the period to filter payments. The maximum date range between fromDate and toDate should not exceed 732 days.

toDatestring

Example:2019-01-02

The inclusive end date of the period to filter payments. The maximum date range between fromDate and toDate should not exceed 732 days.

onlyOpenItemsboolean

Limits the extraction to unpaid or not reversed charges.

(When onlyOpenItems has been set to false, either the date range (fromDate and toDate) or docNumber should be supplied.)

Defaults to false

includeLocksboolean

Example:true

Include additional information related to claim and debt management.

Defaults to false

calculateAccruedInterestboolean

Calculate accrued interest. Accruing interest is the amount of interest calculated

a) To today’s date (or in the case of a created statement, to the statement date)

b) On any overdue interest-bearing liability

No interest charge is created for an amount of accruing interest. An interest charge is only created when the related liability is paid in full.

removePOAboolean

Remove Payment on Account details. When true, details of any payments that the customer has made will not be returned.

Defaults to false.

customerPaymentInformationboolean

Include customer payment information in the response. When true, the following information is returned: Payment Reference, Payment Amount, Payment Method, Payment Lot, Payment Lot Item, Clearing SAP Document.

Note that if removePOA is true, no information is returned even if customerPaymentInformation is true.

Defaults to false.

includeEstimatedChargesboolean

Example:true

Include statistical (estimated) values for monthly payments.

Defaults to false.

Headers

Accept'application/vnd.hmrc.4.0+json' required

Specifies the response format and the version of the API to be used.

Authorizationstring required

Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the read:self-assessment scope.

Gov-Test-Scenariostring

Example:-

Only in sandbox environment. See Test Data table for all header values.

Response

Success

Example response

{
  "balanceDetails": {
    "payableAmount": 5009.99,
    "payableDueDate": "2018-04-05",
    "pendingChargeDueAmount": 5009.99,
    "pendingChargeDueDate": "2018-04-05",
    "overdueAmount": 5009.99,
    "bcdBalancePerYear": [
      {
        "taxYear": "2018-19",
        "bcdAmount": 5009.99
      }
    ],
    "earliestPaymentDateOverdue": "2018-04-05",
    "totalBalance": 5009.99,
    "amountCodedOut": 5009.99,
    "totalBcdBalance": 5009.99,
    "unallocatedCredit": 5009.99,
    "allocatedCredit": 5009.99,
    "totalCredit": 5009.99,
    "firstPendingAmountRequested": 5009.99,
    "secondPendingAmountRequested": 5009.99,
    "availableCredit": 5009.99
  },
  "codingDetails": [
    {
      "returnTaxYear": "2021-22",
      "totalLiabilityAmount": 5009.99,
      "codingTaxYear": "2021-22",
      "coded": {
        "charge": 5009.99,
        "initiationDate": "2021-04-05"
      }
    }
  ],
  "documentDetails": [
    {
      "taxYear": "2020-21",
      "documentId": "1455",
      "formBundleNumber": "068000003760",
      "creditReason": "Voluntary Payment",
      "documentDate": "2018-04-05",
      "documentText": "ITSA- Bal Charge",
      "documentDueDate": "2021-04-05",
      "documentDescription": "ITSA- POA 1",
      "originalAmount": 5009.99,
      "outstandingAmount": 5009.99,
      "lastClearing": {
        "lastClearingDate": "2018-04-05",
        "lastClearingReason": "Incoming Payment",
        "lastClearedAmount": 5009.99
      },
      "paymentLot": "AB1023456789",
      "paymentLotItem": "000001",
      "effectiveDateOfPayment": "2021-04-05",
      "latePaymentInterest": {
        "latePaymentInterestId": "1234567890123456",
        "accruingInterestAmount": 5009.99,
        "interestRate": 5.99,
        "interestStartDate": "2020-04-05",
        "interestEndDate": "2020-05-05",
        "interestAmount": 5009.99,
        "interestDunningLockAmount": 5009.99,
        "interestOutstandingAmount": 5009.99
      },
      "amountCodedOut": 5009.99,
      "reducedCharge": {
        "chargeType": "AA",
        "documentNumber": "1234567890123456",
        "amendmentDate": "2018-04-05",
        "taxYear": "2018-19"
      },
      "poaRelevantAmount": 5009.99
    }
  ],
  "financialDetails": [
    {
      "taxYear": "2020-21",
      "chargeDetail": {
        "documentId": "XAIS12345678910",
        "documentType": "3880",
        "documentTypeDescription": "ITSA- Bal Charge",
        "chargeType": "3175",
        "chargeTypeDescription": "Income Tax Estimate - NIC2 NI"
      },
      "taxPeriodFrom": "2020-04-06",
      "taxPeriodTo": "2021-04-05",
      "contractAccount": "X",
      "documentNumber": "1040000872",
      "documentNumberItem": "XM00",
      "chargeReference": "XM002610011594",
      "originalAmount": 5009.99,
      "outstandingAmount": 5009.99,
      "clearedAmount": 5009.99,
      "accruedInterest": 5009.99,
      "items": [
        {
          "itemId": "001",
          "dueDate": "2018-04-05",
          "amount": 5009.99,
          "clearingDate": "2018-04-05",
          "clearingReason": "Incoming Payment",
          "outgoingPaymentMethod": "Payable Order Repayment",
          "locks": {
            "isInterestAccrualOnHold": true,
            "isInterestChargeOnHold": true
          },
          "isReturn": true,
          "paymentReference": "Ab12453535",
          "paymentAmount": 5009.99,
          "paymentMethod": "BACS RECEIPTS",
          "paymentLot": "81203010024",
          "paymentLotItem": "000001",
          "clearingSAPDocument": "3350000253",
          "isChargeEstimate": true,
          "codedOutStatus": "initiated"
        }
      ]
    }
  ]
}