Search payments

GET/v1/payments

You can use this endpoint to search for payments you’ve previously created. Payments are sorted by date, with the most recently-created payment appearing first.

Requires a bearer token.

In this mock: Filters run over payments stored for the last 7 days. reference must match exactly; email and cardholder_name are partial, case-insensitive matches. Results are newest first.

Query parameters

Name	Type	Description
`reference`	string	Returns payments with `reference` values exactly matching your specified value.
`email`	string	Returns payments with matching `email` values. You can send full or partial email addresses. `email` is the paying user’s email address.
`state`	string	Returns payments in a matching `state`. `state` reflects where a payment is in the payment status lifecycle. One of: created, started, submitted, success, failed, cancelled, error
`card_brand`	string	Returns payments paid with a particular card brand.
`from_date`	string	Returns payments created on or after the `from_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
`to_date`	string	Returns payments created before the `to_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
`page`	string	Returns a specific page of results. Defaults to `1`.
`display_size`	string	The number of payments returned per results page. Defaults to `500`. Maximum value is `500`.
`cardholder_name`	string	Returns payments paid with cards under this cardholder name.
`first_digits_card_number`	string	Returns payments paid by cards beginning with the `first_digits_card_number` value. `first_digits_card_number` value must be 6 digits.
`last_digits_card_number`	string	Returns payments paid by cards ending with the `last_digits_card_number` value. `last_digits_card_number` value must be 4 digits.
`from_settled_date`	string	Returns payments settled on or after the `from_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.
`to_settled_date`	string	Returns payments settled before the `to_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.
`agreement_id`	string	Returns payments that were authorised using the agreement with this `agreement_id`. Must be an exact match.

Example request

curl -X GET "https://publicapi.payments.platform-engineering.com/v1/payments" \
  -H "Authorization: Bearer $TOKEN"

Responses

200: OK - your request was successful.

Name	Type	Description
`_links`	object	Links to navigate through pages of your search.
`_links.first_page`	object	A link related to a payment
`_links.first_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.first_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.last_page`	object	A link related to a payment
`_links.last_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.last_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.next_page`	object	A link related to a payment
`_links.next_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.next_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.prev_page`	object	A link related to a payment
`_links.prev_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.prev_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.self`	object	A link related to a payment
`_links.self.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.self.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`count`	integer	Number of payments on the current page of search results.
`page`	integer	The page of results you’re viewing. To view other pages, make this request again using the `page` parameter.
`results[]`	array of objects	Contains payments matching your search criteria.
`results[]._links`	object	links for search payment resource
`results[]._links.cancel`	object	A POST link related to a payment
`results[]._links.cancel.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`results[]._links.cancel.method`	string
`results[]._links.cancel.params`	map
`results[]._links.cancel.type`	string
`results[]._links.capture`	object	A POST link related to a payment
`results[]._links.capture.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`results[]._links.capture.method`	string
`results[]._links.capture.params`	map
`results[]._links.capture.type`	string
`results[]._links.events`	object	A link related to a payment
`results[]._links.events.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`results[]._links.events.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`results[]._links.refunds`	object	A link related to a payment
`results[]._links.refunds.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`results[]._links.refunds.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`results[]._links.self`	object	A link related to a payment
`results[]._links.self.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`results[]._links.self.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`results[].agreement_payment_type`	string	When the customer initiates a standing order agreement transaction we have to include a customerInitiatedReason attribute. This can have a value of `instalment`, `recurring`, or `unscheduled`. One of: instalment, recurring, unscheduled
`results[].amount`	integer	The description assigned to the payment when it was created.
`results[].authorisation_mode`	string	How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment. One of: web, moto_api, external
`results[].authorisation_summary`	object	Object containing information about the authentication of the payment.
`results[].authorisation_summary.three_d_secure`	object	Object containing information about the 3D Secure authentication of the payment.
`results[].authorisation_summary.three_d_secure.required`	boolean	Indicates if this payment was authorised with 3D Secure authentication. `required` is `true` if the payment required 3D Secure authentication.
`results[].card_brand`	string	This attribute is deprecated. Please use `card_details.card_brand` instead.
`results[].card_details`	object	A structure representing the payment card
`results[].card_details.billing_address`	object	A structure representing the billing address of a card
`results[].card_details.billing_address.city`	string	The paying user's city.
`results[].card_details.billing_address.country`	string	The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
`results[].card_details.billing_address.line1`	string	The first line of the paying user’s address.
`results[].card_details.billing_address.line2`	string	The second line of the paying user’s address.
`results[].card_details.billing_address.postcode`	string	The paying user's postcode.
`results[].card_details.card_brand`	string	The brand of card the user paid with.
`results[].card_details.card_type`	string	The type of card the user paid with.`null` means your user paid with Google Pay or we did not recognise which type of card they paid with. One of: debit, credit, null
`results[].card_details.cardholder_name`	string
`results[].card_details.expiry_date`	string	The expiry date of the card the user paid with in `MM/YY` format.
`results[].card_details.first_digits_card_number`	string
`results[].card_details.last_digits_card_number`	string
`results[].card_details.wallet_type`	string	The digital wallet type that the user paid with One of: Apple Pay, Google Pay
`results[].corporate_card_surcharge`	integer	The corporate card surcharge amount in pence.
`results[].created_date`	string
`results[].delayed_capture`	boolean	`delayed_capture` is `true` if you’re controlling how long it takes GOV.UK Pay to take (‘capture’) a payment.
`results[].description`	string	The description assigned to the payment when it was created.
`results[].email`	string
`results[].exemption`	object	A structure representing that 3DS exemption was requested and the outcome of the exemption, if applicable.
`results[].exemption.outcome`	object	A structure representing the outcome of a 3DS exemption, if known.
`results[].exemption.outcome.result`	string	The outcome of the requested exemption
`results[].exemption.requested`	boolean	Indicates whether an exemption was requested for the given payment.
`results[].exemption.type`	string	Indicates the type of exemption. Only present for corporate exemption
`results[].fee`	integer	The payment service provider’s (PSP) transaction fee, in pence. `fee` only appears when we have taken (‘captured’) the payment from the user or if their payment fails after they submitted their card details. `fee` will not appear if your PSP is Worldpay or you are using an API key from a test service.
`results[].language`	string	The ISO-6391 Alpha-2 code of the language of the user's payment page. One of: en, cy
`results[].metadata`	object
`results[].metadata.metadata`	map
`results[].moto`	boolean	Indicates if this payment is a Mail Order / Telephone Order (MOTO) payment.
`results[].net_amount`	integer	The amount, in pence, that will be paid into your bank account after your payment service provider takes the `fee`.
`results[].payment_id`	string	The unique ID GOV.UK Pay automatically associated with this payment when you created it.
`results[].payment_provider`	string	The payment service provider that processed this payment.
`results[].provider_id`	string	The unique ID your payment service provider generated for this payment. This is not the same as the `payment_id`.
`results[].reference`	string	The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.
`results[].refund_summary`	object	A structure representing the refunds availability
`results[].refund_summary.amount_available`	integer	How much you can refund to the user, in pence.
`results[].refund_summary.amount_submitted`	integer	How much you’ve already refunded to the user, in pence.
`results[].refund_summary.status`	string	Whether you can refund the payment.
`results[].return_url`	string	The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.
`results[].settlement_summary`	object	A structure representing information about a settlement
`results[].settlement_summary.capture_submit_time`	string	The date and time GOV.UK Pay asked your payment service provider to take the payment from your user’s account. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`
`results[].settlement_summary.captured_date`	string	The date your payment service provider took the payment from your user. This value uses ISO 8601 format - `YYYY-MM-DD`
`results[].settlement_summary.settled_date`	string	The date that the transaction was paid into the service's account.
`results[].state`	object	A structure representing the current state of the payment in its lifecycle.
`results[].state.can_retry`	boolean	If `can_retry` is `true`, you can use this agreement to try to take another recurring payment. If `can_retry` is `false`, you cannot take another recurring payment with this agreement. `can_retry` only appears on failed payments that were attempted using an agreement for recurring payments.
`results[].state.code`	string	An API error codethat explains why the payment failed. `code` only appears if the payment failed.
`results[].state.finished`	boolean	Indicates whether a payment journey is finished.
`results[].state.message`	string	A description of what went wrong with this payment. `message` only appears if the payment failed.
`results[].state.status`	string	Where the payment is in the payment status lifecycle.
`results[].total_amount`	integer	Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you added a corporate card surcharge to the payment.
`total`	integer	Total number of payments matching your search criteria.

