Skip to main content
Alerts And Decisioning

Decision a payment hold to release or cancel a payment

In this tutorial, you will learn how to decision a payment hold to release or cancel a payment. The API supports two methods: 

  • Decision a single payment hold 
  • Decision multiple payment holds in bulk 

Before You Begin

To decision a payment hold, you will need the following: 

  • A registered and fully onboarded Developer Account on the J.P. Morgan Payments Developer Portal. 
  • A way to retrieve payments for decision: 
  • Pull from your own storage after “Receiving a hold via webhook”
  • Pull holds Dynamically via J.P. Morgan hold API 
  • Code to generate a bearer token via Sentry

Decision single payment hold

To decision a single payment hold, send a POST request to the /holds/{id}/decision endpoint.

Sample request: 

Json
{
  "action": "REJECT",
  "rejectReason": "FRAUD",
  "fraudType": "OTHER",
  "fraudTypeOtherAdditionalData": "Suspicious wire transfer to unknown beneficiary"
}

Notes:

  • The “action” attribute may be “APPROVE” or “REJECT”.   
    • If “APPROVE”, no other attributes are specified 
    • If “REJECT”, additional attributes may be specified 
    • The “rejectReason” MUST be specified if “action” is “REJECT” 
    • The “fraudType” MAY be specified if “rejectReason” is “FRAUD” 
    • The “fraudTypeOtherAdditionalData” MAY be specified if “fraudType” is “OTHER” 

If the API call succeeds, you receive an HTTP 200 response code and a response body.

Sample response: 

Json
{
  "holdId": "550e8400-e29b-41d4-a716-446655440000",
  "result": "SUCCESS",
  "status": "REJECTED",
  "substatus": "REJECTED_FRAUD_CLIENT",
  "fraudType": "OTHER",
  "fraudTypeOtherAdditionalData": "Suspicious wire transfer to unknown beneficiary"
}

If an error occurs, the API returns a non-200 HTTP response code. For details about field names, values, and possible response type, see error codes.

If you store hold data in your own database, save the returned details for future reference.

Decision multiple payment holds in bulk

You can decision multiple payment holds at the same time by sending a list of decisions to the /holds/decision/bulk endpoint via POST.

Sample request:

Json
{
  "items": [
    {
      "holdId": "6c4e9a21-3f72-4b8c-8d3a-2f1e7c9b0d54",
      "action": "REJECT",
      "rejectReason": "DUPLICATE_TRANSACTION"
    },
    {
      "holdId": "a1d7f3c9-2b45-4e1a-b6c2-3d9e8f0a7c31",
      "action": "APPROVE"
    }
  ]
}

Sample response:

Json
{
  "items": [
    {
      "holdId": "6c4e9a21-3f72-4b8c-8d3a-2f1e7c9b0d54",
      "result": "SUCCESS",
      "status": "REJECTED",
      "substatus": "REJECTED_DUPLICATE_TXN_CLIENT"
    },
    {
      "holdId": "a1d7f3c9-2b45-4e1a-b6c2-3d9e8f0a7c31",
      "result": "FAILURE",
      "failureReason": {
        "code": "11001",
        "message": "Hold already decisioned"
      },
      "status": "PENDING",
      "substatus": "PENDING_ACTION_CLIENT"
    }
  ]
}

Notes:

  • The API allows partial success. Some holds may be processed successfully, while others may fail.
  • For each item, check the result attribute to determine success or failure.
  • If decisioning fails for an item, a failure reason object is included.
  • A new status and substatus are calculated for each successfully processed hold. Store these values if you maintain hold data in your system.
  • Hold processing can fail for various reasons. For more information about field names, values, and possible response types, see error codes.