Simulate Card Transactions

Simulate card transactions for testing purposes as part of the sandbox environment

New to the sandbox environment? Read Sandbox vs Production to understand more about sandbox environment.

Card Transaction Simulator

The Card Transaction Simulator allows you to test full card transaction lifecycles in the sandbox environment, without sending transactions 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

https://core.sandbox.gnosispay.in/docs/simulator-api

How to Simulate a Card Transaction

1. Authenticate with the Simulator API

   Use HTTP Basic Auth:

   • Username: simulator
   • Password: Provided during onboarding

   All simulator endpoints require authentication.

2. Choose the Card Identifier

   You can simulate transactions using:

   • card_id → POST /transactions/simulate
   • pan → POST /transactions/simulate-by-pan

   Both endpoints behave identically.

3. Understand Request Fields

   All simulation requests use these fields:

   Field	Type	Required	Description
   transaction_type	string	Yes	authorization, reversal, replacement, clearing, or clearing_cancellation
   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, replacement, clearing, and clearing_cancellation
   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: authorization, reversal, replacement, clearing, and clearing cancellation.

Simulate an Authorization

Authorization creates an initial hold on the card balance.

1. Send Authorization Request

   {
     "transaction_type": "authorization",
     "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "amount": "100.50",
     "currency": "USD"
   }
   

   Required: transaction_type, amount, currency, and card_id or pan.

2. Simulator Validation

   The simulator will:

   • Confirm the card exists
   • Verify the card is active
   • Check sufficient available balance
   • Place a hold for the requested amount
3. Store Authorization Code

   If approved, the response includes authorization_code and authorization_id.

   Save the authorization_code as it’s required for reversals, replacements, and clearing operations.

Simulate a Reversal

Reversal cancels a previous authorization entirely and releases the held amount.

1. Provide Authorization Code

   You must use the authorization_code returned from the original authorization.

2. Send Reversal Request

   {
     "transaction_type": "reversal",
     "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "amount": "100.50",
     "currency": "USD",
     "authorization_code": "ABC123"
   }
   
3. Simulator Behavior

   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.

1. Provide Authorization Code

   Use the authorization_code from the original authorization.

2. Send Replacement Request

   {
     "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 and replacement_amount.

3. Simulator Behavior

   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.

1. Provide Authorization Code

   Use the authorization_code from the original authorization.

2. Send Clearing Request

   {
     "transaction_type": "clearing",
     "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "amount": "100.50",
     "currency": "USD",
     "authorization_code": "ABC123"
   }
   
3. Simulator Behavior

   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 a 409 error.

Simulate a Clearing Cancellation

Clearing cancellation cancels a transaction via clearing. For partial cancellation, send an amount lower than the original authorization.

1. Provide Authorization Code

   Use the authorization_code from the original authorization.

2. Send Clearing Cancellation Request

   {
     "transaction_type": "clearing_cancellation",
     "card_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "amount": "100.50",
     "currency": "USD",
     "authorization_code": "ABC123"
   }
   
3. Simulator Behavior

   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:

{
  "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 as most fields will be empty or zero-valued:

{
  "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:

{
  "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"
}

denial_code and denial_reason use the same codes documented in Card Decline Reasons, use the simulator to test the responses and showcase the right mapping according to the guide.

Error Handling

Validation and authentication errors return structured error objects:

{
  "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