> ## Documentation Index
> Fetch the complete documentation index at: https://gnosispay-feat-v2-auth-module.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Simulate Card Transactions
> Simulate card transactions for testing purposes as part of sandbox environment.
### Card Transaction Simulator
The Card Transaction Simulator allows you to test full card transaction lifecycles in the sandbox environment — without sending traffic to the live card network.
When you send a transaction request:
1. The simulator authenticates the request
2. It checks available balance
3. It applies lifecycle logic:
* **Authorization** creates a hold
* **Reversal** releases a hold
* **Replacement** adjusts an existing hold
* **Clearing** confirms/settles a transaction
* **Clearing Cancellation** cancels via clearing
4. It returns an approval or denial response with production-like fields
**Important:** No traffic is sent to the live card network. All validation and balance logic is handled internally by the simulator.
```
https://core.sandbox.gnosispay.in/docs/simulator-api
```
## How to Simulate a Card Transaction
Use HTTP Basic Auth:
* **Username:** `simulator`
* **Password:** Provided during onboarding
All simulator endpoints require authentication.
You can simulate transactions using:
* `card_id` → `POST /transactions/simulate`
* `pan` → `POST /transactions/simulate-by-pan`
Both endpoints behave identically.
All simulation requests use these fields:
| Field | Type | Required | Description |
| -------------------- | ------ | ----------- | ---------------------------------------------------- |
| `transaction_type` | string | Yes | `authorization`, `reversal`, or `replacement` |
| `card_id` | uuid | Yes\* | Card UUID (use `pan` instead on the by-PAN endpoint) |
| `pan` | string | Yes\* | Card PAN (only on the by-PAN endpoint) |
| `amount` | string | Yes | Amount in major units (e.g., `"100.50"`) |
| `currency` | string | Yes | `USD`, `EUR`, or `GBP` |
| `authorization_code` | string | Conditional | Required for `reversal` and `replacement` |
| `replacement_amount` | string | Conditional | Required for `replacement` |
| `merchant_name` | string | No | Defaults to `"TEST MERCHANT"` |
| `merchant_code` | string | No | MCC code. Defaults to `"5541"` |
## Transaction Types
The simulator supports five transaction types that form a complete lifecycle:
## Simulate an Authorization
Authorization creates an initial hold on the card balance.
```json theme={null}
{
"transaction_type": "authorization",
"card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "100.50",
"currency": "USD"
}
```
**Required:**
* `transaction_type`: "authorization"
* `amount`
* `currency`
* `card_id` or `pan`
The simulator will:
* Confirm the card exists
* Verify the card is active
* Check sufficient available balance
* Place a hold for the requested amount
If approved, the response includes:
* `authorization_code`
* `authorization_id`
**Save the `authorization_code`** — it is required for reversals, replacements, and clearing operations.
## Simulate a Reversal
Reversal cancels a previous authorization entirely and releases the held amount.
You must use the `authorization_code` returned from the original authorization.
```json theme={null}
{
"transaction_type": "reversal",
"card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "100.50",
"currency": "USD",
"authorization_code": "ABC123"
}
```
The simulator will:
* Validate the original authorization exists
* Confirm the amount matches
* Release the full held balance
## Simulate a Replacement
Replacement adjusts a previous authorization to a different amount.
Use the `authorization_code` from the original authorization.
```json theme={null}
{
"transaction_type": "replacement",
"card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "100.50",
"currency": "USD",
"authorization_code": "ABC123",
"replacement_amount": "75.00"
}
```
**Required:**
* `authorization_code`
* `replacement_amount`
The simulator will:
* Validate the original authorization
* Reduce or increase the held amount
* Update the balance accordingly
## Simulate a Clearing
Clearing confirms a previous authorization (settlement/base II) and finalizes the transaction.
Use the `authorization_code` from the original authorization.
```json theme={null}
{
"transaction_type": "clearing",
"card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "100.50",
"currency": "USD",
"authorization_code": "ABC123"
}
```
The simulator will:
* Validate the original authorization
* Process the settlement
* Finalize the transaction
The simulator requires a minimum 2-minute gap between clearing messages for the same authorization. Sending a second clearing before this window elapses will result in an error.
## Simulate a Clearing Cancellation
Clearing cancellation cancels a transaction via clearing. For partial cancellation, send an amount lower than the original authorization.
Use the `authorization_code` from the original authorization.
```json theme={null}
{
"transaction_type": "clearing_cancellation",
"card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"amount": "100.50",
"currency": "USD",
"authorization_code": "ABC123"
}
```
The simulator will:
* Validate the original authorization
* Process the cancellation
* Adjust balances accordingly
For partial cancellations, use an amount lower than the original authorization amount.
## Response Handling
### Approved (Authorization)
An approved authorization response includes full transaction details:
```json theme={null}
{
"status": "approved",
"authorization_code": "ABC123",
"authorization_id": 98765432,
"authorization_date_time": "2025-06-15T14:30:00Z",
"settlement_amount": "100.50",
"mode_type": "DEBIT",
"card_mode": "CHIP",
"is_domestic_transaction": true
}
```
### Approved (Clearing/Clearing Cancellation)
Clearing responses are sparse — most fields will be empty or zero-valued:
```json theme={null}
{
"status": "approved",
"authorization_code": "",
"authorization_id": 0,
"authorization_date_time": "0001-01-01T00:00:00Z",
"settlement_amount": "",
"mode_type": "",
"card_mode": "",
"is_domestic_transaction": false
}
```
### Denied
If denied, the response includes detailed denial information:
```json theme={null}
{
"status": "denied",
"authorization_code": "",
"authorization_id": 98765432,
"authorization_date_time": "2025-06-15T14:30:00Z",
"settlement_amount": "0.00",
"mode_type": "DEBIT",
"card_mode": "CHIP",
"is_domestic_transaction": true,
"denial_code": "810",
"denial_reason": "Insufficient balance"
}
```
## Common Denial Codes
| Code | Reason |
| ----- | ---------------------------- |
| `810` | Insufficient balance |
| `UBT` | Card is blocked |
| `BNP` | Card reported lost |
| `BNR` | Card reported stolen |
| `FRB` | Card not activated |
| `BND` | Card is cancelled |
| `PFT` | Denied by anti-fraud |
| `FR7` | Card not present in database |
| `VNM` | Card expired |
| `CNC` | Account cancelled |
| `CND` | Account blocked |
## Error Handling
Validation and authentication errors return structured error objects:
```json theme={null}
{
"code": 400,
"message": "authorization_code is required for reversal, replacement, and clearing transactions"
}
```
**Possible HTTP status codes:**
| Status | Cause |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | Invalid credentials |
| `400` | Validation error (missing fields, invalid amount/currency) |
| `404` | Card or account not found |
| `409` | Clearing collision — a clearing message is already being processed for this authorization. Wait at least 2 minutes between clearing messages |