ToolStation - Internal Docs
Routes

Trade Credit

Overview

The Trade Credit API includes endpoints for managing trade credit applications, handling customer documents, and processing payments. It allows you to submit, save, and retrieve applications, generate signed URLs for documents, and manage credit agreements. Payment operations cover bank transfers, direct debits, and SSO authentication for customers. Refer to the endpoint documentation for detailed information. GET route for health checks (newsletters/_ping) and a POST route (newsletters/signup) that allows users to sign up for newsletters using the create method from NewsletterController. The routes are organized under a newsletters prefix, promoting clean and maintainable code.

Submit Trade Credit Application

  • Route: POST ../trade-credit/application/
  • Controller: TradeCreditController
  • Method: submitApplication
  • Request: Request
  • Description: Endpoint to submit a new trade credit application. Acts as a proxy between e-commerce clients and the internal trade credit service, handling all validation within that service.

The submitApplication method processes the request data and submits it to the trade credit service. It returns a TradeCreditApplicationResponse containing the result of the application submission.

Save Application

  • Route: POST ../trade-credit/application/save
  • Controller: SavedApplicationController
  • Method: store
  • Request: CreateApplicationRequest
  • Description: Endpoint to save an application. It validates the request data and creates a new application. If a token is provided, it checks for its existence and validates the associated pin and email.

The store method in the SavedApplicationController processes the request to save an application. It validates the token and checks the pin and email if a token is present. If validation is successful, it creates a new application and returns the token with a 201 Created status.

Continue Application

  • Route: POST ../trade-credit/application/continue/{token}
  • Controller: SavedApplicationController
  • Method: get
  • Request: ContinueApplicationRequest
  • Description: Endpoint to retrieve a saved application based on a token. It validates the request data, checks the pin and email, and returns the application's state if the token is valid.

The get method in the SavedApplicationController retrieves a saved application using the provided token. It first checks the validity of the token and then verifies the pin and email. If valid, it returns the application's state. Otherwise, it responds with appropriate HTTP status codes: 404 Not Found if the application is not found, or 403 Forbidden if validation fails.

Generate Customer Document Signed URL

  • Route: POST ../trade-credit/customer-documents/signed-url
  • Controller: TradeCreditController
  • Method: generateCustomerDocumentSignedUrl
  • Request: CustomerDocumentSignedUrlRequest
  • Description: Endpoint to generate a signed URL for uploading customer documents. The method constructs a storage reference and generates a signed URL with a timeout for secure upload.

The generateCustomerDocumentSignedUrl method in the TradeCreditController generates a signed URL for uploading a customer document. It uses the filename and content_type from the request to create a storage reference. It then generates a signed URL using the signedUrlService, which allows for secure document uploads with a specific timeout. The method logs the process and returns the signed URL, storage reference, and original filename if successful. If an error occurs, it logs the issue and returns a 400 Bad Request response.

Request Data:

  • filename (string): The name of the file to be uploaded.
  • content_type (string): The MIME type of the file.

Response Data:

  • signed_url (string): The generated signed URL for document upload.
  • storage_reference (string): The storage reference used for the document.
  • original_filename (string): The original name of the file.

Errors:

  • 400 Bad Request: If there is an issue generating the signed URL.

Sign Credit Agreement

  • Route: POST ../trade-credit/sign-credit-agreement
  • Controller: TradeCreditController
  • Method: signCreditAgreement
  • Request: CustomerSignatureRequest
  • Description: Endpoint to generate a signature ID for signing a credit agreement. The method uses the request data to generate a signature ID through the signatureService.

The signCreditAgreement method in the TradeCreditController generates a signature ID needed for signing a credit agreement. It utilizes the signatureService to obtain a signature ID using details from the request, including company_name, name, and email. After generating the signature ID, the method logs the success and returns the signature_id in the response.

Request Data:

  • name (string): The name of the individual signing the agreement.
  • email (string): The email address of the individual signing the agreement.
  • company_name (string): The name of the company associated with the agreement.

Response Data:

  • signature_id (string): The generated signature ID.

Errors:

  • If validation fails, a 422 Unprocessable Entity response with validation errors will be returned.

