cds-reimbursement-claim

This is backend microservice providing a bridge between the CDS Reimbursement frontends and head-of-duty HMRC services through the EIS.

• Usage
• API endpoints
• Internals
  • Submitting a claim
  • Submitting a document
• External APIs
• Development

Usage

This service is available internally within the HMRC network and SHOULD NOT be used without agreement with the responsible business team.

Access to this service requires:

• Government Gateway session token
• Customs Declaration Service subscription

API endpoints

Method	Path	Description
GET	/declaration/:id	Retrieve customs declaration by MRN (NDRC)
GET	/declaration/:id/reason-for-security	Retrieve customs declaration by MRN (SCTY)
GET	/declaration/:id/claim-exists	Check is the claim exists for the given MRN
GET	/claims	Get existing claims given the EORI
GET	/claims/ndrc	Get existing NDRC claims given the EORI
GET	/claims/overpayments	Get existing overpayments claims given the EORI
GET	/claims/securities	Get existing securities claims given the EORI
GET	/claims/underpayments	Get existing underpayments claims given the EORI
GET	/claims/:cdfPayService/:cdfPayCaseNumber	Get claim details by case number
GET	/eori/xi	Get XI EORI connected with the current user's GB EORI
GET	/eori/:eori	Get details of the provided EORI
GET	/eori	Get details of the EORI connected with the currently authorised user
POST	/claims/overpayments-single	Submit a single overpayment claim
POST	/claims/overpayments-multiple	Submit a multiple overpayment claim
POST	/claims/overpayments-scheduled	Submit a scheduled overpayment claim
POST	/claims/rejected-goods-single	Submit a single rejected goods claim
POST	/claims/rejected-goods-multiple	Submit a multiple rejected goods claim
POST	/claims/rejected-goods-scheduled	Submit a scheduled rejected goods claim
POST	/claims/securities	Submit a security deposit claim
POST	/claims/files	Submit an evidence document

Internals

Internally the service consists of several types of components:

• http endpoints defined in conf/*.routes files
• action controllers classes
• services and repositories
• data model classes
• external http services connectors

The main job of the service is to map between frontend requests and relevant EIS requests/responses.

Submitting a TPI05 Claim

Each of the different type of TPI05 claims that are made have different TPI05 & DEC64 Mappers that convert the frontend request into the appropriate format

Submitting a DEC64 Document

To make DEC64 calls we are using the work-item-repo library which provides an asynchronous method for performing tasks.

When this service is started an instance of the CcsSubmissionPoller is spooled up. It is configured to periodically check the CcsSubmissionRepo to see if there are any requests that need to be made.

The tasks that need to be executed are queued up when making the TPI05 claim, the body of the DEC64 request that is made will be generated by the DEC64 mapper that is found in the Submit Claim section above.

External APIs

This service calls the following external APIs:

• Email service
• CDFPay/ETMP via EIS:
  • ACC14 - Customs declaration retrieval /accounts/overpaymentdeclarationdisplay/v1
  • SUB09 - CDS subscription /subscriptions/subscriptiondisplay/v1
  • TPI01 - Claims list /tpi/getpostclearancecases/v1
  • TPI02 - Claim details /tpi/getspecificcase/v1
  • TPI04 - Get existing claims /tpi/getexistingclaim/v1
  • TPI05 - Claim submission /tpi/postoverpaymentclaim/v1
  • DEC64 - File upload to CCS /filetransfer/init/v1

Development

This service is built using Play Framework and Scala language (https://www.scala-lang.org/).

Prerequisites

• Java 21
• SBT build tool

Build and test

sbt clean compile test

Run locally

Running this service locally requires multiple other services to be up and running. The best way to achieve that is by using Service Manager:

sm --start CDSRC_ALL

Run locally in a development mode

sm --start CDSRC_ALL
sm --stop CDSRC
sbt run

License

This code is open source software licensed under the Apache 2.0 License.