# Amend API
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/amend-api/index.md

The Amend API allows Cross-Border Services customers to request amendments to a transaction's receiver details. You can update the receiver's name, address, or phone number using either the Transaction ID or Transaction Reference.

This API is **optional** and available only to Cross-Border Services customers who have opted in for the **Payment API** . Customers can use the amend API to correct receiver information before the transaction is paid or cancelled.  

When an amend request is processed, the system first freezes cash pickup. If the cash pickup freeze is successful, the system confirms that the amend request is accepted. If the amend request includes an update to the receiver's name, the updated name is sent for compliance screening. If the compliance screening fails, the payment is rejected.
Note: Amend is supported only for cash pickup payments.

## Environment Domains {#environment-domains}

* Sandbox/MTF
* Production

```Sandbox/MTF
https://sandbox.api.mastercard.com/send/v1/partners/{partner_id}/crossborder/amends
```

```Production
https://api.mastercard.com/send/v1/partners/{partner_id}/crossborder/amends
```

Note: **Sandbox** and **MTF** environments share the same url but are differentiated by partner id.

## API {#api}

[**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-swagger.yaml)

### Amend API {#amend-api}


API Reference: `GET /send/v1/partners/{partner_id}/crossborder/amends`

* **Formats supported** : XML/ JSON   
* **HTTP Version**: 1.0/ 1.1
* **Required HTTP header parameters** :   
  content-type : Format of the inbound content being submitted. example: application/json   
  content-length: Length of the inbound content body in octets.   
  Accept: Format of the expected response must be provided in this header field. Example - application/json

## API Convention {#api-convention}

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

## Payload Encryption {#payload-encryption}

All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by  
Mastercard.   

For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md)

## Sandbox Testing {#sandbox-testing}

You can make API calls to the Sandbox server from your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required Authorization Header.
Tip: During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production). This partner ID will not be able to access the sandbox environment, but the customer can still access sandbox by using the non-registered partner ID.  
Any correctly formatted partner ID can be used in the sandbox. As a best practice, use the first 15 digits of your institution's name (alphanumeric and/or special characters, no spaces) as the Partner_ID.   
For testing in sandbox, please use unique transaction_reference on each run. Note: The sandbox does not return parameters unique to a specific Customer; such as pricing, limits, and corridor-specific data requirements, but allows you to test general call structure and responses outside of the production environment. After sandbox testing is completed, Customers meeting the eligibility requirements will be assigned a project manager to do integrated testing in the test environment that has been configured to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the Customer.

