# Return Messages
source: https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/return-message/index.md

Return messages will be provided via Status Change reporting (File or API based) and via Retrieve Payment APIs when a transaction is returned.
The values provide an explanation of the reason the transaction is being returned.

## Return Messages Version 2 {#return-messages-version-2}

<br />

The following table contains the list of return messages for Version 2.

|    |      Return Message For Refund Return Reason Version 2       |
|----|--------------------------------------------------------------|
| 1  | Returned per sending service provider's request              |
| 2  | Beneficiary account is not valid or unable to locate account |
| 3  | Beneficiary account is inactive                              |
| 4  | Beneficiary name does not match account                      |
| 5  | Invalid account type                                         |
| 6  | Credit refused by beneficiary                                |
| 7  | Unspecified reason                                           |
| 8  | Beneficiary account is not authorized to receive deposits    |
| 9  | Beneficiary account currency does not match payout currency  |
| 10 | Beneficiary account is frozen​​​​​​                          |

* [Sample response](https://developer.mastercard.com/cross-border-services/documentation/api-ref/sample-responses-retrieve-payment-api/index.md) of Retrieve Payment API (Example #5)

* [Sample notification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/sample-requests-status-change-api/index.md) of Status Change Push (Example #3)

When a local network does not provide a clear return reason, "Unspecified reason" will be provided in the Return Message.
Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines.

<br />

## Return Messages Version 3 {#return-messages-version-3}

<br />

Return Version 3 (V3) allows Mastercard to provide 1 of 53 different Return Messages compared to the 10 Return Messages available in Version 2. For a complete list of Return Version 3 (V3) messages, please refer to the
[Error And Return Message Codes Information](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/error-codes/index.md) export filtered with a checkmark on column "J"

When a local network does not provide a clear return reason, Code "150006 "and description "System Error" will be provided.

* [Sample response](https://developer.mastercard.com/cross-border-services/documentation/api-ref/sample-responses-retrieve-payment-api/index.md) of Retrieve Payment API (Example #6)

* [Sample notification](https://developer.mastercard.com/cross-border-services/documentation/api-ref/sample-requests-status-change-api/index.md) of Status Change Push (Example #4)

#### Member Test Facility (MTF) Testing for Return Message Version 3 {#member-test-facility-mtf-testing-for-return-message-version-3}

For a complete list of the Return Version 3 (V3) MTF test cases, please refer to tab 2, "Return V3 Test Scenarios" on the [Error And Return Message Codes Information](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/error-codes/index.md) export. Columns "D" through "H" list the Recipient URI and the additional data field, that must be provided to test Returns for the following receive channels: IBAN, BAN, Card, Tel, and E-Wallet.
Please refer to the below table on how to format the Return V3 test cases for each channel:

|                                    Test Case                                    |                                                                                                                                                                                                                                 Action/Response                                                                                                                                                                                                                                  |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| "P2P" Payment with "iban" recipient uri is returned with specific error code    | 1. Send a Payment where recipient currency is USD and Recipient account uri as iban:BR9700360305000010009795493P1. Also, provide additional data field name '999' and value in format '226NNNNNN', where NNNNNN is desired error code. For example: "additional_data": \[ { "name": "999", "value": "226130105" }, will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105 |
| "P2P" Payment with "ban" recipient uri is returned with specific error code     | 1. Send a Payment where recipient currency is USD and Recipient account uri in format ban:1000000226NNNNNN;bic=SIMXXX, where NNNNNN is desired error code. For example: Recipient uri ban:1000000226130105;bic=SIMXXX, will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105                                                                                             |
| "P2P" Payment with "ewallet" recipient uri is returned with specific error code | 1. Send a Payment where recipient currency is USD and Recipient account uri in format ewallet: EW226NNNNNN;sp=sim, where NNNNNN is desired error code. For example: Recipient uri ewallet: EW226130105;sp=sim , will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105                                                                                                    |
| "P2P" Payment with "tel" recipient uri is returned with specific error code     | 1. Send a Payment where recipient currency is USD and Recipient account uri in format tel:+999226NNNNNN, where NNNNNN is desired error code. For example: Recipient uri tel:+999226130105 , will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105                                                                                                                        |
| "P2P" Payment with "pan" recipient uri is returned with specific error code     | 1. Send a Payment where recipient currency is USD and Recipient account uri as pan:5186002600000013. Also, provide additional data field name '999' and value in format '226NNNNNN', where NNNNNN is desired error code. For example: "additional_data": \[ { "name": "999", "value": "226130105" }, will return the payment with return message 130105 2. System would mark the payment successful initially and after 26 hrs return the payment with code 130105               |

<br />

**Note** : The above test case outcomes can also be tested in the Sandbox environment. Please refer to [Retrieve Payment For Return Reason Message Version 3](https://developer.mastercard.com/cross-border-services/documentation/api-ref/retrieve-payment-api/index.md#sandbox-test-cases) to see Sandbox test case formatting.

**Sample "P2P" payment requests:**

**Recipient URI 'iban':**

```JSON
{
  "paymentrequest": {
    "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207686",
    "sender_account_uri": "tel:+254108989",
    "recipient_account_uri": "iban:BR9700360305000010009795493P1",
    "payment_amount": {
      "amount": "11.50",
      "currency": "USD"
    },
    "payment_origination_country": "USA",
    "bank_code": "NP021",
    "payment_type": "P2P",
    "sender": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "USA"
      },
      "date_of_birth": "1980-01-20"
    },
    "recipient": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "CAN"
      }
    },
    "fx_type": {
      "forward": {
        "fees_included": "true",
        "receiver_currency": "USD"
      }
    },
    "additional_data": {
      "data_field": [
        {
          "name": "701",
          "value": "USA"
        },
        {
          "name": "999",
          "value": "226130105"
        }
      ]
    }
  }
}
```

**Recipient URI 'ban':**

```JSON
{
  "paymentrequest": {
    "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207696",
    "sender_account_uri": "tel:+254108989",
    "recipient_account_uri": "ban:1000000226130105;bic=SIMXXX",
    "payment_amount": {
      "amount": "12.50",
      "currency": "USD"
    },
    "payment_origination_country": "USA",
    "bank_code": "NP021",
    "payment_type": "P2P",
    "sender": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "USA"
      },
      "date_of_birth": "1980-01-20"
    },
    "recipient": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "CAN"
      }
    },
    "fx_type": {
      "forward": {
        "fees_included": "true",
        "receiver_currency": "USD"
      }
    },
    "additional_data": {
      "data_field": [
        {
          "name": "701",
          "value": "USA"
        }
      ]
    }
  }
}
```

**Recipient URI 'ewallet':**

```JSON
{
  "paymentrequest": {
    "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207606",
    "sender_account_uri": "tel:+254108989",
    "recipient_account_uri": "ewallet:EW226130113;sp=sim",
    "payment_amount": {
      "amount": "13.50",
      "currency": "USD"
    },
    "payment_origination_country": "USA",
    "bank_code": "NP021",
    "payment_type": "P2P",
    "sender": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "USA"
      },
      "date_of_birth": "1980-01-20"
    },
    "recipient": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "CAN"
      }
    },
    "fx_type": {
      "forward": {
        "fees_included": "true",
        "receiver_currency": "USD"
      }
    },
    "additional_data": {
      "data_field": [
        {
          "name": "701",
          "value": "USA"
        },
        {
          "name": "1200",
          "value": "test"
        }
      ]
    }
  }
}
```

**Recipient URI 'tel':**

```JSON
{
  "paymentrequest": {
    "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207676",
    "sender_account_uri": "tel:+254108989",
    "recipient_account_uri": "tel:+999226130105",
    "payment_amount": {
      "amount": "13.50",
      "currency": "USD"
    },
    "payment_origination_country": "USA",
    "bank_code": "NP021",
    "payment_type": "P2P",
    "sender": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "USA"
      },
      "date_of_birth": "1980-01-20"
    },
    "recipient": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "CAN"
      }
    },
    "fx_type": {
      "forward": {
        "fees_included": "true",
        "receiver_currency": "USD"
      }
    },
    "additional_data": {
      "data_field": [
        {
          "name": "701",
          "value": "USA"
        },
        {
          "name": "1200",
          "value": "test"
        }
      ]
    }
  }
}
```

**Recipient URI 'pan':**

```JSON
{
  "paymentrequest": {
    "transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207686",
    "sender_account_uri": "tel:+254108989",
    "recipient_account_uri": "pan:5186002600000013",
    "payment_amount": {
      "amount": "11.50",
      "currency": "USD"
    },
    "payment_origination_country": "USA",
    "bank_code": "NP021",
    "payment_type": "P2P",
    "sender": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "USA"
      },
      "date_of_birth": "1980-01-20"
    },
    "recipient": {
      "first_name": "John",
      "middle_name": "L",
      "last_name": "Doe",
      "nationality": "USA",
      "address": {
        "line1": "123MainStreet",
        "line2": "#5A",
        "city": "Arlington",
        "country_subdivision": "NA",
        "postal_code": "12345",
        "country": "CAN"
      }
    },
    "fx_type": {
      "forward": {
        "fees_included": "true",
        "receiver_currency": "USD"
      }
    },
    "additional_data":{
      "data_field": [
        {
          "name": "701",
          "value": "USA"
        },
        {
          "name": "999",
          "value": "226130105"
        }
      ]
    }
  }
}
```

Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines.

<br />