Skip to main content

Add custom metadata

You can add custom metadata to a new payment. For example, you can add a reference number from your finance or accounting system, so you can reconcile the payment later.

You add metadata when you make an API call to create a new payment.

If you’re using payment links, you can add metadata by adding reporting columns in the GOV.UK Pay admin tool.

Your users cannot see metadata while they’re making a payment.

Add metadata to a payment

Include a metadata object in the body of your request to create a new payment, for example:

"metadata": {
   "ledger_code": "AB100",
   "an_internal_reference_number": 200,
...
}

The metadata object must contain between 1 and 10 parameters.

Each parameter key must be a unique case-insensitive string between 1 and 30 characters long. If 2 or more keys are identical, the API will remove all but one of the identical keys from the metadata object.

The data type of each parameter value must be either a:

  • string of no more than 100 characters
  • number
  • boolean

Parameter values can be empty.

The API response will include your metadata.

You cannot add or change metadata keys or values after you’ve created the payment request.

Getting a payment’s metadata

When you get information about a single payment or generate a list of payments, the API response will include the metadata object.

The order of the parameters in the metadata object may be different to your original object.

You can sign in to the GOV.UK Pay admin tool to see or download a payment’s metadata. You can also use a payment’s metadata to locate that payment in the GOV.UK Pay admin tool.