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

The Payment API creates an MPQR payment transfer (Payment Transaction) to send funds to the Receiving Institution holding the merchant account (recipient account).

For each payment transfer, generate a unique Transfer Reference ID (6-40 characters, alphanumeric and \* , - . _ \~ allowed) and provide it as the `transfer_reference` in the request. If the request is successful, the API response includes a unique system-generated Transfer ID (`id`).

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 transaction is declined, the API response is a 402 error with `"ReasonCode": "DECLINE"`. Error responses are also returned for API requests that fail Mastercard validation or transaction processing, for example, when a required field is missing or a value is incorrectly formatted; see [Error Codes](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/response-error-codes/index.md#error-codes).

## 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 section below shows 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/payment-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: Users of this documentation may find discrepancies in field lengths specified in the [EMVCo specification](https://www.emvco.com/specifications/emv-qr-code-specification-for-payment-systems-emv-qrcps-merchant-presented-mode/) and the Mastercard API specifications for QR fields. Please ensure that values passed in API fields conform to the Mastercard API specifications.

We updated the API specification from a Swagger 2.0 file 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/MerchantPayment_swagger_final.yaml`

<br />

To retrieve information about a payment request, use the [Retrieval API](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/api-reference/retrieval-api/index.md).

## 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. For valid test card numbers you can use in your requests, see [Test Card Numbers](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/test-card-numbers/index.md).

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

|                                      Test Scenario                                       |                                                                                 Request Test Data                                                                                 | HTTP Status / Reason Code |                  Result                  |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|------------------------------------------|
| Merchant Transfer Payment Approval                                                       | Provide [valid Recipient Account Number](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/test-card-numbers/index.md) and Amount \> 50 | 200 / APPROVED            | Merchant Payment Transaction is approved |
| Sender / Recipient Expiry Date with past date validation                                 | Provide Expiry date as past date for Sender / Recipient in Account URI, e.g. exp=2017-01                                                                                          | 400 / INVALID_INPUT_VALUE | Invalid value                            |
| Payment Decline during Transaction processing                                            | Provide Amount as 1 cents                                                                                                                                                         | 402 / DECLINE             | Card declined                            |
| Payment Decline by Network error during transaction processing                           | Provide Amount as 2 cents                                                                                                                                                         | 500 / SYSTEM_ERROR        | Internal exception occurred              |
| Slow response - Service will be delayed 30 seconds before returning approved transaction | Provide Amount as 3 cents                                                                                                                                                         | 200 / APPROVED            | Merchant Payment Transaction is approved |
| Payment Decline due to "Refer to Card Issuer" reason                                     | Provide Amount as 12 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment Decline due to "Lost Card" reason                                                | Provide Amount as 13 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment Decline due to "Stolen Card" reason                                              | Provide Amount as 14 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Insufficient Funds" reason                                       | Provide Amount as 15 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Invalid Issuer" reason                                           | Provide Amount as 16 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Invalid Transaction" reason                                      | Provide Amount as 17 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Invalid Amount" reason                                           | Provide Amount as 18 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Invalid Card Number"                                             | Provide Amount as 19 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Transactions not permitted on issuer"                            | Provide Amount as 20 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Duplicate Transaction"                                           | Provide Amount as 21 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Fraud Detected" reason                                           | Provide Amount as 49 cents                                                                                                                                                        | 402 / DECLINE             | Card declined                            |
| Payment decline due to "Card Expired" reason                                             | Provide Recipient Account Number 5008533529008683                                                                                                                                 | 402 / DECLINE             | Card expired                             |

## MTF Testing {#mtf-testing}

As MTF is a testing environment, it has specific functionality designed for testing as well as a smaller dataset to simulate certain transactions and responses.

The MTF environment simulates transaction responses based on the `amount` value passed in the API request, see below. Any card number may be used as long as it passes the basic card number validation, see [Test Card Numbers](https://developer.mastercard.com/mastercard-merchant-presented-qr/documentation/server-apis/test-card-numbers/index.md).

|                           Amount                           |                                  Simulated Response                                  |
|------------------------------------------------------------|--------------------------------------------------------------------------------------|
| Any amount except for the amounts listed in the rows below | Approved Transaction                                                                 |
| 1                                                          | Declined Transaction                                                                 |
| 2                                                          | Error returned during transaction processing                                         |
| 3                                                          | Service will be delayed 30 seconds before returning an approved transaction response |

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}

### Request {#request}

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

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

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

**Formats:** JSON / XML  

**HTTP Methods:** POST  

**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:**
* JSON
* XML

```JSON
{
  "merchant_payment_transfer": {
    "payment_type": "P2M",
    "amount": "120",
    "currency": "USD",
    "payment_origination_country": "IND",
    "sender_account_uri": "pan:5299920000000149;exp=2022-08;cvc=123",
    "transaction_local_date_time": "2017-09-22T13:22:11-05:30",
    "sender": {
      "first_name": "Fred",
      "middle_name": "Pete",
      "last_name": "Flinstone",
      "address": {
        "line1": "21Broadway",
        "line2": "ApartmentA-62",
        "city": "OFallon",
        "country_subdivision": "MO",
        "postal_code": "63368",
        "country": "USA"
      },
      "date_of_birth": "1994-05-21",
      "phone": "123456789",
      "email": "test123@abcmail.com"
    },
    "recipient_account_uri": "pan:5299920210000277;exp=2077-08;cvc=123",
    "recipient": {
      "merchant_category_code": "4829",
      "first_name": "Fred",
      "middle_name": "Pete",
      "last_name": "Flinstone",
      "address": {
        "line1": "1MainSt",
        "line2": "Apartment9",
        "city": "OFallon",
        "country_subdivision": "MO",
        "postal_code": "63368",
        "country": "USA"
      },
      "phone": "123456789",
      "email": "test123@abcmail.com"
    },
    "funding_source": "CASH",
    "reconciliation_data": {
      "custom_field": [
        {
          "name": "Paymentid",
          "value": "123"
        },
        {
          "name": "tranid",
          "value": "456"
        },
        {
          "name": "reference",
          "value": "789"
        }
      ]
    },
    "participant": {
      "card_acceptor_name": "testmerchant"
    },
    "mastercard_assigned_id": "111111",
    "channel": "KIOSK",
    "device_id": "DEVICE-1234",
    "location": "state:MO",
    "participation_id": "Imparticipating1",
    "additional_message": "0305A6008070845784312",
    "qr_data": "0305A6008070845784312",
    "convenience_amount": "100",
    "convenience_indicator": "01",
    "transfer_reference": "MPQR_157427542617121"
  }
}
```

```XML
<merchant_payment_transfer>
  <payment_type>P2M</payment_type>
  <amount>120</amount>
  <currency>USD</currency>
  <payment_origination_country>IND</payment_origination_country>
  <sender_account_uri>pan:5299920000000149;exp=2022-08;cvc=123</sender_account_uri>
  <transaction_local_date_time>2017-09-22T13:22:11-05:30</transaction_local_date_time>
  <sender>
    <first_name>Fred</first_name>
    <middle_name>Pete</middle_name>
    <last_name>Flinstone</last_name>
    <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>
    <date_of_birth>1994-05-21</date_of_birth>
    <phone>123456789</phone>
    <email>test123@abcmail.com</email>
  </sender>
  <recipient_account_uri>pan:5299920210000277;exp=2077-08;cvc=123</recipient_account_uri>
  <recipient>
    <merchant_category_code>4829</merchant_category_code>
    <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>
  </recipient>
  <funding_source>CASH</funding_source>
  <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>
  <participant>
    <card_acceptor_name>testmerchant</card_acceptor_name>
  </participant>
  <mastercard_assigned_id>111111</mastercard_assigned_id>
  <channel>KIOSK</channel>
  <device_id>DEVICE-1234</device_id>
  <location>state:MO</location>
  <participation_id>Imparticipating1</participation_id>
  <additional_message>0305A6008070845784312</additional_message>
  <qr_data>0305A6008070845784312</qr_data>
  <convenience_amount>100</convenience_amount>
  <convenience_indicator>01</convenience_indicator>
  <interchange_rate_designator>QR</interchange_rate_designator>
  <transfer_reference>MPQR_157229565564621</transfer_reference>
</merchant_payment_transfer>
```

### Response {#response}

**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:48-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:************9903",
    "transfer_amount": {
      "value": "120",
      "currency": "USD"
    },
    "convenience_amount": "100",
    "convenience_indicator": "01",
    "qr_data": "0305A6008070845784312",
    "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:48-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",
    "participation_id": "Imparticipating1"
  }
}
```

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