List payment requests

List payment requests to retrieve payment requests available to your identity client in pages. To find requests by free text or structured criteria, use Search payment requests.

Endpoints

EnvironmentMethod and URL
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/paymentRequests
Production – US HubGET https://api.us.vitesse.io/v1/payment-initiation/paymentRequests

For help choosing an environment, see Environment.

Access requirements

Configure at least one of the following access combinations:

OAuth scopeIdentity client role
payment-requestspayment-requests.viewer
payment-requestspayment-requests.manager

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Query parameters

Use these parameters to choose the page size and retrieve subsequent pages.

ParameterWhen to use it
ContinuationTokenRetrieve the next page. Use the token returned in the previous response.
PageSizeSet the maximum number of requests per page. The default is 10; the accepted range is 1 to 100.

Send the request

This example uses the Staging environment and requests up to 10 payment requests:

curl --get \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --data-urlencode 'PageSize=10'

Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.

To request the next page, add the ContinuationToken returned in the previous response. --data-urlencode encodes the query parameter for you:

--data-urlencode 'ContinuationToken=<continuation-token>'

Pass the token back unchanged; do not construct or decode it.

Example response

A successful request returns 200 OK and a Data array containing programme details. This example returns one payment request:

{
  "Data": [
    {
      "Recipient": {
        "CardDetails": null,
        "Capture": {
          "CompletedAt": null,
          "UnsuccessfulInputReason": null,
          "UnsuccessfulInputTriggeredAt": null,
          "TrustMethods": [
            {
              "TrustMethodId": "TrustMethodId",
              "Value": "TrustMethodValue"
            }
          ],
          "VerificationMethods": null,
          "ProgrammeId": "770e8400-e29b-41d4-a716-446655440002",
          "AllowedPaymentMethods": [
            "Card",
            "BankAccount"
          ]
        },
        "VendorOnboarding": null,
        "CapturedPhoneNumber": null,
        "CapturedEmail": null,
        "Type": "Person",
        "Business": {
          "RegistrationNumber": "1234567890"
        },
        "Person": {
          "ResidenceNumber": "1234567890",
          "IdCardOrPassportNumber": "1234567890",
          "Birthdate": "1990-03-04",
          "Nationality": "US"
        },
        "TaxId": null,
        "Name": "Recipient name",
        "PhoneNumber": "1234567890",
        "Email": "[email protected]",
        "Country": "GB",
        "Address": null,
        "BankAccount": null
      },
      "PaymentRequestId": "550e8400-e29b-41d4-a716-446655440000",
      "SendAccountId": 1234,
      "PaymentMethod": "Card",
      "SendValue": 1,
      "SendCurrency": "GBP",
      "ReceiveValue": 1,
      "ReceiveCurrency": "GBP",
      "UseFxRateGroup": false,
      "StoredRecipient": {
        "StoredRecipientId": "660e8400-e29b-41d4-a716-446655440001",
        "ExternalStoredRecipientId": null
      },
      "VendorRecipient": null,
      "PaymentDescription": "Payment description",
      "PaymentPurpose": "Payment purpose",
      "PaymentCode": "Payment Code",
      "RecipientReference": "RecipientReference1",
      "CorrelationId": null,
      "ExternalReference1": "ExternalReference1",
      "ExternalReference2": "ExternalReference2",
      "ExternalReference3": "ExternalReference3",
      "Originator": {
        "Name": "Name",
        "Address": {
          "Country": "GB",
          "City": "London",
          "PostalCode": null,
          "CountrySubDivision": null,
          "AddressLine1": null,
          "AddressLine2": null
        },
        "Identifier": "Identifier"
      },
      "Scheduler": {
        "PaymentSchedulerId": "880e8400-e29b-41d4-a716-446655440003",
        "Default": true
      },
      "PaymentMethodsConfiguration": null,
      "Extra": null,
      "TransactionId": "TransactionId",
      "Status": "Created",
      "RoutingDetails": null,
      "CreatedAt": "2025-01-15T10:30:00Z",
      "CancelledAt": null,
      "CancellationDetails": null,
      "PrioritisationDetails": null,
      "TransactionDetails": null,
      "CreatedBy": null,
      "UpdatedBy": null,
      "OriginalValueIndicator": null,
      "CoPDetails": null
    }
  ],
  "HasMore": false,
  "ContinuationToken": null,
  "TotalCount": null
}

The example has no further pages, so HasMore is false and ContinuationToken is null. The API schema allows TotalCount to be null.

Troubleshoot requests

If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.

For 400 Bad Request, check that PageSize is between 1 and 100 and that you passed the continuation token returned by the previous response. For 401 Unauthorized or 403 Forbidden, check the access token, scope and identity client role.

For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.

Next steps

To find payment requests using free text or structured criteria, see Search payment requests. To retrieve a specific request, see Retrieve a payment request.