# Queues tutorial source: https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/queues-tutorial/index.md ## Overview {#overview} This tutorial will show you how issuers and acquirers retrieve a list of all queues and their fields, fields for a specific queue, and a list of claims within a queue. Queues gather various related dispute events and place them into a single location for users to work easily on them. #### What you will learn {#what-you-will-learn} > * How to retrieve a list of all queues and their fields > * How to retrieve fields for a specific queue > * How to retrieve a list of claims in a queue ## Before you start {#before-you-start} Before starting this tutorial, ensure that you have already completed the following: * [Mastercom Extended API Client Generation Tutorial](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/clientgeneration-tutorial/index.md) * [Quick Start Guide](https://developer.mastercard.com/mastercom-extended/documentation/quick-start-guide/index.md) ## Step 1: Review Queue names and their associated Queue ID and Queue fields {#step-1-review-queue-names-and-their-associated-queue-id-and-queue-fields} Refer to the following table for details. | Queue Name | Queue ID | Queue Fields | |--------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Claims with No Activity *Region: Global, India domestic* | 19 | claimId claimCreateDate issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber transactionAmount transactionDateTime settlementDate numericTransactionCurrencyCode alphaTransactionCurrencyCode primaryAccountNumber tokenizedPrimaryAccountNumber claimOwnerUserId | | Issuer Collaboration Unworked *Region: Global* | 20 | claimId eventId eventExpiryDateTime collaborationResponseCode collaborationInitiationAmount numericCollaborationCurrencyCode alphaCollaborationCurrencyCode totalDisputeAmount transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Acquirer Collaboration Unworked *Region: Global* | 1 | claimId eventId eventExpiryDateTime collaborationResponseCode collaborationInitiationAmount numericCollaborationCurrencyCode alphaCollaborationCurrencyCode totalDisputeAmount transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Acquirer First Chargeback Unworked *Region: Global, India domestic* | 11 | claimId eventId eventExpiryDateTime chargebackReasonCode documentIndicator documentStatus disputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode totalDisputeAmount transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Issuer Representment Unworked *Region: Global, India domestic* | 25 | claimId eventId eventExpiryDateTime chargebackReasonCode representmentReasonCode documentIndicator documentStatus disputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode totalDisputeAmount transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Pending Documentation *Region: Global, India domestic* | 10 | claimId eventType eventId documentDueDate adjustmentReasonCode chargebackReasonCode representmentReasonCode documentStatus disputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode totalDisputeAmount issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber ventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId sendDisputeReasonCode sendDisputeReasonCodeDescription response postingStatusResponse | | Issuer Worked *Region: Global, India domestic* | 9 | claimId eventType eventId eventExpiryDateTime collaborationResponseCode collaborationInitiationAmount numericCollaborationCurrencyCode alphaCollaborationCurrencyCode chargebackReasonCode representmentReasonCode documentStatus disputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode totalDisputeAmount transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Acquirer Worked *Region: Global, India domestic* | 12 | claimId eventType eventId eventExpiryDateTime adjustmentReasonCode collaborationResponseCode collaborationInitiationAmount numericCollaborationCurrencyCode alphaCollaborationCurrencyCode chargebackReasonCode representmentReasonCode documentStatus disputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode totalDisputeAmount transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Closed Claim *Region: Global, India domestic* | 5 | claimId claimCreateDate totalDisputeAmount issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber transactionDateTime transactionAmount numericTransactionCurrencyCode alphaTransactionCurrencyCode primaryAccountNumberMasked tokenizedPrimaryAccountNumber claimOwnerUserId claimLastModifiedBy claimLastUpdateDate | | Rejects *Region: Global, India domestic* | 8 | claimId eventType eventId eventExpiryDateTime adjustmentReasonCode chargebackReasonCode representmentReasonCode disputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode totalDisputeAmount transactionAmount transactionDateTime settlementDate numericTransactionCurrencyCode alphaTransactionCurrencyCode issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | | Sender Case Filing *Region: Global, India domestic* | 26 | caseId caseType cardholderNumber virtualAccountNumber chargebackReasonCode section violationDate disputeAmount disputeAmountCurrencyCode arn chargebackReferenceNumber filingIca filedAgainstIca filingRegion filedAgainstRegion memberFileNumber responseDueDate merchantName cleansedMerchantName fileAs submittedBy submittedDate rebuttedBy rejectedBy rejectedDate escalatedBy escalatedDate acceptedDate acceptedUser withdrawnBy withdrawnDate ruling rulingDate caseState billingCurrencyCode senderSettlementAmount senderSettlementAmtCurrCode pointOfServiceDataCode senderEndpoint referenceName extendedClaim receiverEndpoint unjustEnrichmentCBDate unjustEnrichmentCreditDate ossn settlementDate filedAgainstIcaDate acquirerCountryCode issuerCountryCode cardPresenceIndicator productTypeCode mcomPartyCode displayPriorityLevel senderBill senderBillingFeesEur senderDisputeCurrencyCode senderBillingFeesGbp senderBillingFeesUsd senderDisputeAmount | | Receiver Case Filing *Region: Global, India domestic* | 27 | caseId caseType cardholderNumber virtualAccountNumber chargebackReasonCode section violationDate disputeAmount disputeAmountCurrencyCode arn chargebackReferenceNumber filingIca filedAgainstIca filingRegion filedAgainstRegion memberFileNumber responseDueDate merchantName cleansedMerchantName fileAs submittedBy submittedDate rebuttedBy rejectedBy rejectedDate escalatedBy escalatedDate acceptedDate acceptedUser withdrawnBy withdrawnDate ruling rulingDate caseState billingCurrencyCode senderSettlementAmount senderSettlementAmtCurrCode pointOfServiceDataCode senderEndpoint referenceName extendedClaim receiverEndpoint unjustEnrichmentCBDate unjustEnrichmentCreditDate ossn settlementDate filedAgainstIcaDate acquirerCountryCode issuerCountryCode cardPresenceIndicator productTypeCode mcomPartyCode displayPriorityLevel receiverBill receiverBillingFeesEur receiverDisputeCurrencyCode receiverBillingFeesGbp receiverBillingFeesUsd receiverDisputeAmount | | Send Payment Originating Institution Worked *Region: Global, India domestic* | 31 | claimId eventId sendDisputeReasonCode sendDisputeReasonCodeDescription response postingStatusResponse sendDisputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode documentStatus eventExpiryDateTime transactionDateTime issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId sendDisputeFraudSubReasonCode sendDisputeFraudSubReasonCodeDescription | | Send Payment Receiving Institution Unworked *Region: Global, India domestic* | 30 | claimId eventId sendDisputeReasonCode sendDisputeReasonCodeDescription sendDisputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode documentStatus eventExpiryDateTime transactionDateTime issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId sendDisputeFraudSubReasonCode sendDisputeFraudSubReasonCodeDescription | | Send Payment Receiving Institution Worked *Region: Global, India domestic* | 32 | claimId eventId sendDisputeReasonCode sendDisputeReasonCodeDescription response postingStatusResponse sendDisputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode documentStatus eventExpiryDateTime transactionDateTime issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId sendDisputeFraudSubReasonCode sendDisputeFraudSubReasonCodeDescription | | Send Payment Originating Institution Unworked *Region: Global, India domestic* | 29 | claimId eventId sendDisputeReasonCode sendDisputeReasonCodeDescription sendDisputeAmount numericDisputeAmountCurrencyCode alphaDisputeAmountCurrencyCode documentStatus eventExpiryDateTime transactionDateTime issuerICA acquirerICA acquirerReferenceNumber switchSerialNumber primaryAccountNumberMasked tokenizedPrimaryAccountNumber eventLastModifiedBy eventLastUpdateDate claimLastModifiedBy claimLastUpdateDate claimOwnerUserId | ## Step 2: Retrieve a list of all queues and their fields {#step-2-retrieve-a-list-of-all-queues-and-their-fields} The issuer or acquirer uses this endpoint to retrieve a list of all queues and their fields. A claim is always associated with at least one queue. API Reference: `GET /queues` Before retrieving claims from a queue, you need to know which queues are available. To work with queues, create a `QueuesApi` object. Use method `queuesApi.getQueueList` to list all available queues. Optionally, the limit and offset can be provided. ```java public class Main { public static void main(String[] args) { // API client set up here... QueuesApi queuesApi = new QueuesApi(client); Integer offset = 0; Integer limit = 25; try { QueueDefinitionsList result = queuesApi.getQueueList(offset, limit); result.getDefinitions().forEach( q -> System.out.println("queueId: " + q.getQueueId() + " | queueName: " + q.getName()) ); } catch (ApiException e) { System.err.println("Exception when calling QueuesApi#queueDefinitionList"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Review the possible error codes associated with this request {#review-the-possible-error-codes-associated-with-this-request} | HTTP Code | Error | Error Description | Error Code | |-----------|------------------------|------------------------|------------| | 401 | NOT_AUTHORIZED_REQUEST | User is not authorized | 200010 | Review additional error codes [here](https://developer.mastercard.com/mastercom-extended/documentation/code-and-formats/errorsandexceptions/index.md). #### Verify response {#verify-response} You should receive a 200 OK response. Returns a list of queues and their details, including the `queueId`. Use the `queueId` to list claims from a specific queue. ## Step 3: Retrieve fields for a specific queue {#step-3-retrieve-fields-for-a-specific-queue} The issuer or acquirer uses this endpoint to retrieve fields within a specific queue. API Reference: `GET /queues/{queue_id}` To retrieve the fields that will be returned on a particular queue, create a `QueuesApi` object. Then use method `queuesApi.getQueueDefinition` to retrieve the specified queue definition. This method only expects a `queueId` as part of the path. ```java public class Main { public static void main(String[] args) { // API client set up here... QueuesApi queuesApi = new QueuesApi(client); try { QueueDefinition result = queuesApi.getQueueDefinition(queueId); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling QueuesApi#getQueueDefinition"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` ### Review the possible error codes associated with this request {#review-the-possible-error-codes-associated-with-this-request-1} | HTTP Code | Error | Error Description | Error Code | |-----------|------------------------|------------------------|------------| | 400 | INVALID_INPUT | Invalid input | 230004 | | 401 | NOT_AUTHORIZED_REQUEST | User is not authorized | 200010 | | 404 | RESOURCE_NOT_FOUND | `queue_id` not found | 200005 | Review additional error codes [here](https://developer.mastercard.com/mastercom-extended/documentation/code-and-formats/errorsandexceptions/index.md). ### Verify response {#verify-response-1} You should receive a 200 OK response. Returns the fields within the queue. ## Step 4: Retrieve list of claims in a queue {#step-4-retrieve-list-of-claims-in-a-queue} The issuer or acquirer uses this endpoint to retrieve a list of claims in a queue within a specified date range. To work with claims, retrieve the `claimId` from a specific queue and apply actions to the claim according to the claim's state. API Reference: `GET /queues/{queue_id}/claims` Retrieve the claims from a specific queue by providing the `queueId`, `startDate`, `endDate`, `offset`, and `limit`. Set the date range for the search. Optionally, the limit and offset can be provided. You then call `queuesApi.queueSearch(queueId, startDate, endDate, offset, limit)` to perform the search. ```java public class Main { public static void main(String[] args) { // API client set up here... QueuesApi queuesApi = new QueuesApi(client); String queueId = "1"; OffsetDateTime startDate = OffsetDateTime.now().withOffsetSameInstant(ZoneOffset.UTC).minusDays(1); OffsetDateTime endDate = OffsetDateTime.now().withOffsetSameInstant(ZoneOffset.UTC); Integer offset = 0; Integer limit = 25; try { Queue result = queuesApi.queueSearch(queueId, startDate, endDate, offset, limit); List claimDataList = result.getData(); claimDataList.forEach(System.out::println); } catch (ApiException e) { System.err.println("Exception when calling QueuesApi#queueSearch"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Review the possible error codes associated with this request {#review-the-possible-error-codes-associated-with-this-request-2} | HTTP Code | Error | Error Description | Error Code | |-----------|------------------------|---------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | 400 | INVALID_FORMAT | Invalid format for field `fieldName` | 220000 | | 400 | KEY_INVALID | The parameter `date_filter_key` is NOT applicable for this `queue-id`. Refer to queue table for more details. | 220032 | | 400 | INVALID_INPUT_VALUE | Invalid input value for field `fieldName` | 230000 | | 400 | INVALID_INPUT_VALUE | Minimum search date limit is `{{0}}` `{{1}}` | 230000 | | 400 | INVALID_INPUT_VALUE | Largest search window allowed is `{{0}}` `{{1}}` | 230000 | | 400 | INVALID_INPUT_VALUE | The `end_date_time` cannot be before the `start_date_time` | 230000 | | 400 | INVALID_INPUT_VALUE | Invalid input value for field `sort_order` | 230000 | | 400 | INVALID_INPUT_VALUE | Invalid input value for field `sort_key` | 230000 | | 400 | INVALID_INPUT_VALUE | Invalid input value for field `date_filter_key` | 230000 | | 400 | INVALID_INPUT | Invalid input | 230004, 230005, 230006, 230007, 230008, 230009, 230010, 230011, 230012, 230013, 230014, 230015, 230016, 230017 | | 400 | INVALID_INPUT_VALUE | INVALID_INPUT_VALUE | 230000 | | 400 | MISSING_REQUIRED_INPUT | Missing required field `fieldName` | 250000 | | 401 | NOT_AUTHORIZED_REQUEST | User is not authorized | 200010 | Review additional error codes [here](https://developer.mastercard.com/mastercom-extended/documentation/code-and-formats/errorsandexceptions/index.md). #### Verify response {#verify-response-2} You should receive a 200 OK response. Returns the list of claims in the specified queue. Return to [Tutorials](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/index.md).