Skip to main content
Skip table of contents

Transaction Holds API Filter Options

Transaction holds are essential mechanisms in financial transactions that help manage risks and ensure smooth processing. By utilizing the filtering options provided below, you can effectively sort and identify transaction holds based on specific criteria. This enables you to streamline your operations, focus on critical holds, and take necessary actions promptly. Whether you need to review open holds, track released holds, or identify transactions declined due to risk rules, these filtering steps offer valuable insights for efficient management of transaction holds.

The /holds endpoint can be utilized as a filter query to sort and return Transaction and Entity Holds for all entity levels.

Endpoint Headers

CODE
/holds HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com

Available HTTP Methods

Create

POST /holds

Retrieve All

GET /holds/

Retrieve by ID

GET /holds/{id}

Update

PUT /holds/{id}

Delete

DELETE /holds/{id}

ID Format

t1_hld_123abc4d567890efg1h2i34

The traditional GET /entities or /txns (transactions) request can also be sent as normal, while applying additional filter query criteria from the /holds resource that will only return results related to open holds.

For the example below, we'll filter transaction holds only. To filter to entity holds, simply replace the txn value with entity in the table below.

Transaction Holds Filter Format

The section details HTTP queries for filtering transaction holds, aiding in targeted retrieval and management. Queries enable sorting based on criteria, optimizing user experience and hold management. The provided HTTP string focuses on active holds requiring attention, offering insights for prompt actions. Sorting results by hold creation date enhances efficiency in managing transaction holds.

CODE
GET https://api-test.payrix.com/txns?{Filter_Query}

Filter Options

The table below provides a comprehensive list of HTTP filter queries that can be utilized to interact with the /holds endpoint resource records through the /txns endpoint. This reference guide aims to streamline the process of filtering transaction holds, empowering risk analysts to efficiently manage and take necessary actions based on the hold data.

Filter Query

Description

?txn[id][greater]=0

Ensures only transactions/transaction holds are returned.

?txn[holds][reviewed]

Filters out transaction holds by Risk analyst review status.

Valid Values:

  • =0 - The Hold has not been reviewed by a Risk analyst.

  • =1 - The Hold has been reviewed by a Risk analyst.

?txn[holds][released]

Filters out our targets' holds that have been released

  • =0 - The Hold has not been released by a Risk analyst.

  • =1 - The Hold has been released by a Risk analyst.

?txn[holds][action][greater]=0

Filter out any transactions that have 0 for “No Action”.

These types of holds do not impact the transaction and typically are used for analysis purposes only ie listen-only mode

?txn[reserved][greater]=0

Ensures only transactions with a reserved status other than 0 for “No Reserve”.

?txn[status][in]=0,1,3,4,5

Filters out transactions that are in status 2 for “Failed” since the hold cannot be open as the transaction has initially failed.

?txn[reserved][equals]=1

Targets only holds that blocked a transaction

Transaction Holds Filter Query Use Cases

The following section outlines specific HTTP queries that serve as powerful tools for achieving targeted use cases when retrieving information related to transaction holds. These queries can be effectively utilized not only for retrieving data but also for enhancing the filtering capabilities of web applications. By incorporating these HTTP queries into the configuration of web apps, you can streamline the process of sorting and identifying transaction holds based on specific criteria, thereby optimizing your user experience and facilitating efficient management of transaction holds.

All Open Transaction Holds

Filter and retrieve all open transaction holds that have not been released, ensuring a focus on active holds that require attention. It helps in identifying and managing transactions that are currently on hold, allowing for prompt actions to be taken to address any potential risks or issues.

CODE
?txn[id][greater]=0&txn[holds][released][exact]=null&txn[reserved][greater]=0&txn[status][in]=1,3,4,5&txn[holds][created][sort]=asc

Conditions

  • Transaction ID is greater than 0, ensuring all transaction IDs are included.

  • Hold has not been released (txn[holds][released][exact]=null), indicating an open hold.

  • The Reserved transaction amount is greater than 0, also indicating an open and held amount.

  • The transaction status is 1, 3, 4, or 5, indicating a “Block”, “Hold”, “Reserve”, or “Limit” status and removing any “Failed” transaction statuses, which can’t be held

  • Results are sorted by the created date of the hold in ascending order.

Open Transaction Holds Not in Review

Retrieve open transaction holds not reviewed by a Risk analyst. Focus on active holds needing attention without review. Identify transactions on hold, unassessed for risks or issues. Query includes only pending holds for prompt action addressing concerns with unreviewed holds.

CODE
?txn[id][greater]=0&txn[holds][reviewed][exact]=null&txn[holds][released][exact]=null&txn[reserved][greater]=0&txn[status][in]=0,1,3,4,5&txn[holds][created][sort]=asc

Conditions

  • Transaction ID is greater than 0, ensuring all transaction IDs are included.

  • The Hold has not been reviewed (txn[holds][reviewed][exact]=null), indicating an open hold.

  • The Hold has not been released (txn[holds][released][exact]=null), indicating an open hold.

  • The Reserved transaction amount is greater than 0, also indicating an open and held amount.

  • The transaction status is 1, 3, 4, or 5, indicating a “Block”, “Hold”, “Reserve”, or “Limit” status and removing any “Failed” transaction statuses, which can’t be held

  • Results are sorted by the created date of the hold in ascending order.

Transaction Holds in Risk Review

Filter and retrieve transaction holds post-risk analyst review. Query helps manage active holds needing attention after Risk analyst review. Pinpoint transactions assessed for risks, facilitating prompt actions. Results include only reviewed holds, aiding in efficient operations and issue resolution related to these holds.

CODE
?txn[id][greater]=0&txn[holds][reviewed][greater]=0&txn[holds][released][exact]=null&txn[reserved][greater]=0&txn[holds][created][sort]=asc

Conditions

  • Transaction ID is greater than 0, ensuring all transaction IDs are included.

  • The Hold has been reviewed (txn[holds][reviewed][greater]=0), indicating a reviewed, but open hold.

  • The Hold has not been released (txn[holds][released][exact]=null), indicating an open hold.

  • The Reserved transaction amount is greater than 0, also indicating an open and held amount.

  • Results are sorted by the created date of the hold in ascending order.

Transaction Holds Released

Filter and retrieve released transaction holds. Identify and manage previously active holds now released by Risk analyst. Pinpoint transactions no longer restricted, track their progression. Query includes only released holds for insights into held transactions' status.

CODE
?txn[id][greater]=0&txn[holds][released][greater]=0&txn[holds][created][sort]=asc

Conditions

  • Transaction ID is greater than 0, ensuring all transaction IDs are included.

  • The Hold has been reviewed (txn[holds][released][greater]=0), indicating a reviewed and released hold.

  • Results are sorted by the created date of the hold in ascending order.

Transactions Declined Due to Risk Rules

Retrieve declined transactions due to risk rules. Identify failed transactions triggering specific risk criteria. Pinpoint failures in meeting established rules, understanding decline reasons. Query includes only transactions declined by risk rules for insightful analysis of processing failures.

CODE
?txn[id][greater]=0&txn[reserved][equals]=1&txn[holds][created][sort]=asc

Conditions

  • Transaction ID is greater than 0, ensuring all transaction IDs are included.

  • The Reserved parameter is 1, (txn[reserved][equals]=1) indicating a full or partial reserve for the transaction being held.

 

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.