|  Status  |                                   Test Case                                   |                                                                                                                                                                                   Action / Error Details                                                                                                                                                                                    |
|----------|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Success  | Amend payment response is "Success" indicating the request was accepted.      | Send an amend request providing the Transaction Reference or Transaction Id, an amend request reference, and the details to be updated for a payment (for example, receiver's name, receiver address, receiver phone numbers). **Note:** The amend request must include either a transaction reference or transaction Id. If both are provided, the transaction reference takes precedence. |
| Rejected | Amend payment request without transaction reference or transaction Id.        | Send an amend request without Transaction Reference or Transaction Id. Returns message **"Transaction reference is mandatory"** with error code **092001**.                                                                                                                                                                                                                                 |
| Rejected | Amend payment request without amendment reference.                            | Send an amend request without providing an amendment reference. Returns message **"Amend reference is mandatory"** with error code **092002**.                                                                                                                                                                                                                                              |
| Rejected | Amend payment request has an invalid transaction reference or transaction Id. | Send an amend request with an invalid transaction reference or transaction Id. Returns message **"Invalid Input Value"** with error code **082000** . **Note:** If both transaction reference and transaction Id are provided and the transaction reference is valid (but transaction Id is invalid), the request will not be rejected.                                                     |
| Rejected | Amend payment request is received for a successful payment.                   | Send an amend request for a payment with status *successful* . Returns message **"Payment is processed"** with error code **082003**.                                                                                                                                                                                                                                                       |
| Rejected | Amend payment request is received for a rejected payment.                     | Send an amend request for a payment with status *rejected* . Returns message **"Payment is rejected"** with error code **082002**.                                                                                                                                                                                                                                                          |
| Rejected | Amend payment request is received for a non-cash pickup payment.              | Send an amend request for a non--cash pickup payment in progress. Returns message **"Amend is allowed only for cash pickup payment"** with error code **140002**.                                                                                                                                                                                                                           |
| Rejected | Amend request is received with unexpected or unsupported parameters.          | If the amend request contains parameters outside the allowed specification, it is rejected. Returns message **"Invalid Input Value"** with error code **082000**.                                                                                                                                                                                                                           |

## Sample Requests {#sample-requests}

### Sample reference payment request {#sample-reference-payment-request}

* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<paymentrequest>
    <transaction_reference>06{% uuid 'v4' %}</transaction_reference>
    <sender_account_uri>tel:+254167419</sender_account_uri>
    <recipient_account_uri>ewallet:nate.diaz;sp=rsptf</recipient_account_uri>
    <payment_amount>
        <amount>10.00</amount>
        <currency>USD</currency>
    </payment_amount>
    <forward>
        <receiver_currency>JMD</receiver_currency>
        <fees_included>true</fees_included>
    </forward>
    <payment_origination_country>MEX</payment_origination_country>
    <payment_type>P2P</payment_type>
    <sender>
        <first_name>Gabriel</first_name>
        <middle_name>J</middle_name>
        <last_name>Tom</last_name>
        <nationality>GBR</nationality>
        <address>
            <line1>123MainStreet</line1>
            <line2>5A</line2>
            <city>Arlington</city>
            <country_subdivision>Texas</country_subdivision>
            <postal_code>12345</postal_code>
            <country>GBR</country>
        </address>
        <date_of_birth>1980-01-20</date_of_birth>
        <phone>8801700111224</phone>
    </sender>
    <recipient>
        <first_name>Johnn</first_name>
        <middle_name>X</middle_name>
        <last_name>Merriman</last_name>
        <nationality>GBR</nationality>
        <address>
            <line1>1001 E</line1>
            <line2>Parmer Lane Suite B</line2>
            <city>Austin</city>
            <country_subdivision>Texas</country_subdivision>
            <postal_code>12</postal_code>
            <country>USA</country>
        </address>
        john.x.m@gmail.com
    </recipient>
    <additional_data>
        <data_field>
            <name>701</name>
            <value>JAM</value>
        </data_field>
        <data_field>
            <name>208</name>
            <value>JXM</value>
        </data_field>
        <data_field>
            <name>209</name>
            <value>Thomas</value>
        </data_field>
        <data_field>
            <name>221</name>
            <value>1234567890123</value>
        </data_field>
        <data_field>
            <name>222</name>
            <value>87766554465</value>
        </data_field>
        <data_field>
            <name>223</name>
            <value>44557766776</value>
        </data_field>
    </additional_data>
</paymentrequest>
```

```json
{
  "paymentrequest": {
    "transaction_reference": "068b8d46f2-5b30-4097-9485-2cc617b4e824",
    "sender_account_uri": "tel:+254167419",
    "recipient_account_uri": "ewallet:nate.diaz;sp=rsptf",
    "payment_amount": {
      "amount": "10.00",
      "currency": "USD"
    },
    "forward": {
      "receiver_currency": "JMD",
      "fees_included": "true"
    },
    "payment_origination_country": "MEX",
    "payment_type": "P2P",
    "sender": {
      "first_name": "Gabriel",
      "middle_name": "J",
      "last_name": "Tom",
      "nationality": "GBR",
      "address": {
        "line1": "123MainStreet",
        "line2": "5A",
        "city": "Arlington",
        "country_subdivision": "Texas",
        "postal_code": "12345",
        "country": "GBR"
      },
      "date_of_birth": "1980-01-20",
      "phone": "8801700111224"
    },
    "recipient": {
      "first_name": "Johnn",
      "middle_name": "X",
      "last_name": "Merriman",
      "nationality": "GBR",
      "address": {
        "line1": "1001 E",
        "line2": "Parmer Lane Suite B",
        "city": "Austin",
        "country_subdivision": "Texas",
        "postal_code": "12",
        "country": "USA"
      },
      "email": "john.x.m@gmail.com"
    },
    "additional_data": {
      "data_field": [
        {
          "name": "701",
          "value": "JAM"
        },
        {
          "name": "208",
          "value": "JXM"
        },
        {
          "name": "209",
          "value": "Thomas"
        },
        {
          "name": "221",
          "value": "1234567890123"
        },
        {
          "name": "222",
          "value": "87766554465"
        },
        {
          "name": "223",
          "value": "44557766776"
        }
      ]
    }
  }
}
```

### ++Request amend using Transaction Reference++ {#urequest-amend-using-transaction-referenceu}

* Xml
* Json

```xml
<AmendPayment>
	<transaction_reference>0635ebbc35-7d60-41be-939e-ad52d7d62be1</transaction_reference>
	<amend_reference>AmendTransRef</amend_reference>
	<recipient>
		<first_name>Jon</first_name>
		<middle_name>D</middle_name>
		<last_name>Merrimen</last_name>
		<address>
			<line1>House 8</line1>
			<line2>Brown Lane</line2>
			<city>Dallas</city>
			<country_subdivision>Texas</country_subdivision>
			<postal_code>112233</postal_code>
		</address>
		<phone>78654723456</phone>
	</recipient>
	<additional_data>
		<data_field>
			<name>208</name>
			<value>JonAlias</value>
		</data_field>
		<data_field>
			<name>209</name>
			<value>Tom</value>
		</data_field>
		<data_field>
			<name>222</name>
			<value>65454723456</value>
		</data_field>
		<data_field>
			<name>223</name>
			<value>68564723456</value>
		</data_field>
	</additional_data>
</AmendPayment>
```

```json
{
  "AmendPayment": {
    "transaction_reference": "0635ebbc35-7d60-41be-939e-ad52d7d62be1",
    "amend_reference": "AmendTransRef",
    "recipient": {
      "first_name": "Jon",
      "middle_name": "D",
      "last_name": "Merrimen",
      "address": {
        "line1": "House 8",
        "line2": "Brown Lane",
        "city": "Dallas",
        "country_subdivision": "Texas",
        "postal_code": "112233"
      },
      "phone": "78654723456"
    },
    "additional_data": {
      "data_field": [
        {
          "name": "208",
          "value": "JonAlias"
        },
        {
          "name": "209",
          "value": "Tom"
        },
        {
          "name": "222",
          "value": "65454723456"
        },
        {
          "name": "223",
          "value": "68564723456"
        }
      ]
    }
  }
}
```

### ++Request amend using Transaction Id++ {#urequest-amend-using-transaction-idu}

* Xml
* Json

```xml
<AmendPayment>
	<remit_reference>rem_tto6BUAcku88CK21zvNYePRUw1o</remit_reference>
	<amend_reference>AmendTransRef</amend_reference>
	<recipient>
		<first_name>Jon</first_name>
		<middle_name>D</middle_name>
		<last_name>Merrimen</last_name>
		<address>
			<line1>House 8</line1>
			<line2>Brown Lane</line2>
			<city>Dallas</city>
			<country_subdivision>Texas</country_subdivision>
			<postal_code>112233</postal_code>
		</address>
		<phone>78654723456</phone>
	</recipient>
	<additional_data>
		<data_field>
			<name>208</name>
			<value>JonAlias</value>
		</data_field>
		<data_field>
			<name>209</name>
			<value>Tom</value>
		</data_field>
		<data_field>
			<name>222</name>
			<value>65454723456</value>
		</data_field>
		<data_field>
			<name>223</name>
			<value>68564723456</value>
		</data_field>
	</additional_data>
</AmendPayment>
```

```json
{
  "AmendPayment": {
    "remit_reference": "rem_tto6BUAcku88CK21zvNYePRUw1o",
    "amend_reference": "AmendTransRef",
    "recipient": {
      "first_name": "Jon",
      "middle_name": "D",
      "last_name": "Merrimen",
      "address": {
        "line1": "House 8",
        "line2": "Brown Lane",
        "city": "Dallas",
        "country_subdivision": "Texas",
        "postal_code": "112233"
      },
      "phone": "78654723456"
    },
    "additional_data": {
      "data_field": [
        {
          "name": "208",
          "value": "JonAlias"
        },
        {
          "name": "209",
          "value": "Tom"
        },
        {
          "name": "222",
          "value": "65454723456"
        },
        {
          "name": "223",
          "value": "68564723456"
        }
      ]
    }
  }
}
```

## Sample Responses {#sample-responses}

The response fields would be same regardless if it's a payment with quote or payment with carded rate or payment without quote/ carded rate.

### Successful Amend: {#successful-amend}

A successful response indicates that the amend request has been accepted.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<AmendPaymentBody>
    <amend_reference>AmendUsingTRef</amend_reference>
    <transaction_reference>068b8d46f2-5b30-4097-9485-2cc617b4e824</transaction_reference>
    <remit_reference>rem_lPaedW15a6eRfcNiTfDuujY8LXQ</remit_reference>
    <status>SUCCESS</status>
    <status_timestamp>2026-02-16T09:32:27-06:00</status_timestamp>
</AmendPaymentBody>
```

```json
{
	"AmendPaymentBody": {
		"amend_reference": "AmendUsingTRef",
		"transaction_reference": "068b8d46f2-5b30-4097-9485-2cc617b4e824",
		"remit_reference": "rem_lPaedW15a6eRfcNiTfDuujY8LXQ",
		"status": "SUCCESS",
		"status_timestamp": "2026-02-16T09:32:27-06:00"
	}
}
```

### Rejected Amend: {#rejected-amend}

1. Rejected response for an amend request without transaction reference or transaction Id.
* Xml
* Json

```xml
<Errors>
<Error>
<RequestId>347158586</RequestId>
<Source>transaction_reference</Source>
<ReasonCode>MISSING_REQUIRED_INPUT</ReasonCode>
<Description>Transaction reference is mandatory</Description>
<Recoverable>false</Recoverable>
<Details>
<Detail>
<Name>ErrorDetailCode</Name>
<Value>092001</Value>
</Detail>
</Details>
</Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347158586",
			"Source": "transaction_reference",
			"ReasonCode": "MISSING_REQUIRED_INPUT",
			"Description": "Transaction reference is mandatory",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "092001"
				}
			}
		}
	}
}
```

2. Rejected response for an amend request without amend reference.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347158716</RequestId>
    <Source>amend_reference</Source>
    <ReasonCode>MISSING_REQUIRED_INPUT</ReasonCode>
    <Description>Amend reference is mandatory</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>092002</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347158716",
			"Source": "amend_reference",
			"ReasonCode": "MISSING_REQUIRED_INPUT",
			"Description": "Amend reference is mandatory",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "092002"
				}
			}
		}
	}
}
```

3(a). Rejected response for an amend request with an invalid Transaction reference.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347156724</RequestId>
    <Source>transaction_reference</Source>
    <ReasonCode>INVALID_INPUT_VALUE</ReasonCode>
    <Description>Invalid Input Value</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082000</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347156724",
			"Source": "transaction_reference",
			"ReasonCode": "INVALID_INPUT_VALUE",
			"Description": "Invalid Input Value",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082000"
				}
			}
		}
	}
}
```