Get Credit Agreement to Sign

  • Route: GET ../trade-credit/sign-credit-agreement
  • Controller: TradeCreditController
  • Method: getCreditAgreementToSign
  • Request: Request
  • Description: Endpoint to retrieve the URL for signing a credit agreement. It generates a view with the signature URL and client ID.

The getCreditAgreementToSign method in the TradeCreditController generates a URL for signing the credit agreement. It uses the getSignatureUrl private method to fetch the URL based on the signature_id provided in the request. The method then returns a view containing the clientId and the signatureUrl.

Request Data:

  • signature_id (string): The ID used to retrieve the signature URL.

Response:

  • Returns a view named signing-request with the following data:
    • clientId (string): Client ID for the signing service.
    • signatureUrl (string): URL for signing the credit agreement.

Errors:

  • If signature_id is missing or invalid, a 400 Bad Request response will be returned.
  • If the signature URL cannot be retrieved, a 400 Bad Request response will be returned, and an error will be logged.

Get Credit Agreement Signature URL

  • Route: GET ../trade-credit/credit-agreement-signature-url
  • Controller: TradeCreditController
  • Method: getCreditAgreementSignatureUrl
  • Request: Request
  • Description: Endpoint to retrieve the URL for signing the credit agreement in JSON format.

The getCreditAgreementSignatureUrl method in the TradeCreditController fetches the URL required for signing the credit agreement. It uses the getSignatureUrl private method to obtain the URL based on the provided signature_id. The method then returns a JSON response containing the client_id and the signature_url.

Request Data:

  • signature_id (string): The ID used to retrieve the signature URL.

Response:

  • Returns a JSON response with the following data:
    • client_id (string): Client ID for the signing service.
    • signature_url (string): URL for signing the credit agreement.

Errors:

  • If signature_id is missing or invalid, a 400 Bad Request response will be returned.
  • If the signature URL cannot be retrieved, a 400 Bad Request response will be returned, and an error will be logged.

Bank Transfer

  • Route: POST ../trade-credit/payment/bank-transfer
  • Controller: TradeCreditController
  • Method: bankTransfer
  • Request: BankTransferRequest
  • Description: Initiates a bank transfer and returns a response with transfer details.

The bankTransfer method in the TradeCreditController processes a bank transfer request. It uses the BankTransferRequest to validate the request and authorize the user. The method then sends the transfer details to an external service and returns a JSON response with the URL and ID of the bank transfer.

Request Data:

  • amount (float): The amount to be transferred.

Response:

  • On success, returns a JSON response with:
    • url (string): URL to complete the bank transfer.
    • id (string): Identifier for the transfer.

Errors:

  • If the request fails or the response status is not OK, a 400 Bad Request response is returned, and an error is logged.
  • If the user is unauthorized or no valid account is found, the request is denied with appropriate responses.

Bank Transfer Details

  • Route: POST ../trade-credit/payment/bank-transfer/details
  • Controller: TradeCreditController
  • Method: getBankTransferDetails
  • Request: BankTransferDetailsRequest
  • Description: Retrieves detailed information about a specific bank transfer.

The getBankTransferDetails method in the TradeCreditController fetches detailed information for a bank transfer using a transfer ID. It validates the request and authorizes the user before querying the external service. The method then formats the response and logs the outcome.

Request Data:

  • transfer_id (string): The identifier for the bank transfer.

Response:

  • On success, returns a JSON response with:
    • amount (float): The amount of the transfer.
    • amount_formatted (string): Formatted amount with currency symbol.
    • date (string): Date when the transfer was created.
    • reference (string): Transfer reference.
    • description (string): Transfer description.
    • payee (string): Name of the payee.
    • sort_code (string): Formatted sort code.
    • account_number (string): Last digits of the sort code representing the account number.
    • outcome (int): Outcome status of the transfer.
    • error (string | null): Error message if applicable.

Errors:

  • If the request fails or the response status is not OK, a 400 Bad Request response is returned, and an error is logged.
  • If the user is unauthorized or invalid transfer_id is provided, the request is denied with appropriate responses.

Request Direct Debit Mandate

  • Route: GET ../trade-credit/payment/direct-debit/request-mandate
  • Controller: DirectDebitController
  • Method: requestMandate
  • Request: Request
  • Description: Requests a direct debit mandate for the customer if one does not already exist.

