# Test payments

> Pay for orders on a development store or a demo shop, and choose how each payment ends. No money moves.

Source: https://storeware.ai/docs/get-started/test-payments

A [development store](https://storeware.ai/docs/get-started/development-stores) takes test payments only. Nothing is charged, no card is typed, and no payment company is asked. You choose how each payment ends, and your app receives the same events a real shop would send.

## The four endings

| Ending | What happens to the order | Events your app receives |
| --- | --- | --- |
| `approve` | Paid at once. | `order.created.v1`, then `order.paid.v1` |
| `decline` | Waits unpaid, as if the card was refused (`card_declined`). Its stock stays held. | `order.created.v1` |
| `needs_action` | Waits for the shopper's bank. A test bank page approves or fails it. | `order.created.v1`, then `order.paid.v1` once approved |
| `error` | Waits unpaid, as if the payment company had a fault. The card is not blamed. | `order.created.v1` |

A declined or failed order can be paid again with another ending. It keeps the same payment, so `order.paid.v1` is sent once, whichever try succeeds.

A test payment is named `test_pi_` followed by the order's id, where a real payment has its provider's id.

## Pay from the shop front

Open your development store's preview from the admin, add something to the basket and fill in the details. Where a real shop shows a card form, a development store shows four buttons, labelled as a test payment where no money moves:

- **Approve** pays the order and takes you to it.
- **Decline the card** and **Cause an error** keep the basket, so you can choose another ending.
- **Ask the bank** places the order and opens a test bank page. **Approve payment** pays it. **Fail the check** leaves it waiting, with the four buttons to try again.

The shop front loads nothing from Stripe on a development store.

## Pay from the CLI

> **Early access.** The CLI and the SDK are not on npm yet, so the commands below do not run for everyone. To build an app now, write to https://storeware.ai/contact.

```bash
npx @storeware/cli store test-order --pay approve
npx @storeware/cli store test-order --pay decline
npx @storeware/cli store test-order --pay needs_action
npx @storeware/cli store test-order --pay error
```

The order is placed for a sample shopper, so add the sample data first with `store seed`. With `needs_action`, the CLI prints the test bank page's address. Open it in a browser that is previewing the store.

Without `--pay`, `store test-order` places an order on account for the sample trade buyer, as before. Add `--paid` to record that invoice as paid.

The same order can be placed over the API:

```http
POST /api/v1/developer/dev-stores/{storeId}/test-orders
Content-Type: application/json

{ "pay": "approve" }
```

## Pay as an AI shopper

A demo shop is a shop Storeware keeps open to everybody, so people and AI shoppers can try the whole checkout. It takes test payments only, like a development store, and says "Demo shop. No money moves." on every page and in its agent documents.

There, and only there, the shop advertises one payment handler: `storeware_test` (`ai.storeware.test_payment`, environment `sandbox`). Card and stablecoin handlers are not offered. To pay, send credential type `storeware_test` with the ending you want as its token: `approve`, `decline` or `needs_action`.

Over UCP, on Complete Checkout:

```json
{
  "payment": {
    "instruments": [
      {
        "id": "instrument-1",
        "type": "storeware_test",
        "handler_id": "storeware_test",
        "credential": { "type": "storeware_test", "token": "approve" }
      }
    ]
  }
}
```

Over ACP, on complete:

```json
{
  "payment_data": {
    "handler_id": "storeware_test",
    "instrument": {
      "type": "storeware_test",
      "credential": { "type": "storeware_test", "token": "approve" }
    }
  }
}
```

With `needs_action`, the session answers with a link to the test bank page, as it would for a card's bank. Any other shop refuses a `storeware_test` credential.

## Refunds

Refund a test-paid order from the admin, or through the API, as you would any order. The refund goes through every step a card refund does. It is named `test_re_` and completed at once, and your app receives `order.refunded.v1`, and `order.restocked.v1` when the refund puts stock back. Returns resolved as a refund work the same way.

## What a development store will not take

- A real card, a wallet, a stablecoin or any other payment. Only test payments and orders on account.
- A test payment at any other shop. A real shop refuses one, and so does the database. Demo shops take them too, and never an order on account.
- An order with nothing to pay with. Choose an ending.

## Good to know

- Mail about test orders is recorded and never sent.
- A development store's orders are never sent to a supplier, and never reported as sales to an ad network.
- Development stores never open to shoppers. The checkout works only in the store's own preview, and AI shoppers cannot reach it.