3(b). Rejected response for an amend request with an invalid Transaction Id.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347158916</RequestId>
    <Source>remit_reference</Source>
    <ReasonCode>INVALID_INPUT_VALUE</ReasonCode>
    <Description>Invalid Input Value</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082000</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347158916",
			"Source": "remit_reference",
			"ReasonCode": "INVALID_INPUT_VALUE",
			"Description": "Invalid Input Value",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082000"
				}
			}
		}
	}
}
```

4. Rejected response for an amend request for a successful payment.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347919260</RequestId>
    <Source>transaction_reference</Source>
    <ReasonCode>TRANSACTION_PROCESSED</ReasonCode>
    <Description>Payment is processed</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082003</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347919260",
			"Source": "transaction_reference",
			"ReasonCode": "TRANSACTION_PROCESSED",
			"Description": "Payment is processed",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082003"
				}
			}
		}
	}
}
```

5. Rejected response for an amend request for a rejected payment.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347919786</RequestId>
    <Source>transaction_reference</Source>
    <ReasonCode>TRANSACTION_REJECTED</ReasonCode>
    <Description>Payment is rejected</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082002</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347919786",
			"Source": "transaction_reference",
			"ReasonCode": "TRANSACTION_REJECTED",
			"Description": "Payment is rejected",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082002"
				}
			}
		}
	}
}
```

6. Rejected response for an amend request for a non-cash pickup payment.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347890234</RequestId>
    <Source></Source>
    <ReasonCode>AMEND_NOT_SUPPORTED_FOR_DPI</ReasonCode>
    <Description>Amend is allowed only for cash pickup payment</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>140002</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347890234",
			"Source": "",
			"ReasonCode": "AMEND_NOT_SUPPORTED_FOR_DPI",
			"Description": "Amend is allowed only for cash pickup payment",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "140002"
				}
			}
		}
	}
}
```

