> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paymend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing

> How to use the sandbox environment to develop and test your integration before going live

We provide a lightweight API simulator that allows merchants and partners to test their integration with the Paymend API without processing real payments.

The sandbox is designed to validate:

* Request structure and mandatory fields
* Authentication handling
* Core payment flows (create, capture, refund, void, query)
* Basic success and failure scenarios

The simulator does not process real transactions and, in this first version, does not persist payment state. Responses are mocked and limited to predefined behaviors.

For example, the same payment `id` value is always returned for successful payment creation and all follow-up requests (capture, refund, void or query) must reference this same `id`.

## API environments

The following details should be used for testing your integration in sandbox:

| Environment | Base URL                                                           | Notes                                             |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------- |
| Sandbox     | [https://api.sandbox.paymend.com](https://api.sandbox.paymend.com) | Use for testing only. Transactions are simulated. |

**Important:** Always use your sandbox credentials when testing. Production credentials are separate and should be kept secure.

## Authentication

All API requests require a **Bearer token** in the `Authorization` header:

👉 To get your API token, just reach out to your Paymend sales representative.

```http theme={null}
Authorization: Bearer <your_api_token>
```

* Tokens are issued specifically for sandbox use.
* Requests without valid authentication will return 401 Unauthorized.
* Ensure you are using sandbox credentials when targeting the sandbox environment.

## How the simulator works

The sandbox returns simplified, deterministic responses:

* A single payment `id` is used for all responses. Any request referencing a different payment `id` will fail with a HTTP error.
* The simulator does not persist payment state. Dependent requests (capture, refund, void, query) always return a fixed success response regardless of payment history.
* Partial captures and refunds are not supported in the simulator. Any specified amount values (eg. `captureAmount`, `refundAmount`) are ignored.
* Mandatory fields defined by the API are enforced.
* Basic validation (eg. on field types) is performed.

These behaviors are intentionally limited to simplify testing.

## Test cards

<Warning>
  Real card numbers should never be used in the sandbox environment.
</Warning>

When creating payments in the sandbox, specific test card numbers determine simulated outcomes.

The table below shows which card number and brand values can be passed in the `paymentMethod` object during payment creation to receive different `status` and `failure` object values in the response.

| `card.number`        | `card.brand` | `status`                    | `failure.failureCode` |
| -------------------- | ------------ | --------------------------- | --------------------- |
| 444444444444**0000** | VISA         | `AUTHORIZED` / `CAPTURED`\* |                       |
| 555555555555**0000** | MASTERCARD   | `AUTHORIZED` / `CAPTURED`\* |                       |
| 444444444444**0051** | VISA         | `FAILED`                    | `INSUFFICIENT_FUNDS`  |
| 555555555555**0051** | MASTERCARD   | `FAILED`                    | `INSUFFICIENT_FUNDS`  |

\*Whether you receive `AUTHORIZED` or `CAPTURED` will depend on the value passed in the `captureNow` field.

## Request examples

You can find example requests for payment creation and payment management by following the links below:

* [Create payments](/create-payments)
* [Manage payments](/manage-payments)

<Note>
  In the sandbox environment, the field `source.storeId` should be populated with `store_sandbox`
</Note>

## Next Steps

Once your integration is working smoothly in sandbox:

* Request production credentials from Paymend.
* Update your base URL to the production endpoint.
* Perform live transaction testing as needed.