# Adjustment and Adjustment Search API
source: https://developer.mastercard.com/mastercard-send-funding/documentation/api-reference/adjustment/index.md

Note: This new API is in development and has been made available to special early adopters. **This API functionality is subject to change.** We will try to keep this API specification and information up to date. If you notice differences from API behavior, please ask your Mastercard contact for guidance.

Unless you have been asked to try this API, please do **not** start coding for it.

Currently, information specific to this API is only present on this page; we have not adjusted the other pages for it. The documentation set will be updated fully when the API is launched.

### Adjustment {#adjustment}

The Adjustment API creates an adjustment (refund) of an approved funding transfer (Funding Transaction), for example when you need to refund the Sender. The adjustment must be requested within 180 days of the Funding Transaction. You can request adjustments for Funding Transactions created by the [Funding API](https://developer.mastercard.com/mastercard-send-funding/documentation/api-reference/index.md).

For each adjustment request, generate a unique Adjustment Reference ID (6-40 characters, alphanumeric and \* , - . _ \~ allowed) and provide it as the `adjustmentReference` in the POST request. Identify the funding transfer by providing one of these values:

* The Transfer Reference (`transfer_reference`) you provided when you created the transfer
* The system-generated Transfer ID (`id`) that was returned when you created the transfer

If the request is successful, the API response (HTTP 201) includes a unique system-generated Adjustment ID (`adjustmentId`). The status (`transactionStatus`) will indicate whether the adjustment was approved:

* 'APPROVED' = The adjustment is approved. The funding transfer's `status` changes to 'REVERSED'.
* 'DECLINED' = The adjustment is declined. The funding transfer's `status` remains 'APPROVED'.
* 'PENDING' = Similar to the Funding API's 'UNKNOWN' status, see the guidance for [Transaction Responses with an 'UNKNOWN' Status](https://developer.mastercard.com/mastercard-send-funding/documentation/response-error-codes/unknown-response/index.md).

Error responses are returned for API requests that fail Mastercard Send 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-send-funding/documentation/api-reference/adjustment/index.md#error-codes).

### Adjustment Search {#adjustment-search}

The Adjustment Search API retrieves details of an adjustment, including its latest status, by searching for its `adjustmentReference` or `adjustmentId`. Wait at least five seconds after creating the adjustment, otherwise your Search POST call might receive an error. The Search call is useful when a transaction is pending or declined and you need further details for troubleshooting or research purposes. You do not need to use it for approved transactions.

## Environment Domains {#environment-domains}

* Sandbox
* MTF
* Production

```Sandbox
https://sandbox.api.mastercard.com/send/partners
```

```MTF
https://mtf.api.mastercard.com/send/partners
```

```Production
https://api.mastercard.com/send/partners
```

To form the full endpoint URL, combine the appropriate domain portion (shown above) with the path portion shown by the OpenAPI specification (see below).

## APIs {#apis}

This API supports JSON requests. In the expandable sections below, JSON example requests and responses are shown. 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 `partner_id` portion of the URL makes the request unique to a specific Originating Institution or Transaction Initiator:

* Sandbox API: Use any ID of valid length (32-40 characters), e.g. `ptnr_BEeCrYJHh2BXTXPy_PEtp-8DBOo`
* MTF and Production APIs: Use the Partner Reference ID you receive when you [register for the Mastercard Send program](https://developer.mastercard.com/mastercard-send/documentation/send-eligibility/)

Note: The `adjustmentReference` value must be unique for each API request to create a transaction, so you must adjust that value for **every** Adjustment call. Otherwise you may get a 409 'Duplicate value' error response.  
The Sandbox server validation detects previously used values, including the default value in the expandable **Adjustment** section below, so we recommend you change it to a random value before clicking **Execute**.

For guidance on the API specification's **Execute** buttons, see [Testing](https://developer.mastercard.com/mastercard-send-funding/documentation/api-reference/adjustment/index.md#testing).
Tip: Guidance for the API sections below:
The expandable API sections below are rendered from the API specification, which you can download using **Download spec**.

Each API call type is a section. Expand it to see the request parameters and example JSON body payload and/or example response for that call. There may be multiple examples, which may not show all possible fields. If so, select **All fields** to see the possible fields:

![](https://static.developer.mastercard.com/content/mastercard-send-funding/documentation/api-reference/img/example-selection.png)

To see the field descriptions, click **Model** and expand the object/array blocks to show their contents.

**Request URI** shows the call's endpoint path based on the selected environment (for example, Sandbox URL).

You can edit the example payload. Switching to the Model view will reset the payload to the default example.
The API specification identifies the required (mandatory) API fields as per Mastercard Send API validation and systems. In the expandable sections below, these fields are indicated as follows:

* REQUIRED indicates a required parameter, for example:

![](https://static.developer.mastercard.com/content/mastercard-send-funding/documentation/api-reference/img/required-param.png)

* In the **Model** section, a red asterisk \* indicates a required object/array and **required: yes** indicates a required item, for example:

![](https://static.developer.mastercard.com/content/mastercard-send-funding/documentation/api-reference/img/required-item.png)

If an item is marked as required but its parent object/array is not, you only need to provide that item if you provide the parent.

The required indicator relates to general API validation. Some conditional fields might be required depending on the payment type, region, and so on. Some of the other optional fields might also be required as per program or network rules.

API Specification: `https://static.developer.mastercard.com/content/mastercard-send-funding/swagger/send-adjustment-api-swagger.yaml`

## Testing {#testing}

To try this API quickly, use the **Execute** buttons (in the expandable sections above) to send requests directly from your browser to the Sandbox, without needing to create a Mastercard Developers project and keys. This functionality will send the shown Request parameters and Body payload, which you can alter, and the response will appear in a **Server Response** tab.

You can also make API calls to the Sandbox server from an API tool or your application code or the [tutorials](https://developer.mastercard.com/mastercard-send-funding/documentation/tutorials-and-guides/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required OAuth 1.0a Authorization Header.

The Sandbox server returns simulated responses.

For Sandbox and MTF testing guidance, please ask your Mastercard contact. (We will add that information to this documentation set for API launch.)

## Error Codes {#error-codes}

If your API request is unsuccessful, you should receive a service error response or a [gateway error response](https://developer.mastercard.com/mastercard-send-funding/documentation/response-error-codes/error-codes/index.md#gateway-error-codes).

Note that the service error response messages (4xx status code) for this API have a slightly different structure from the Funding API error response. An example error message is shown below. The `Error` array may contain multiple error items.
* JSON

```JSON
{
  "Errors": {
    "Error": [
      {
        "Source": "RESOURCE_UNKNOWN",
        "ReasonCode": "RESOURCE_ERROR",
        "Description": "Record not found",
        "Recoverable": false,
        "ErrorDetailCode": "110507",
        "Details": null
      }
    ]
  }
}
```

For error message guidance, please ask your Mastercard contact. (We will add that information to this documentation set for API launch.)