Payment Item Search
Search through Payouts submitted either as single payouts or as part of a batch, refining by UBR (unique bankout reference) or using a query string with filters.
Payment Item Search request
Accept: application/vnd.worldpay.account-payouts-v2+json
Payment Item Search uses GET requests with parameters defined in the path (URL) supplied.
Below sample Payment Item Search query strings are shown, refining using filters, by UBR or by Payment Id.
GET https://try.access.worldpay.com/payouts/events?entity=000000&startDate=2022-01-01&endDate=2022-02-01&payeeName=John+Doe&merchantReference=aaa&paymentReference=aaa&accountNumber=0000&sourceCurrency=EUR&sourceAmount=5.15&targetCurrency=USD&targetAmount=5.55&countryCode=UK&pageNumber=1&pageSize=1
GET https://try.access.worldpay.com/payouts/events/PO20000N88
GET https://try.access.worldpay.com/payouts/events/id/27ae566e-6530-ee11-b58a-005056b48b8e
Parameters
Permitted special characters for appropriate fields, as well as preset values for specific fields are listed in the Appendix.
| Request type | Field Name | Description | Data Type/Format | Required? | Min-Max Length | Validation Criteria |
|---|---|---|---|---|---|---|
| Search by filters | entity | Merchant Domain making payout. This value is provided by the RM/Onboarding as part of the onboarding process. | AN | ✅ | 6-6 | Must be a valid domain |
| startDate | Posting start date for the payout; this the start of a 'window' of time which must satisfy the constraints described. Should be before current date. Should be before end date. Distance between start and end dates should not exceed 30 days. Should be after minimum date (0001-01-01). | Date | ✅ | 10-10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD. | |
| endDate | Posting end date for the payout; this the end of a 'window' of time which must satisfy the constraints described. Should be before present date. Should be after start date. Should be after minimum date (0001-01-01) | Date | ✅ | 10-10 | Must be a Gregorian calendar date with ISO 8601 format YYYY-MM-DD. | |
| payeeName | Complete payee name for the payout. This will be one of the following (depending on the beneficiary type): fullName - concatenated value from title + firstName + middleName + lastName; companyName | AN | ❌ | 0-50 | ||
| narrative | Reference provided by remitter of the payment (unique for a remitter). In Single Payout API - merchantNarrative | AN | ❌ | 0-50 | ||
| transactionReference | Reference provided by remitter of the payment (unique for Account Payouts Payout API). | AN | ❌ | 0-50 | ||
| beneficiaryAccountNumber | Beneficiary bank account number. (IBAN is currently not supported). | AN | ❌ | 0-50 | ||
| sourceCurrency | Source currency for the payout. | A | ❌ | 3-3 | ISO 4217. List of valid Valid currency codes. | |
| sourceAmount | Source currency amount | N | ❌ | 1-19 | Decimal, 18 digit precision including 2 decimal places | |
| targetCurrency | Target currency for the payout. | A | ❌ | 3-3 | ISO 4217. List of valid currency codes. | |
| targetAmount | Target currency amount | N | ❌ | 1-19 | Decimal, 18 digit precision including 2 decimal places | |
| countryCode | Payment destination country code. | A | ❌ | 2-2 | ISO 3166-1 Alpha-2 code. List of valid country codes. | |
| pageNumber | Positive whole number indicating which page of the statement to return. | N | ✅ | Greater than 0 | ||
| pageSize | Positive whole number indicating which page of the statement to return. | N | ✅ | 1-499 | Greater than 0, less than 500 | |
| Search by UBR | ubr | Unique reference associated with a payout submitted through Payout API. | AN | ✅ | 8-10 | PN/PZ/PO prefix plus 6 characters, e.g. PZ000N65. Five numbers, a letter and finally two/four further numbers. AlphaNumericRegex = ^[0-9a-zA-Z]+$ |
Response structure
| Section | Field Name | Description | Data Type/Format |
|---|---|---|---|
| items | ubr | Unique bankout reference associated with a payout submitted through our Account Payouts API. | string (50 characters maximum) |
| items | narrative | Reference provided by remitter of the payment (unique for a remitter). | string (50 characters maximum) |
| items | transactionReference | Reference provided by remitter of the payment (unique for Account Payouts Payout API). | string (50 characters maximum) |
| items | beneficiaryAccountNumber | Beneficiary bank account number | string (50 characters maximum) |
| items | swiftBic | Beneficiary bank account SWIFT/BIC. | string (50 characters maximum) |
| items | paymentId | Unique identifier associated with the payment. | Guid |
| items | entity | Domain ID of the merchant making the payout. | Alphanumeric string, length 6. |
| items | paymentDatetime | Date and time of the payment submission. | DateTime ISO 8601 |
| items | payeeName | Complete payee name for the payout. This will be one of the below (depending on the beneficiary type): fullName - concatenated value from title + firstName + middleName + lastName companyName | string (50 characters maximum) |
| items | sourceCurrency | Currency for the remitter account. | String (3 characters maximum) |
| items | sourceAmount | Amount being sent by the remitter. This may take precedence in the transaction or the targetAmount. If the transaction is cross-currency these will differ due to conversion. | Decimal, 18 digit precision including 2 decimal places |
| items | targetCurrency | Currency for the payee's account. | String (3 characters maximum) |
| items | targetAmount | Amount being received by the payee. This may take precedence in the transaction or the sourceAmount. If the transaction is cross-currency these will differ due to conversion. | Decimal, 18 digit precision including 2 decimal places |
| items | countryCode | Country that the payout is being made in. | String (2 characters maximum) |
| items | paymentState | State of the payment. | For the full list of values please see here |
| items | bankName | Name of the payee (beneficiary) bank which the payout is being made to. | string (50 characters maximum) |
| items | bankCode | Beneficiary bank account bank code. | string (50 characters maximum) |
| items | iban | Beneficiary IBAN. | string (50 characters maximum) |
| pagination | pageNumber | Page that the transaction is listed on. | Integer |
| pagination | pageSize | Number of items listed per page. | Integer |
| pagination | pageCount | Total number of pages. | Integer |
| pagination | totalNumberOfRecords | Total number of items listed across all pages. | Integer |
Example Payment Item Search response body:
{ "items": [ { "ubr": "PO000N65", "narrative": "XYZ102025", "transactionReference": "XYZ102025", "beneficiaryAccountNumber": "45533882", "swiftBic": "BUKBGB22", "entity": "000055", "countryCode": "AR", "paymentId": "51a448e5-4430-ee11-b58a-005056b48b8e", "paymentDatetime": "2023-08-01T08:24:44.443", "payeeName": "John Smith", "sourceCurrency": "ARS", "sourceAmount": 0.00, "targetCurrency": "ARS", "targetAmount": 1.05, "paymentState": "EXECUTED", "bankName": "Test Bank", "bankCode": "10 02 04", "iban": "GB29NWBK60161331926819" }, { "ubr": "PN00004N", "narrative": "Ref: 123456", "transactionReference": "123456", "beneficiaryAccountNumber": "12345677", "swiftBic": "BUKBGB22", "entity": "000055", "countryCode": "GB", "paymentId": "c1b659f6-4c30-ee11-b58a-005056b48b8e", "paymentDatetime": "2023-08-01T09:22:41.377", "payeeName": "John Johno Johnson", "sourceCurrency": "GBP", "sourceAmount": 0.00, "targetCurrency": "GBP", "targetAmount": 10.00, "paymentState": "EXECUTED", "bankName": "Test Bank", "bankCode": "404433", "iban": "GB29NWBK60161331926819" } ], "pagination": { "pageNumber": 1, "pageSize": 2, "pageCount": 5610, "totalNumberOfRecords": 11220 } }
Error response example
{ "errors": { "callerId": [ "CallerId is mandatory" ] }, "httpStatusCode": 400, "customCode": "SPAB01", "message": "There was an error in the request" }
Error response codes
General
| HTTP code | Custom Code | Message | Scenario |
|---|---|---|---|
| 404 | SPAN19 | Payment not found | Request successful, but the payment searched not found. |
| 400 | SPAB01 | There was an error in the request | Caller ID exceeds 100 characters limit |
| 400 | SPAV01 | An API version is required, but was not specified. | Version not specified or incorrect / Provided versions are conflicting |
| 401 | SPAU02 | Unauthorized | The token has expired |
| 401 | SPAU03 | Unauthorized | The edge token is not trusted |
| 401 | SPAU14 | Unauthorized | Unauthorized request |
| 401 | SPAE11X | Unauthorized request | Unauthorized request |
| 404 | SPAN16 | Unable to find external consumer data | Consumer with subject-domain combination not found |
| 500 | SPAU04 | Unexpected issue | Unexpected issue. Please try again |
| 401 | SPAU07A | Unauthorized request | Token is empty |
| 401 | SPAU06A | Unauthorized request | Token validation failed |
| 401 | SPAU06A | Unauthorized request | Token has expired |
| 401 | SPAU10 SPAU07B | Authentication failed | Token validation failed |
| 500 | SPAE11C | Unexpected Issue. Please try again | Internal Server Error |
| 415 | N/A | Unsupported Media Type | Invalid Content Type Value |
| 403 | SPAF18 | Authorisation failed for this domain | Consumer isn't allowed to instruct requests using the entitlements that were provided in the token. |
Note
In the event of 401-500 range HTTP code error response please contact Worldpay Support Team.
Schema Validation Responses
Note
All Schema validation responses will have the same format of httpStatusCode, customCode and message, however the responses will differ with the error message as in the table below.
| HTTP code | Custom Code | Example Message | Scenario |
|---|---|---|---|
| 400 | SPAB05 | Merchant Treasury Id' must be 6 characters long and not contain I or O | Merchant Treasury ID longer/shorter than expected |
| 400 | SPAB05 | 'Merchant Treasury Id' must not be empty. | Merchant Treasury ID empty |
| 400 | SPAB05 | 'Start Date' is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD. | Start Date or End Date empty Start Date or End Date is not a valid Gregorian calendar date Start Date or Start Date is before minimum date |
| 400 | SPAB05 | 'Start Date' is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD. | Difference between Start and End dates is too great (more than 30 days) |
| 400 | SPAB05 | 'Start Date' is invalid. Please use Gregorian calendar dates with ISO 8601 format YYYY-MM-DD. | Start Date must not equal End Date |
| 400 | SPAB05 | "'Page' must be greater than '0'. | Page field is empty, has a value of 0 or a negative value |
| 400 | SPAB05 | 'Page Size' must be greater than 0 and less than 500 | Page Size is empty, is less than or equal to 0 or greater than 500 |