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
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/paymentRequests |
| Production – US Hub | GET 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 scope | Identity client role |
|---|---|
payment-requests | payment-requests.viewer |
payment-requests | payment-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.
| Parameter | When to use it |
|---|---|
ContinuationToken | Retrieve the next page. Use the token returned in the previous response. |
PageSize | Set 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.
Updated 17 days ago