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

# Testing in sandbox

> Test card issuance flows, simulate transactions, and prepare for production launch.

The UQPAY sandbox environment lets you test the full card issuance lifecycle — from creating cardholders and issuing cards to simulating transactions and receiving webhooks — without processing real payments.

## Sandbox base URL

```
https://api-sandbox.uqpaytech.com/api
```

All API endpoints use the same paths as production. Replace the base URL when switching environments.

## Test the card issuance flow

In sandbox, you create real cardholders and cards just as you would in production. There are no special "test" card numbers — the cards you create are your test cards.

A typical test flow:

<Steps>
  ### Create a cardholder

  Call [Create Cardholder](/card-issuance/v1.6/api-reference/create-cardholder) with test data. Use any valid email and phone number format.

  ### Issue a card

  Call [Create Card](/card-issuance/v1.6/api-reference/create-card) with a sandbox-supported card product. See [Quickstart](/card-issuance/v1.6/guide/quickstart) for a complete walkthrough.

  ### Simulate a transaction

  Use the [Simulate Authorization](#simulate-authorization) endpoint to trigger a transaction against your card.

  ### Verify webhooks

  Confirm that your webhook endpoint receives the expected events (e.g., `issuing.transaction.authorization`).
</Steps>

## Simulate transactions

The simulator endpoints let you trigger authorization and reversal events on sandbox cards. These endpoints are available only in the sandbox environment.

### Supported BINs

Only cards with the following BIN support simulation:

| BIN        | Environment |
| ---------- | ----------- |
| `40963608` | Sandbox     |

### Simulate authorization

Trigger an authorization transaction on a card.

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/simulation/issuing/authorization \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "transaction_amount": 10.00,
    "transaction_currency": "USD",
    "merchant_name": "Test Merchant",
    "merchant_category_code": "5734"
  }'
```

| Field                    | Required | Description                        |
| ------------------------ | :------: | ---------------------------------- |
| `card_id`                |    Yes   | The card to transact against       |
| `transaction_amount`     |    Yes   | Amount to authorize                |
| `transaction_currency`   |    Yes   | Currency (e.g., `USD`, `SGD`)      |
| `merchant_name`          |    Yes   | Merchant name                      |
| `merchant_category_code` |    Yes   | MCC. Must be `5734` for simulation |

<Note>
  The `merchant_category_code` must be `5734` for simulated transactions. Other MCC values are not supported in the simulator.
</Note>

This triggers an `issuing.transaction.authorization` webhook:

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.transaction.authorization",
  "event_id": "234fca01-1ace-4d34-baf5-29b10e9d11c0",
  "source_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
  "data": {
    "authorization_code": "W6MJU9",
    "billing_amount": "11.5",
    "billing_currency": "USD",
    "card_available_balance": "988.5",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "description": "",
    "fee_pass_through": "Y",
    "merchant_data": [
      {
        "category_code": "5734",
        "city": "",
        "country": "",
        "name": "Test Merchant"
      }
    ],
    "original_transaction_id": "",
    "posted_time": "2026-04-12T15:27:39.563+08:00",
    "short_transaction_id": "T260412-2AHV51KO5U68",
    "transaction_amount": "10",
    "transaction_currency": "USD",
    "transaction_fee": "1.5",
    "transaction_fee_currency": "USD",
    "transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
    "transaction_status": "APPROVED",
    "transaction_time": "2026-04-12T15:27:39.48+08:00",
    "transaction_type": "AUTHORIZATION",
    "wallet_type": ""
  }
}
```

### Simulate reversal

Reverse an existing approved authorization using its `transaction_id`.

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/simulation/issuing/reversal \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c"
  }'
```

This triggers an `issuing.transaction.reversal` webhook:

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.transaction.reversal",
  "event_id": "255d66c0-ddf6-479a-a0b1-923e23664648",
  "source_id": "5353d200-88de-49b2-b575-d4bdd3d7be30",
  "data": {
    "authorization_code": "5PHF2P",
    "billing_amount": "11.5",
    "billing_currency": "USD",
    "card_available_balance": "1000",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "description": "",
    "fee_pass_through": "Y",
    "merchant_data": [
      {
        "category_code": "5734",
        "city": "",
        "country": "",
        "name": "Test Merchant"
      }
    ],
    "original_transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
    "posted_time": "2026-04-12T15:27:40.905+08:00",
    "short_transaction_id": "T260412-2AHV54BIN6RK",
    "transaction_amount": "10",
    "transaction_currency": "USD",
    "transaction_fee": "1.5",
    "transaction_fee_currency": "USD",
    "transaction_id": "5353d200-88de-49b2-b575-d4bdd3d7be30",
    "transaction_status": "APPROVED",
    "transaction_time": "2026-04-12T15:27:40.905+08:00",
    "transaction_type": "REVERSAL",
    "wallet_type": ""
  }
}
```

## Webhook testing

Subscribe to webhook events in the Dashboard to receive real-time notifications during testing. See the [Webhooks](/card-issuance/v1.6/webhooks/card-created) section for the full list of available events and their payload formats.

<Tip>
  Use a tool like [webhook.site](https://webhook.site) during development to inspect webhook payloads before building your production webhook handler.
</Tip>

## Related

* [Quickstart](/card-issuance/v1.6/guide/quickstart)
* [Simulate Authorization API](/card-issuance/v1.6/api-reference/simulate-authorization)
* [Simulate Reversal API](/card-issuance/v1.6/api-reference/simulate-reversal)
* [Transaction Authorization webhook](/card-issuance/v1.6/webhooks/transaction)