7.0.6 • Public • Published

    Client library for payment-api

    Client library for the Pay common component.


    • Node >=10.15.2
    • yarn


    As of now, this module is published only in a private repository. We are working on publishing this project to NPM. Until then, the package can be installed from its github URL, examples:

    # Install the latest version
    yarn add https://github.com/hmcts/div-pay-client
    # Install a specific version
    yarn add https://github.com/hmcts/div-pay-client#4.0.2


    First get a client

    const payClient = require('@hmcts/div-pay-client')
    const client = payClient.init({
      apiBaseUrl: 'https://payment-api:4501', // Base URL of payment-api
      serviceIdentification: 'DIV1', // Service ID for use in payment reference

    Create a payment

    client.create(user, serviceToken, caseReference, caseType, feeCode, amount, description, returnUrl)
      .then(responsePayload => {
        // JSON response payload should be available here.
      .catch(err => {
        // Or an error in case of an error.
        throw err

    Query a payment

    client.query(user, serviceToken, paymentId)
      .then(responsePayload => {
        // JSON response payload should be available here.
      .catch(err => {
        // Or an error in case of an error.
        throw err

    Cancel a payment

    client.cancel(user, serviceToken, paymentId)
      .then(responsePayload => {
        // The response body is empty with status code 204 on success.
        // A new query needs to run in order to confirm status.
      .catch(err => {
        // Or an error in case of an error.
        throw err

    Please refer to the JSDoc blocks in /src for the function signatures. See response examples in the /examples folder in this repo.

    Implementation notes

    User tokens

    To make calls to payment-api the user must already be logged in and authenticated. For requests, the user id and the token are required for every API call.

    Service tokens

    In order to make requests a service token is required. This can be obtained from the /lease endpoint of service-auth-provider-api using the already registered service name and a one time password generated using a service secret.

    See @divorce/service-auth-provider-client for an example implementation.

    Chargeable Fees

    The fee being charged needs to come from the fees-register service. To create payments, Fee Code, Fee Description and the Amount charged should be obtained from a fees-register service response.

    Payment Reference

    The payment reference is a string containing the service ID, a Case Reference, the Divorce Case Type, and a Fee Code concatenated with $$$. For transactions where the Case Reference is not known, a random identifier is generated. In these cases the Case Reference must be assigned to the payment for reconciliation purposes.

    Payment Status

    The payment status will determine whether the transaction was successful. No details are given if an error occurs as all payment errors are displayed to the user on the Gov Pay payment pages.




    npm i @hmcts/div-pay-client

    DownloadsWeekly Downloads






    Unpacked Size

    26.3 kB

    Total Files


    Last publish


    • bendiggle
    • ellie-harrison
    • adrianc
    • hemantt
    • adamsilver
    • trevorsaint
    • timja-hmcts
    • dharmendrak
    • robertparkinson
    • pragnesh
    • damdun
    • p.jar
    • sabah.irfan
    • jenkins-reform-hmcts
    • andrewwa-kainos
    • timja