# 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


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>
```