7. Rejected response for an amend request with the receiver's details not aligned with the allowed formats.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>369452044</RequestId>
    <Source>recipient.first_name</Source>
    <ReasonCode>INVALID_INPUT_VALUE</ReasonCode>
    <Description>Invalid Input Value</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082000</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "369452044",
			"Source": "recipient.first_name",
			"ReasonCode": "INVALID_INPUT_VALUE",
			"Description": "Invalid Input Value",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082000"
				}
			}
		}
	}
}
```

8. Rejected response for an amend request with receiver's name which varies from the current name of the receiver beyond an allowed variance.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347203858</RequestId>
    <Source></Source>
    <ReasonCode>BEYOND_VARIANCE</ReasonCode>
    <Description>Name is beyond allowed variance</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082009</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347203858",
			"Source": "",
			"ReasonCode": "BEYOND_VARIANCE",
			"Description": "Name is beyond allowed variance",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082009"
				}
			}
		}
	}
}
```

9. Rejected response for an amend request with unexpected details apart from the allowed details as per the specifications.
* Xml
* Json

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Errors>
  <Error>
    <RequestId>347154212</RequestId>
    <Source>data_field.name:767</Source>
    <ReasonCode>INVALID_INPUT_VALUE</ReasonCode>
    <Description>Invalid Input Value</Description>
    <Recoverable>false</Recoverable>
    <Details>
      <Detail>
        <Name>ErrorDetailCode</Name>
        <Value>082000</Value>
      </Detail>
    </Details>
  </Error>
</Errors>
```

```json
{
	"Errors": {
		"Error": {
			"RequestId": "347154212",
			"Source": "data_field.name:767",
			"ReasonCode": "INVALID_INPUT_VALUE",
			"Description": "Invalid Input Value",
			"Recoverable": "false",
			"Details": {
				"Detail": {
					"Name": "ErrorDetailCode",
					"Value": "082000"
				}
			}
		}
	}
}
```

## Error Codes {#error-codes}

Refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md).

For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md).