ALalphagov
Card payments

Search payments

Changed on

Search payments by reference, state, 'from' and 'to' date. The Authorisation token needs to be specified in the 'authorization' header as 'authorization: Bearer YOUR_API_KEY_HERE'

get/v1/payments

Request

  • Base URL
    https://publicapi.payments.service.gov.uk
  • URL
    https://publicapi.payments.service.gov.uk/v1/payments
  • Auth
    API key in header Authorization

Query parameters

referencestring

Your payment reference to search (exact match, case insensitive)

emailstring

The user email used in the payment to be searched

state'created' | 'started' | 'submitted' | 'success' | 'failed' | 'cancelled' | 'error'

State of payments to be searched. Example=success

card_brandstring

Card brand used for payment. Example=master-card

from_datestring

From date of payments to be searched (this date is inclusive). Example=2015-08-13T12:35:00Z

to_datestring

To date of payments to be searched (this date is exclusive). Example=2015-08-14T12:35:00Z

pagestring

Page number requested for the search, should be a positive integer (optional, defaults to 1)

display_sizestring

Number of results to be shown per page, should be a positive integer (optional, defaults to 500, max 500)

cardholder_namestring

Name on card used to make payment

first_digits_card_numberstring

First six digits of the card used to make payment

last_digits_card_numberstring

Last four digits of the card used to make payment

from_settled_datestring

From settled date of payment to be searched (this date is inclusive). Example=2015-08-13

to_settled_datestring

To settled date of payment to be searched (this date is inclusive). Example=2015-08-14

Response

OK

totalinteger
countinteger
pageinteger

Example response

{
  "total": 100,
  "count": 20,
  "page": 1,
  "_links": {
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "results": [
    {
      "amount": 1200,
      "description": "Your Service Description",
      "reference": "your-reference",
      "language": "en",
      "email": "your email",
      "state": {
        "status": "created",
        "message": "User cancelled the payment",
        "code": "P010"
      },
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "payment_provider": "worldpay",
      "created_date": "2016-01-21T17:15:000Z",
      "refund_summary": {
        "status": "available",
        "amount_available": 100
      },
      "settlement_summary": {
        "capture_submit_time": "2016-01-21T17:15:000Z",
        "captured_date": "2016-01-21",
        "settled_date": "2016-01-21"
      },
      "card_details": {
        "last_digits_card_number": "1234",
        "first_digits_card_number": "123456",
        "cardholder_name": "Mr. Card holder",
        "expiry_date": "04/24",
        "billing_address": {
          "line1": "address line 1",
          "line2": "address line 2",
          "postcode": "AB1 2CD",
          "city": "address city",
          "country": "GB"
        },
        "card_brand": "Visa",
        "card_type": "debit"
      },
      "corporate_card_surcharge": 250,
      "total_amount": 1450,
      "fee": 5,
      "net_amount": 1195,
      "provider_id": "reference-from-payment-gateway",
      "return_url": "http://your.service.domain/your-reference",
      "_links": {
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "cancel": {
          "type": "application/x-www-form-urlencoded",
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST"
        },
        "events": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "refunds": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "capture": {
          "type": "application/x-www-form-urlencoded",
          "href": "https://an.example.link/from/payment/platform",
          "method": "POST"
        }
      },
      "card_brand": "Visa"
    }
  ]
}

Changes

  • e9ebe27000afRevision changes
    • info

      added the new optional query request parameter from_settled_date

    • info

      added the new optional query request parameter to_settled_date

  • 6d52e43c48aaRevision changes
    • breaking

      removed the media type application/json for the response with the status

    • breaking

      removed the media type application/json for the response with the status

    • breaking

      removed the media type application/json for the response with the status

    • breaking

      removed the media type application/json for the response with the status

    • info

      the endpoint scheme security Authorization was added to the API

    • info

      the endpoint scheme security BearerAuth was removed from the API