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

# Test an Integration

> Create test payment transactions, complete them on the test bank, and simulate outcomes

A test payment transaction goes through the same API as a live one, and moves no real money. There are no separate credentials: any credential that can create a payment transaction can create a test one, before the merchant goes live too. The merchant does need an active bank account in the payment transaction's currency, as in [Onboard a merchant](https://docs.quidkey.com/api-v1/journeys/onboard-a-merchant.md#8-add-the-bank-account).

| # | Step | Who |
| - | - | - |
| 1 | Create a test payment transaction | API |
| 2 | Complete the checkout on the test bank | **Person** |
| 3 | Read the payment transaction | API, polling |
| 4 | Receive its event | Quidkey sends it, optional |
| 5 | List test payment transactions | API |
| 6 | Create a payment transaction that simulates an outcome | API, USD only |
| 7 | Complete its checkout | **Person** |
| 8 | Read it until it reaches that outcome | API, polling |

## 1. Create a Test Payment Transaction

Send the same body as a [live payment transaction](https://docs.quidkey.com/api-v1/journeys/hosted-checkout.md#2-create-the-payment-transaction), with `is_test: true`:

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/transactions' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "payment",
    "amount": { "value": 2550, "currency": "EUR" },
    "order": { "order_id": "TEST-1" },
    "customer_details": {
      "full_name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+353861234567",
      "country": "IE"
    },
    "statement_descriptor": "Example Store",
    "authorization": {
      "method": "checkout",
      "success_url": "https://shop.example.com/paid",
      "failure_url": "https://shop.example.com/failed"
    },
    "is_test": true
  }'
```

The answer is 201, with `is_test: true`, and `checkout` once, as for a live payment transaction. Without `is_test`, a payment transaction is live, and a merchant that isn't live yet answers 409 `LIVE_PAYMENTS_NOT_ALLOWED`.

## 2. Complete the Checkout

Open `checkout.url` and choose the test bank. Approve the payment transaction on its page. **Person.**

## 3. Read the Payment Transaction

```bash theme={null}
curl 'https://api.quidkey.com/v1/transactions/tx_1' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

A test payment transaction reads like any other, with `is_test: true`. `POST /transactions/{id}:issueCheckout` works on it too.

## 4. Receive Its Event

An event for a test payment transaction names one whose `is_test` is `true`. A webhook endpoint created through the API receives test events as well as live ones.

## 5. List Test Payment Transactions

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/transactions?is_test=true' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

A list holds one kind: without `is_test=true`, it lists live records only. The same goes for `POST /merchants/{id}/transactions:search` and `GET /merchants/{id}/payment-links`. A test payment link is created with `is_test: true` too.

Bank accounts, balances and payouts show live records only, so a test payment transaction's `payout` is always `null`.

## 6. Simulate an Outcome

A USD test payment transaction can choose how it ends, with `simulation`:

```json theme={null}
{
  "type": "payment",
  "amount": { "value": 100000, "currency": "USD" },
  "order": { "order_id": "TEST-2" },
  "customer_details": {
    "full_name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+12025550123",
    "country": "US"
  },
  "statement_descriptor": "Example Store",
  "authorization": {
    "method": "checkout",
    "success_url": "https://shop.example.com/paid",
    "failure_url": "https://shop.example.com/failed"
  },
  "is_test": true,
  "simulation": { "payment_outcome": "failed_insufficient_funds" }
}
```

| Field | Values |
| - | - |
| `payment_outcome` | `paid`, `on_hold_daily_limit`, `cancelled_for_fraud_risk`, `cancelled_for_balance_check`, `failed_insufficient_funds`, `reversed_insufficient_funds`, `failed_customer_dispute`, `reversed_customer_dispute`, `failed_closed_bank_account`, `reversed_closed_bank_account` |
| `customer_outcome` | `verified`, `rejected`, `in_review` |
| `bank_link_outcome` | `active`, `rejected` |

* `simulation` needs `is_test: true`, or it answers 400 `SIMULATION_REQUIRES_TEST`.
* A payment transaction whose route can't honour it, such as one in another currency, answers 422 `SIMULATION_NOT_SUPPORTED`. The merchant also needs to be set up for USD test payment transactions.
* `simulation` isn't read back on the payment transaction.

## 7. Complete Its Checkout

Follow `checkout.url` and complete the page, as in step 2. **Person.**

## 8. Read It Until It Reaches the Outcome

```bash theme={null}
curl 'https://api.quidkey.com/v1/transactions/tx_2' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

Poll until the payment transaction reads the status you simulated, such as `failed` for `failed_insufficient_funds`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.