Retrieve payment holds via API
In this tutorial, you learn how to retrieve payment holds via API. You can call two endpoints to retrieve holds:
- Retrieve multiple payment holds
- Retrieve a single payment hold by ID
Before you begin
To retrieve payment holds via API, you need the following:
- A registered and fully onboarded developer account on the J.P. Morgan Payments Developer Portal
- Code to generate a bearer token. See the quick start guide for instructions.
Retrieve multiple payment holds
Use GET /holds endpoint to retrieve a list of payment holds based on filter criteria. Filter your results using query parameters. These are the most common examples:
| Use case | Query parameter | Example |
|---|---|---|
| Get all holds pending your review | substatus | /holds?substatus=PENDING_ACTION_CLIENT |
| Get all holds pending JPMorganChase review | substatus | /holds?substatus=PENDING_ACTION_JPM |
| Get all holds already decisioned | status | /holds?status=APPROVED,REJECTED |
Sample response:
{
"items": [
{
"id": "1f8c3a2e-7b54-4d9a-8c3f-12ab34cd56ef",
"status": "PENDING",
"substatus": "PENDING_ACTION_JPM",
"exceptionType": "BANK_RULE",
"heldAt": "2026-02-01T14:15:22Z",
"cutOffAt": "2026-02-06T14:15:22Z",
"rules": [
{
"id": "59be9844-3a70-4fbc-8d58-9637c1b34b18",
"name": "Client ABC Rule for Suspicious Beneficiary",
"effectiveDate": "2019-08-24"
}
],
"payment": {
"requestedExecutionDate": "2026-02-01",
"paymentIdentifiers": {
"endToEndId": "E2E3000113WEBXX"
},
"value": {
"currency": "USD",
"amount": "10.50"
},
"transferType": "DEBIT",
"paymentType": "WIRE",
"debtor": {
"party": {
"name": "Nicholas Tesla"
},
"account": {
"accountNumber": "987654321",
"accountCurrency": "USD"
}
},
"remittanceInformation": {
"unstructuredInformation": [
{
"text": "Music services INV#09900"
}
]
}
}
},
{
"id": "06bca14f-1fc0-4cd7-9e0b-8bb7e06334f7",
"status": "PENDING",
"substatus": "PENDING_ACTION_CLIENT",
"exceptionType": "BANK_RULE",
"heldAt": "2026-03-01T14:15:22Z",
"cutOffAt": "2026-03-15T14:15:22Z",
"rules": [
{
"id": "59be9844-3a70-4fbc-8d58-9637c1b34b18",
"name": "Client ABC Rule for Suspicious Beneficiary",
"effectiveDate": "2019-08-24"
}
],
"payment": {
"requestedExecutionDate": "2026-03-10",
"paymentIdentifiers": {
"endToEndId": "E2E5908713WEBXX"
},
"value": {
"currency": "USD",
"amount": "250000"
},
"transferType": "DEBIT",
"paymentType": "WIRE",
"debtor": {
"party": {
"name": "Thomas Edison"
},
"account": {
"accountNumber": "123456789",
"accountCurrency": "USD"
}
},
"remittanceInformation": {
"unstructuredInformation": [
{
"text": "Cleaning INV#12300"
}
]
}
}
}
],
"metadata": {
"pagination": {
"page": 1,
"size": 25,
"totalCount": 2,
"totalPages": 1
},
"asOf": "2026-04-01T00:00+00:00"
}
}The response includes an array of payment hold objects and pagination metadata.
Hold information
Each item in the items array contains hold details such as status, substatus, heldAt and cutOffAt. If the hold has already been decisioned, the decision field contains information about how it was decisioned.
Pagination
The metadata.pagination object contains information about the current page of results:
| Field | Description |
|---|---|
| page | Current page number |
| size | Number of items per page |
| totalCount | Total number of holds matching your query |
| totalPages | Total number of pages available |
Error handling
This request can fail for several reasons, such as invalid query parameters or authentication errors. See API reference for details about field requirements and possible error responses.
Retrieve a single payment hold by ID
Use GET /holds/{id} endpoint to retrieve the full details of a specific payment hold when you know its unique identifier.
Sample response:
{
"id": "06bca14f-1fc0-4cd7-9e0b-8bb7e06334f7",
"status": "PENDING",
"substatus": "PENDING_ACTION_CLIENT",
"exceptionType": "BANK_RULE",
"heldAt": "2026-02-01T14:15:22Z",
"cutOffAt": "2026-02-06T14:15:22Z",
"rules": [
{
"id": "59be9844-3a70-4fbc-8d58-9637c1b34b18",
"name": "Client ABC Rule for Suspicious Beneficiary",
"effectiveDate": "2019-08-24"
}
],
"payment": {
"requestedExecutionDate": "2026-02-01",
"paymentIdentifiers": {
"endToEndId": "E2E3000113WEBXX"
},
"value": {
"currency": "USD",
"amount": "10.50"
},
"transferType": "DEBIT",
"paymentType": "WIRE",
"paymentTypeInformation": {
"serviceLevelCode": "NURG",
"localInstrumentCode": {
"code": "WEB"
}
},
"debtor": {
"party": {
"name": "Nicholas Tesla"
},
"account": {
"accountNumber": "987654321",
"accountCurrency": "USD"
},
"postalAddress": {
"type": "HOME",
"addressLines": [
"10007 S. Lake Drive"
],
"streetName": "10007 Lake Dr",
"postalCode": "48035",
"city": "Clinton Township",
"countrySubDivision": "MI",
"country": "US"
}
},
"paymentPurpose": {
"categoryPurpose": {
"proprietary": "PURCHASE"
}
},
"remittanceInformation": {
"unstructuredInformation": [
{
"text": "Music services INV#09900"
}
]
}
}
}The response contains the complete payment hold object, including hold metadata and full payment details.
Hold information
The response includes hold details such as status, substatus, heldAt and cutOffAt. If the hold has already been decisioned, the decision field contains information about how it was decisioned.
Payment details
The payment object contains the full payment instruction, including debtor information, payment value and remittance information.
Error handling
This request can fail for several reasons, such as an invalid hold ID or authentication errors. See API reference for details about field requirements and possible error responses.