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

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, 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.

1. Send Authorization Request

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

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
   • 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 an 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 — 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"
}

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:

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