{
  "_links": {
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "count": 20,
  "page": 1,
  "results": [
    {
      "_links": {
        "cancel": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST",
          "params": {
            "description": "This is a value for a parameter called description"
          },
          "type": "application/x-www-form-urlencoded"
        },
        "capture": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST",
          "params": {
            "description": "This is a value for a parameter called description"
          },
          "type": "application/x-www-form-urlencoded"
        },
        "events": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "refunds": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "agreement_payment_type": "instalment",
      "amount": 1200,
      "authorisation_mode": "web",
      "authorisation_summary": {
        "three_d_secure": {}
      },
      "card_brand": "Visa",
      "card_details": {
        "billing_address": {
          "city": "address city",
          "country": "GB",
          "line1": "address line 1",
          "line2": "address line 2",
          "postcode": "AB1 2CD"
        },
        "card_brand": "Visa",
        "card_type": "debit",
        "cardholder_name": "Mr. Card holder",
        "expiry_date": "04/24",
        "first_digits_card_number": "123456",
        "last_digits_card_number": "1234",
        "wallet_type": "Apple Pay"
      },
      "corporate_card_surcharge": 250,
      "created_date": "2016-01-21T17:15:00.000Z",
      "delayed_capture": false,
      "description": "Your Service Description",
      "email": "The paying user’s email address.",
      "exemption": {
        "outcome": {
          "result": "honoured"
        },
        "requested": true,
        "type": "corporate"
      },
      "fee": 5,
      "language": "en",
      "metadata": {
        "ledger_code": "AB100"
      },
      "moto": false,
      "net_amount": 1195,
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "worldpay",
      "provider_id": "reference-from-payment-gateway",
      "reference": "your-reference",
      "refund_summary": {
        "amount_available": 100,
        "status": "available"
      },
      "return_url": "http://your.service.domain/your-reference",
      "settlement_summary": {
        "capture_submit_time": "2016-01-21T17:15:00.000Z",
        "captured_date": "2016-01-21",
        "settled_date": "2016-01-21"
      },
      "state": {
        "code": "P010",
        "message": "User cancelled the payment",
        "status": "created"
      },
      "total_amount": 1450
    }
  ],
  "total": 100
}

401: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)

422: Invalid parameters: from_date, to_date, status, display_size. See Public API documentation for the correct data formats

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

429: Too many requests

Name	Type	Description
`code`	string	A GOV.UK Pay API error code. You can find out more about this code in our documentation.
`description`	string	Additional details about the error

{
  "code": "P0900",
  "description": "Too many requests"
}

500: Downstream system error

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}