The requestMandate method in the DirectDebitController handles the process of requesting a direct debit mandate. It first checks if the customer’s account already has an existing mandate. If a mandate is present, it returns a 400 Bad Request response. If not, it makes a request to an external service to initiate the mandate process and returns the response data.

Request Data:

  • The request does not need specific parameters but requires the user to be authenticated.

Response:

  • Success:
    • Returns a JSON response with the data from the external service if the mandate request is successfully processed.
  • Failure:
    • If a mandate already exists, returns a 400 Bad Request response with a message indicating that the account already has a mandate.
    • If an error occurs during the direct debit request, returns a 500 Internal Server Error response with an error message. The error details are logged for debugging purposes.

Error Handling:

  • BadResponseException: If the external service responds with an error, a 500 Internal Server Error is returned. The error message is logged for further investigation.

Cancel Direct Debit Mandate

  • Route: DELETE ../trade-credit/payment/direct-debit/mandate
  • Controller: DirectDebitController
  • Method: cancelMandate
  • Request: Request
  • Description: Cancels an existing direct debit mandate for the customer.

The cancelMandate method in the DirectDebitController handles the cancellation of a direct debit mandate. It first verifies if the customer’s account has an existing mandate. If no mandate is found, it returns a 400 Bad Request response. If a mandate is present, it makes a request to an external service to cancel the mandate and returns an empty JSON response.

Request Data:

  • The request does not require additional parameters but necessitates the user to be authenticated.

Response:

  • Success:
    • Returns an empty JSON response with no content if the mandate cancellation is successful.
  • Failure:
    • If there is no mandate to cancel, returns a 400 Bad Request response with a message indicating the absence of a mandate.
    • If an error occurs during the cancellation request, returns a 500 Internal Server Error response with an error message. The error details are logged for debugging.

Error Handling:

  • Exception: If an error occurs during the cancellation process, a 500 Internal Server Error is returned. The error message is logged for further investigation.

Update Direct Debit Customer Details

  • Route: PATCH ../trade-credit/payment/direct-debit/customer/{customerId}
  • Controller: DirectDebitController
  • Method: updateCustomer
  • Request: UpdateDirectDebitCustomerRequest
  • Description: Updates customer details related to Direct Debit.

The updateCustomer method in the DirectDebitController updates the Direct Debit customer details. It handles updating the customer's account number and Toolstation customer ID. If a mandate_id is provided in the request, it updates the corresponding record in the account service.

Request Data:

  • Path Parameters:
    • customerId (string): The ID of the customer to update.
  • Request Body:
    • account_number (string): The new account number to be set.
    • toolstation_customer_id (string): The new Toolstation customer ID to be set.
    • mandate_id (string, optional): The mandate ID to be updated in the account service, if applicable.

Response:

  • Success:
    • Returns an empty JSON response with no content if the update is successful.
  • Failure:
    • If an error occurs during the update process, a 500 Internal Server Error response is returned with an error message. The error details are logged for debugging.

Error Handling:

  • Exception: If there is an issue with the update request, a 500 Internal Server Error is returned. The error message is logged for further investigation.

SSO Authentication

  • Route: GET /sso/{customerId}
  • Controller: TradeCreditController
  • Method: ssoAuthentication
  • Request: Request
  • Description: Endpoint to generate Single Sign-On (SSO) authentication data for a customer.

The ssoAuthentication method in the TradeCreditController retrieves SSO authentication data for a specified customer. It checks the API version configuration to decide whether to use the Trade Credit Service or an identity provider for generating the authentication data.

Request Data:

  • Path Parameters:
    • customerId (string): The ID of the customer for whom SSO authentication data is to be generated.

Response:

  • Success:
    • Returns a SSOResponseResource with the authentication data including url, method, and params.
  • Failure:
    • If an error occurs during the generation of authentication data, a 400 Bad Request response is returned with an error message. The error details are logged.

Error Handling:

  • Exception: If there's a failure in generating authentication data from the identity provider, a 400 Bad Request response is returned. The error details are logged for debugging.

Transaction

Taxonomies

The following API routes are available under the taxonomies prefix. These routes are cached with public headers and a max age of 300 seconds .

Copyright © 2026