Sign in

v1

latestOpenAPI 3.0.32026-07-132012.5 KB

Begin a payment journey.

After a successful call to the /pay endpoint, the API user receives JSON with a redirection URL. The API user then redirects the customer's browser to this URL, starting the payment journey.

post/pay

Request body

taxRegime'SelfAssessment' | 'Vat' required

The tax regime under which the liability has arisen. One of a fixed set. Currently supported regimes are: Self Assessment and Vat.

referencestring required

The reference identifying the tax liability. For Self Assessment this is the 10 digit Unique Taxpayer Reference. For VAT this is the 9-digit VAT registration number.

amountInPenceinteger required

The amount to be paid in pence, so £12.34 is 1234, must be greater than or equal to 0. If 0 is provided, the user will be prompted to enter an amount. If non zero is provided, the user will be prompted to select the amount or enter another amount.

backURLstring uri

If this is present HMRC will offer this as a link to the customer at the end of the journey, this link can allow them to return to their software.

friendlyNamestring

The name of the software that the user started their payment from. If this is present, then we will display a link to help users go back to their software which says "return to <friendlyName>"

Example request

{
  "taxRegime": "SelfAssessment",
  "reference": "1097172564",
  "amountInPence": 1234,
  "backURL": "https://some-accounting-software.com/after-pay/a218f71d9bf2438e851c71d50866c2e9",
  "friendlyName": "Accounting Software Company X"
}

Response

Created. Body contains url to redirect user to and a UUID to look up the status of the payment journey with.

redirectURLstring

The URL to direct the customer browser to in order to initiate the customer payment journey

clientJourneyIdstring uuid

The client identifier created by HMRC for this journey. This will be a UUID (version 4, variant 2). This field is used to identify the journey in calls to the /status endpoint.

All 2 operations