# Testing
source: https://developer.mastercard.com/agent-suite-for-merchants/documentation/testing/index.md

👉 Replace the mock test scenarios, endpoints, payloads, and expected results on this page with the real validation cases your consumers should run in Sandbox. Keep the overall positive and negative testing structure if it fits your service.

Use this page to plan and execute Sandbox validation for the {Your Service Name} API. It covers the recommended workflow, positive and negative coverage, and the reference guides you need for endpoint-level execution.
Tip: Start all validation in Sandbox before moving to Production.

### Choose a testing method {#choose-a-testing-method}

Choose a testing method that best matches how you want to validate requests:

* [Postman Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/postman-collection/index.md) --- pre-built requests with authentication and encryption configured.
* [Insomnia Collection](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/insomnia-collection/index.md) --- an alternative API client with a ready-to-use workspace.
* [Reference Application](https://developer.mastercard.com/agent-suite-for-merchants/documentation/developer-tools/reference-app/index.md) --- a working implementation you can run and inspect.
* Custom API client generated as per guidance in [API Basics](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-basics/index.md#how-to-consume-the-api).

### Recommended testing workflow {#recommended-testing-workflow}

Use this sequence to validate the main endpoint families with a realistic flow:

1. Create a primary resource.
2. Retrieve or search for that resource.
3. Create a downstream transaction.
4. Complete the follow-up transaction action.
5. Create or update an administrative record.
6. Delete a test resource.

This flow gives you coverage across create, read, update, delete, search, authentication, and encryption behavior.

## Positive testing {#positive-testing}

Positive testing confirms that valid requests succeed and return the expected data.

### Validate these behaviors {#validate-these-behaviors}

* Valid request bodies return success codes such as `200 OK`, `201 Created`, or `204 No Content`.
* Created resources can be retrieved by ID or found through search.
* Updates persist and can be verified with a follow-up GET.
* Search and filter parameters return the expected subset of records.
* Encrypted endpoints accept correctly signed and encrypted payloads.

### Positive test cases {#positive-test-cases}

Use the tabs below to view representative positive test cases for each endpoint family.
`POST /resource-b`

```json
{
  "name": "Example Resource",
  "type": "SECONDARY",
  "category": "STANDARD",
  "status": {
    "value": "ACTIVE"
  }
}
```

Expected result: `200 OK` and a response body containing a generated identifier.

Additional checks:

* `GET /resource-b/{resource_id}` returns `200 OK` and an `ETag` header.
* `PUT /resource-b/{resource_id}` with `If-Match: 0` returns `204 No Content`.
* `GET /resources?status=ACTIVE&limit=25&offset=0&sort=%2B` returns a paginated list.
`POST /transactions`

```json
{
  "resourceId": "12345678-1234-1234-1234-123456789abc",
  "transactionDate": "2026-04-07",
  "owner": {
    "firstName": "Alex",
    "lastName": "Jordan",
    "phoneNumber": "+15555550100",
    "reference": "ABC-123"
  }
}
```

Expected result: `201 Created` and a `Location` header containing the `transaction_id`.

Additional checks:

* `GET /transactions/{transaction_id}` returns `200 OK` and the transaction payload.
* `GET /transactions?from_date=2024-01-01&to_date=2026-01-01` returns a `searchResults` array.
`POST /admin-records`

```json
{
  "newRecords": [
    {
      "firstName": "Jordan",
      "lastName": "Taylor",
      "phoneNumber": "+15555550101",
      "identifier": "123-45-6789"
    }
  ]
}
```

Expected result: `200 OK` and an array with generated usernames or identifiers.

Additional checks:

* `POST /admin-records/searches` with a valid identifier returns `200 OK` and the matching record.
* `GET /admin-records/{record_key}` returns `200 OK` and an `ETag` header.

### Endpoint tutorials {#endpoint-tutorials}

Use these guides for full request examples and endpoint-specific flows:

* [Primary Workflow Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/pets-tutorial/index.md)
* [Transaction Workflow Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/adoptions-tutorial/index.md)
* [Administrative Workflow Tutorial](https://developer.mastercard.com/agent-suite-for-merchants/documentation/tutorials-and-guides/employees-tutorial/index.md)

## Negative testing {#negative-testing}

Negative testing confirms that invalid requests fail cleanly and return useful error details.

### Validate these behaviors {#validate-these-behaviors-1}

* Missing required fields return `400 Bad Request`.
* Invalid field values return validation errors with a clear `ReasonCode` and description.
* Requests for unknown resources return `404 Not Found`.
* Incorrect or missing authentication data is rejected.
* Encrypted endpoints reject malformed or unencrypted payloads when encryption is required.

### Negative test cases {#negative-test-cases}

Use the tabs below to view representative negative test cases for each endpoint family.
`POST /resource-a`

```json
{
  "name": "Incomplete Resource",
  "type": "PRIMARY"
}
```

Expected result: `400 Bad Request` because a required field is missing.

Additional checks:

* `PUT /resources/{resource_id}/status` with an unsupported value returns `400 Bad Request`.
`POST /transactions/{transaction_id}/actions`

```json
{
  "amount": 0,
  "currency": "EUR"
}
```

Expected result: `400 Bad Request` because the submitted amount is invalid.

Additional checks:

* `PUT /transactions/{transaction_id}` without `If-Match` returns `400 Bad Request`.
* `GET` or `DELETE /transactions/{transaction_id}` with an unknown ID returns `404 Not Found`.
`POST /admin-records/searches`

```json
{
  "identifier": "123456789"
}
```

Expected result: `400 Bad Request` because the identifier format is invalid.

Additional checks:

* `PUT /admin-records/{record_key}` without `If-Match` returns `400 Bad Request`.
* `GET` or `DELETE /admin-records/{record_key}` with an unknown key returns `404 Not Found`.

### Example error response {#example-error-response}

The OpenAPI spec defines error examples in the following structure:

```yaml
Errors:
  Error:
    - Source: YOUR_SERVICE_NAME
      ReasonCode: BAD_REQUEST
      Description: We could not handle your request.
      Recoverable: false
      Details: Invalid JSON payload.
```

For the complete list of response codes, reason codes, and formatting rules, see [Codes and Formats](https://developer.mastercard.com/agent-suite-for-merchants/documentation/code-and-formats/index.md).

### Next steps {#next-steps}

* Consult the [API Reference](https://developer.mastercard.com/agent-suite-for-merchants/documentation/api-reference/index.md) for complete endpoint specifications, request and response schemas, and environment URLs.
* If you run into issues, visit [Support](https://developer.mastercard.com/agent-suite-for-merchants/documentation/support/index.md) for FAQs and troubleshooting guidance.