# Retrieval API
source: https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/api-reference/retrieval-api/index.md

The Retrieval API gets information about payment transfers that you initiated using the [Payment API](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/api-reference/payment-api/index.md). You can retrieve transfer details by either:

* Transfer Reference, using the `transfer_reference` you provided when you created the transfer
* Transfer ID, using the system-generated `id` that was returned when you created the transfer

<br />

A transaction response (200) with an 'APPROVED' status (`"status": "APPROVED"`) indicates that the Payment Transaction was successful. In some situations, a transaction response can have an 'UNKNOWN' status: `"status": "UNKNOWN"`. For information on what to do, see [Transaction Responses with an 'UNKNOWN' Status](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/response-error-codes/index.md#transaction-responses-with-an-unknown-status). If the status is 'PENDING', the transaction is still in progress; retry with another GET request.

## Environment Domains {#environment-domains}

* **Sandbox:** <https://sandbox.api.mastercard.com/send/static>
* **MTF:** <https://sandbox.api.mastercard.com/send>
* **Production:** <https://api.mastercard.com/send>

## API {#api}

This API supports JSON and XML requests. The expandable sections below show a JSON request and response. For XML examples, see [Sample Requests and Responses](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/api-reference/retrieval-api/index.md#sample-requests-and-responses). Use [HTTP Headers](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/api-basics/index.md#http-headers) to determine the response format. We recommend you log the Correlation ID (correlation-id) response header value for tracking purposes. When seeking support, providing the relevant Correlation ID may help resolve your inquiry more quickly.

The `partnerId` portion of the URL makes the request unique to a specific Originating Institution or Transaction Originator:

* Sandbox API: Use the ID `ptnr_BEeCrYJHh2BXTXPy_PEtp-8DBOo`
* MTF and Production APIs: Use the Partner Reference ID you receive when you register for the MPQR program

Note: We updated the API specification to OpenAPI 3.0.3 in September 2022, adjusting some definition names to better meet API standards. The API and its endpoints did not change. However, if you previously generated an API client using an earlier version of this specification and then regenerate the client or classes from this newer version, you might need to adjust your code.
API Specification: `https://static.developer.mastercard.com/content/mastercard-merchant-presented-qr/swagger/MerchantRetrieval_swagger_final.yaml`

## Sandbox Testing {#sandbox-testing}

You can make API calls to the Sandbox server from an API tool, your application code or the [tutorials](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/tutorials-and-guides/index.md), which involves creating a Mastercard Developers project (see [Getting Started](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/getting-started/index.md)) and using the Sandbox keys to generate the OAuth 1.0a Authorization Header.

The Sandbox server returns simulated responses. You can use the following test data to produce specific responses.
Note: The following tests are based on using Transfer Reference or ID values that either were or were not used/returned when you made API calls to the Payment API Sandbox environment.

### Sandbox Simulated Test Responses {#sandbox-simulated-test-responses}

#### Retrieval by Transfer Reference {#retrieval-by-transfer-reference}

|                    Test Scenario                     |                           Request Test Data                            |    HTTP Status / Reason Code    |                             Result                             |
|------------------------------------------------------|------------------------------------------------------------------------|---------------------------------|----------------------------------------------------------------|
| Happy Path -- Merchant Transfer Retrieval            | Any Transfer Reference used in a previous Payment API Sandbox call     | 200 / Transaction is Successful | Retrieve Merchant Transfer by Transfer reference is successful |
| Retrieve Transaction with Invalid Transfer Reference | Transfer Reference **not** used in a previous Payment API Sandbox call | 404 / RESOURCE_UNKNOWN          | Record not found                                               |

#### Retrieval by Transfer ID {#retrieval-by-transfer-id}

|                 Test Scenario                 |                                              Request Test Data                                              |    HTTP Status / Reason Code    |                         Result                         |
|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------|---------------------------------|--------------------------------------------------------|
| Happy Path -- Merchant Transfer Approval      | Any Transfer ID returned for a previous Payment API Sandbox call                                            | 200 / Transaction is Successful | Retrieve Merchant Transfer Payment by ID is successful |
| Retrieve Transaction with Invalid Transfer ID | Transfer ID **not** returned for a previous Payment API Sandbox call, e.g. mtrn_2tGpG2lkQGnZCT3HKP_p9HbH6GK | 404 / RESOURCE_UNKNOWN          | Record not found                                       |

## MTF Testing {#mtf-testing}

As MTF is a testing environment, it has specific functionality designed for testing as well as a smaller dataset for quick data retrieval.

Your [Mastercard representative](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/support/index.md) will provide test cases.

## Sample Requests and Responses {#sample-requests-and-responses}

### Retrieval by Transfer Reference---Request {#retrieval-by-transfer-referencemdashrequest}

**Sandbox URL:** [https://sandbox.api.mastercard.com/send/static/v1/partners/{partnerId}/merchant/transfers?ref={transfer_reference}](https://sandbox.api.mastercard.com/send/static/v1/partners/%7BpartnerId%7D/merchant/transfers?ref=%7Btransfer_reference%7D)

**MTF URL:** [https://sandbox.api.mastercard.com/send/v1/partners/{partnerId}/merchant/transfers?ref={transfer_reference}](https://sandbox.api.mastercard.com/send/v1/partners/%7BpartnerId%7D/merchant/transfers?ref=%7Btransfer_reference%7D)

**Production URL:** [https://api.mastercard.com/send/v1/partners/{partnerId}/merchant/transfers?ref={transfer_reference}](https://api.mastercard.com/send/v1/partners/%7BpartnerId%7D/merchant/transfers?ref=%7Btransfer_reference%7D)

**Format:** JSON / XML  

**HTTP Methods:** GET  

**HTTP Version:** 1.0 / 1.1  

**HTTP Header Parameters:**

|   Param Name   |                    Description                     | Details  |     Example      |
|----------------|----------------------------------------------------|----------|------------------|
| content-type   | The format of the inbound content being submitted. | Required | application/json |
| content-length | The length of the inbound content body in octets.  | Required |                  |

**Body:**   

None

### Retrieval by Transfer Reference---Response {#retrieval-by-transfer-referencemdashresponse}

**Headers:**   

content-type: application/{type}  

content-length: {length}

**Body:**
* JSON
* XML

```JSON
{
  "merchant_transfers": {
    "data": {
      "merchant_transfer": [
        {
          "sender": {
            "address": {
              "line1": "21Broadway",
              "line2": "ApartmentA-62",
              "city": "OFallon",
              "country": "USA",
              "country_subdivision": "MO",
              "postal_code": "63368"
            },
            "phone": "123456789",
            "email": "test123@abcmail.com",
            "first_name": "Fred",
            "middle_name": "Pete",
            "last_name": "Flinstone",
            "date_of_birth": "1994-05-21"
          },
          "recipient": {
            "address": {
              "line1": "1MainSt",
              "line2": "Apartment9",
              "city": "OFallon",
              "country": "USA",
              "country_subdivision": "MO",
              "postal_code": "63368"
            },
            "phone": "123456789",
            "email": "test123@abcmail.com",
            "first_name": "Fred",
            "middle_name": "Pete",
            "last_name": "Flinstone",
            "merchant_category_code": "4829"
          },
          "created": "2019-11-20T12:43:47-06:00",
          "status": "APPROVED",
          "participant": {
            "card_acceptor_name": "testmerchant"
          },
          "id": "mtrn_4XqoWZQlyjSr5O94vf21k7rtlo6",
          "resource_type": "merchant_transfer",
          "transfer_reference": "MPQR_157427542617121",
          "payment_type": "P2M",
          "sender_account_uri": "pan:************0149",
          "recipient_account_uri": "pan:************0277",
          "transfer_amount": {
            "value": "120",
            "currency": "USD"
          },
          "transaction_history": {
            "data": {
              "transaction": [
                {
                  "network": "MoneySend",
                  "network_status_code": "00",
                  "network_status_description": "APPROVED",
                  "type": "PAYMENT",
                  "id": "txn_C0tsnFdspuqdL_FwqiG9PROlA39Q",
                  "resource_type": "transaction",
                  "account_uri": "pan:************0277",
                  "transaction_amount": {
                    "value": "120",
                    "currency": "USD"
                  },
                  "funds_availability": "IMMEDIATE",
                  "create_timestamp": "2019-11-20T12:43:47-06:00",
                  "status": "APPROVED",
                  "status_reason": "APPROVED",
                  "status_timestamp": "2019-11-20T12:43:48-06:00",
                  "retrieval_reference": "932412042463",
                  "system_trace_audit_number": "042463",
                  "switch_serial_number": "264491706",
                  "unique_reference_number": "0000000000623360505",
                  "authorization_id": "9CCDC8",
                  "payment_account_reference": "6B8DE8BC44AC59EB222CA9BB3E688",
                  "convenience_amount": "100",
                  "convenience_indicator": "01",
                  "qr_data": "0305A6008070845784312"
                }
              ]
            },
            "resource_type": "list",
            "item_count": 1
          },
          "reconciliation_data": {
            "custom_field": [
              {
                "name": "Paymentid",
                "value": "123"
              },
              {
                "name": "tranid",
                "value": "456"
              },
              {
                "name": "reference",
                "value": "789"
              }
            ]
          },
          "channel": "KIOSK",
          "device_id": "DEVICE-1234",
          "location": "state:MO",
          "original_status": "APPROVED",
          "status_timestamp": "2019-11-20T12:43:48-06:00",
          "payment_origination_country": "IND",
          "transaction_local_date_time": "2017-09-22T13:22:11-05:30",
          "funding_source": "CASH",
          "mastercard_assigned_id": "111111",
          "additional_message": "0305A6008070845784312"
        }
      ]
    },
    "item_count": 1,
    "resource_type": "list"
  }
}
```

```XML
<merchant_transfers>
  <resource_type>list</resource_type>
  <item_count>1</item_count>
  <data>
    <merchant_transfer>
  <id>mtrn_3_FgL6lX0BMWn0DdOswf5bZcnTR</id>
      <resource_type>merchant_transfer</resource_type>
  <transfer_reference>MPQR_157229565564621</transfer_reference>
      <payment_type>P2M</payment_type>
      <sender_account_uri>pan:************0149</sender_account_uri>
      <sender>
        <first_name>Fred</first_name>
        <middle_name>Pete</middle_name>
        <last_name>Flinstone</last_name>
        <date_of_birth>1994-05-21</date_of_birth>
        <address>
          <line1>21Broadway</line1>
          <line2>ApartmentA-62</line2>
          <city>OFallon</city>
          <country_subdivision>MO</country_subdivision>
          <postal_code>63368</postal_code>
          <country>USA</country>
        </address>
        <phone>123456789</phone>
        <email>test123@abcmail.com</email>
      </sender>
      <recipient_account_uri>pan:************0277</recipient_account_uri>
      <recipient>
        <first_name>Fred</first_name>
        <middle_name>Pete</middle_name>
        <last_name>Flinstone</last_name>
        <address>
          <line1>1MainSt</line1>
          <line2>Apartment9</line2>
          <city>OFallon</city>
          <country_subdivision>MO</country_subdivision>
          <postal_code>63368</postal_code>
          <country>USA</country>
        </address>
        <phone>123456789</phone>
        <email>test123@abcmail.com</email>
        <merchant_category_code>4829</merchant_category_code>
      </recipient>
      <transfer_amount>
        <value>120</value>
        <currency>USD</currency>
      </transfer_amount>
  <convenience_amount>100</convenience_amount>
  <convenience_indicator>01</convenience_indicator>
  <qr_data>0305A6008070845784312</qr_data>
  <created>2019-10-28T15:47:37-05:00</created>
      <transaction_history>
        <resource_type>list</resource_type>
        <item_count>1</item_count>
        <data>
          <transaction>
        <id>txn_zaF2vCA6gq0Z8FDRsB5brKNqPtGc</id>
            <resource_type>transaction</resource_type>
            <account_uri>pan:************0277</account_uri>
            <transaction_amount>
              <value>120</value>
              <currency>USD</currency>
            </transaction_amount>
            <network>MoneySend</network>
            <network_status_code>00</network_status_code>
            <network_status_description>APPROVED</network_status_description>
            <funds_availability>IMMEDIATE</funds_availability>
            <type>PAYMENT</type>
            <create_timestamp>2019-10-28T15:47:37-05:00</create_timestamp>
            <status>APPROVED</status>
            <status_reason>APPROVED</status_reason>
             <status_timestamp>2019-10-28T15:47:37-05:00</status_timestamp>
        <retrieval_reference>930115640876</retrieval_reference>
        <system_trace_audit_number>640876</system_trace_audit_number>
        <switch_serial_number>680681587</switch_serial_number>
        <unique_reference_number>0000000000002107618</unique_reference_number>
        <authorization_id>BEE129</authorization_id>
        <payment_account_reference>11CC24FA64200BD878BA8F4117971</payment_account_reference>
            <convenience_amount>100</convenience_amount>
            <convenience_indicator>01</convenience_indicator>
            <qr_data>0305A6008070845784312</qr_data>
          </transaction>
        </data>
      </transaction_history>
      <reconciliation_data>
        <custom_field>
          <name>Paymentid</name>
          <value>123</value>
        </custom_field>
        <custom_field>
          <name>tranid</name>
          <value>456</value>
        </custom_field>
        <custom_field>
          <name>reference</name>
          <value>789</value>
        </custom_field>
      </reconciliation_data>
      <channel>KIOSK</channel>
      <device_id>DEVICE-1234</device_id>
      <location>state:MO</location>
      <original_status>APPROVED</original_status>
      <status>APPROVED</status>
  <status_timestamp>2019-10-28T15:47:37-05:00</status_timestamp>
      <payment_origination_country>IND</payment_origination_country>
      <transaction_local_date_time>2017-09-22T13:22:11-05:30</transaction_local_date_time>
      <funding_source>CASH</funding_source>
      <mastercard_assigned_id>111111</mastercard_assigned_id>
      <participant>
        <card_acceptor_name>testmerchant</card_acceptor_name>
      </participant>
      <additional_message>0305A6008070845784312</additional_message>
  <participation_id>Imparticipating1</participation_id>
      <interchange_rate_designator>QR</interchange_rate_designator>
    </merchant_transfer>
  </data>
</merchant_transfers>
```

### Retrieval by Transfer ID---Request {#retrieval-by-transfer-idmdashrequest}

**Sandbox URL:** [https://sandbox.api.mastercard.com/send/static/v1/partners/{partnerId}/merchant/transfers/{transferId}](https://sandbox.api.mastercard.com/send/static/v1/partners/%7BpartnerId%7D/merchant/transfers/%7BtransferId%7D)

**MTF URL:** [https://sandbox.api.mastercard.com/send/v1/partners/{partnerId}/merchant/transfers/{transferId}](https://sandbox.api.mastercard.com/send/v1/partners/%7BpartnerId%7D/merchant/transfers/%7BtransferId%7D)

**Production URL:** [https://api.mastercard.com/send/v1/partners/{partnerId}/merchant/transfers/{transferId}](https://api.mastercard.com/send/v1/partners/%7BpartnerId%7D/merchant/transfers/%7BtransferId%7D)

**Formats:** JSON / XML  

**HTTP Methods:** GET  

**HTTP Version:** 1.0 / 1.1  

**HTTP Header Parameters:**

|   Param Name   |                    Description                     | Details  |     Example      |
|----------------|----------------------------------------------------|----------|------------------|
| content-type   | The format of the inbound content being submitted. | Required | application/json |
| content-length | The length of the inbound content body in octets.  | Required |                  |

**Body:**   

None

### Retrieval by Transfer ID---Response {#retrieval-by-transfer-idmdashresponse}

**Headers:**   

content-type: application/{type}  

content-length: {length}

**Body:**
* JSON
* XML

```JSON
{
  "merchant_transfer": {
    "sender": {
      "address": {
        "line1": "21Broadway",
        "line2": "ApartmentA-62",
        "city": "OFallon",
        "country": "USA",
        "country_subdivision": "MO",
        "postal_code": "63368"
      },
      "phone": "123456789",
      "email": "test123@abcmail.com",
      "first_name": "Fred",
      "middle_name": "Pete",
      "last_name": "Flinstone",
      "date_of_birth": "1994-05-21"
    },
    "recipient": {
      "address": {
        "line1": "1MainSt",
        "line2": "Apartment9",
        "city": "OFallon",
        "country": "USA",
        "country_subdivision": "MO",
        "postal_code": "63368"
      },
      "phone": "123456789",
      "email": "test123@abcmail.com",
      "first_name": "Fred",
      "middle_name": "Pete",
      "last_name": "Flinstone",
      "merchant_category_code": "4829"
    },
    "created": "2019-11-20T12:43:47-06:00",
    "status": "APPROVED",
    "participant": {
      "card_acceptor_name": "testmerchant"
    },
    "id": "mtrn_4XqoWZQlyjSr5O94vf21k7rtlo6",
    "resource_type": "merchant_transfer",
    "transfer_reference": "MPQR_157427542617121",
    "payment_type": "P2M",
    "sender_account_uri": "pan:************0149",
    "recipient_account_uri": "pan:************0277",
    "transfer_amount": {
      "value": "120",
      "currency": "USD"
    },
    "transaction_history": {
      "data": {
        "transaction": [
          {
            "network": "MoneySend",
            "network_status_code": "00",
            "network_status_description": "APPROVED",
            "type": "PAYMENT",
            "id": "txn_C0tsnFdspuqdL_FwqiG9PROlA39Q",
            "resource_type": "transaction",
            "account_uri": "pan:************9903",
            "transaction_amount": {
              "value": "120",
              "currency": "USD"
            },
            "funds_availability": "IMMEDIATE",
            "create_timestamp": "2019-11-20T12:43:47-06:00",
            "status": "APPROVED",
            "status_reason": "APPROVED",
            "status_timestamp": "2019-11-20T12:43:48-06:00",
            "retrieval_reference": "932412042463",
            "system_trace_audit_number": "042463",
            "switch_serial_number": "264491706",
            "unique_reference_number": "0000000000623360505",
            "authorization_id": "9CCDC8",
            "payment_account_reference": "6B8DE8BC44AC59EB222CA9BB3E688",
            "convenience_amount": "100",
            "convenience_indicator": "01",
            "qr_data": "0305A6008070845784312"
          }
        ]
      },
      "resource_type": "list",
      "item_count": 1
    },
    "reconciliation_data": {
      "custom_field": [
        {
          "name": "Paymentid",
          "value": "123"
        },
        {
          "name": "tranid",
          "value": "456"
        },
        {
          "name": "reference",
          "value": "789"
        }
      ]
    },
    "channel": "KIOSK",
    "device_id": "DEVICE-1234",
    "location": "state:MO",
    "original_status": "APPROVED",
    "status_timestamp": "2019-11-20T12:43:48-06:00",
    "payment_origination_country": "IND",
    "transaction_local_date_time": "2017-09-22T13:22:11-05:30",
    "funding_source": "CASH",
    "mastercard_assigned_id": "111111",
    "additional_message": "0305A6008070845784312"
  }
}
```

```XML
<merchant_transfer>
  <id>mtrn_3_FgL6lX0BMWn0DdOswf5bZcnTR</id>
  <resource_type>merchant_transfer</resource_type>
  <transfer_reference>MPQR_157229565564621</transfer_reference>
  <payment_type>P2M</payment_type>
  <sender_account_uri>pan:************0149</sender_account_uri>
  <sender>
    <first_name>Fred</first_name>
    <middle_name>Pete</middle_name>
    <last_name>Flinstone</last_name>
    <date_of_birth>1994-05-21</date_of_birth>
    <address>
      <line1>21Broadway</line1>
      <line2>ApartmentA-62</line2>
      <city>OFallon</city>
      <country_subdivision>MO</country_subdivision>
      <postal_code>63368</postal_code>
      <country>USA</country>
    </address>
    <phone>123456789</phone>
    <email>test123@abcmail.com</email>
  </sender>
  <recipient_account_uri>pan:************0277</recipient_account_uri>
  <recipient>
    <first_name>Fred</first_name>
    <middle_name>Pete</middle_name>
    <last_name>Flinstone</last_name>
    <address>
      <line1>1MainSt</line1>
      <line2>Apartment9</line2>
      <city>OFallon</city>
      <country_subdivision>MO</country_subdivision>
      <postal_code>63368</postal_code>
      <country>USA</country>
    </address>
    <phone>123456789</phone>
    <email>test123@abcmail.com</email>
    <merchant_category_code>4829</merchant_category_code>
  </recipient>
  <transfer_amount>
    <value>120</value>
    <currency>USD</currency>
  </transfer_amount>
  <convenience_amount>100</convenience_amount>
  <convenience_indicator>01</convenience_indicator>
  <qr_data>0305A6008070845784312</qr_data>
  <created>2019-10-28T15:47:37-05:00</created>
  <transaction_history>
    <resource_type>list</resource_type>
    <item_count>1</item_count>
    <data>
      <transaction>
        <id>txn_zaF2vCA6gq0Z8FDRsB5brKNqPtGc</id>
        <resource_type>transaction</resource_type>
        <account_uri>pan:************0277</account_uri>
        <transaction_amount>
          <value>120</value>
          <currency>USD</currency>
        </transaction_amount>
        <network>MoneySend</network>
        <network_status_code>00</network_status_code>
        <network_status_description>APPROVED</network_status_description>
        <funds_availability>IMMEDIATE</funds_availability>
        <type>PAYMENT</type>
        <create_timestamp>2019-10-28T15:47:37-05:00</create_timestamp>
        <status>APPROVED</status>
        <status_reason>APPROVED</status_reason>
        <status_timestamp>2019-10-28T15:47:37-05:00</status_timestamp>
        <retrieval_reference>930115640876</retrieval_reference>
        <system_trace_audit_number>640876</system_trace_audit_number>
        <switch_serial_number>680681587</switch_serial_number>
        <unique_reference_number>0000000000002107618</unique_reference_number>
        <authorization_id>BEE129</authorization_id>
        <payment_account_reference>11CC24FA64200BD878BA8F4117971</payment_account_reference>
        <convenience_amount>100</convenience_amount>
        <convenience_indicator>01</convenience_indicator>
        <qr_data>0305A6008070845784312</qr_data>
      </transaction>
    </data>
  </transaction_history>
  <reconciliation_data>
    <custom_field>
      <name>Paymentid</name>
      <value>123</value>
    </custom_field>
    <custom_field>
      <name>tranid</name>
      <value>456</value>
    </custom_field>
    <custom_field>
      <name>reference</name>
      <value>789</value>
    </custom_field>
  </reconciliation_data>
  <channel>KIOSK</channel>
  <device_id>DEVICE-1234</device_id>
  <location>state:MO</location>
  <original_status>APPROVED</original_status>
  <status>APPROVED</status>
  <status_timestamp>2019-10-28T15:47:37-05:00</status_timestamp>
  <payment_origination_country>IND</payment_origination_country>
  <transaction_local_date_time>2017-09-22T13:22:11-05:30</transaction_local_date_time>
  <funding_source>CASH</funding_source>
  <mastercard_assigned_id>111111</mastercard_assigned_id>
  <participant>
    <card_acceptor_name>testmerchant</card_acceptor_name>
  </participant>
  <additional_message>0305A6008070845784312</additional_message>
  <participation_id>Imparticipating1</participation_id>
  <interchange_rate_designator>QR</interchange_rate_designator>
</merchant_transfer>
```