Transaction Simulation

The Transaction Simulation API allows you to test different transaction types by simulating cardholder-initiated transactions. This endpoint is available exclusively in the staging environment.

You can use the simulator API to validate your RHA/Webhook integration and, over time, test any changes made to the integration. Please reach out to your StraitsX representative to get the simulation postman collection

How to use the simulator API :

Create a card in your staging environment.
Use the simulation endpoint to initiate a transaction.
Verify the simulated authorization at your RHA endpoint and check your Webhook endpoint for the notification.

Supported Transaction Type

Name	Type	Description
POS Authorization	pos_authorization	Transaction that happens when a cardholder uses their card at a physical location, such as a restaurant or convenience store.
ECOM Authorization	ecom_authorization	Transaction that occurs online via web or mobile apps, such as e-commerce purchases or subscriptions like Netflix.
Incremental Authorization	incremental_authorization	Transaction that adds an amount to a preceding authorization.
Authorization Reversal	reversal	Transaction that returns funds from the preceding transaction.
Authorization Partial Reversal	partial_reversal	Transaction that partially returns funds from the preceding transaction.
ATM Cash Withdrawal	atm_cash_withdrawal	Transaction where a cardholder uses an ATM to withdraw cash, reducing the account balance.
ATM Balance Inquiry	atm_balance_inquiry	Transaction where a cardholder checks the current balance of their account using an ATM.
Preauthorization Hold	preauthorization_hold	Transaction where an acquirer (e.g., hotel or gas station) temporarily holds a sum of money to ensure sufficient funds before the final transaction amount is charged.
Preauthorization Release	preauthorization_release	When a hold expires (e.g., after 24 hours) or a transaction is canceled, the previously held funds are returned to the customer.
Preauthorization Completion	preauthorization_completion	Final settlement of a held transaction. If the final amount exceeds the hold, an additional deduction is made. If the final amount is less, the difference is refunded.
Original Credit Transaction (OCT)	original_credit_transaction	Transaction that adds funds to a customer's card account.
OOB Authentication Transaction	oob_authentication	Transactions for cards with active OOB enrollment.
Clearing Matched Transaction	clearing_matched	Matches a previous Base 1 transaction using original_transaction_id or auth_code.
Clearing Offline Refund	clearing_offline_refund	Refund flows that occur without a corresponding authorization record.
Clearing Offline Deduction	clearing_offline_deduction	Funds are deducted without prior authorization.
Partial Adjustment	clearing_partial_adjustment	The clearing amount differs from the authorized amount

Amount and Currency

The endpoint tries to simulate the perspective of user initiating a transaction so field amount and currency will reflect the acquirer perspective, making it acquirer_amount and acquirer_currency on RHA Calls and Webhook Notification.

Cross Border / International Transaction

To Simulate Cross Border Transaction, use different currency other than SGD on the currency field, for example : USD, IDR, etc. The default currency used if currency field is omitted are SGD . Please refer to the API Docs for supported currency code. The amount will be converted using internal conversion rates into the perspective Issuer and Account Amount. The following is sample of cross border transaction using USD as currency.

{
  "type": "ecom_authorization",
  "amount": 10.00,
  "currency": "USD",
  "merchant_name": "Spotify",
  "merchant_location": "STOCKHOLM",
  "merchant_country_code": "SE",
  "mid": "123456789123456",
  "mcc": "5815"
}

{
  "type": "ecom_authorization",
  "amount": 10.00,
  "merchant_name": "NTUC Fair Price"
}

Transaction Types Example

POS Authorization

POS Authorization is transaction that happens when a cardholder uses their card at a physical location, such as a restaurant or convenience store.

{
  "type": "pos_authorization",
  "amount": 10.00
}

ECOM Authorization

ECOM Authorization is transaction that happens online using web or mobile app , such as E-commerce or subscription like Netflix and Spotify.

{
  "type": "ecom_authorization",
  "amount": 5.00,
  "merchant_name": "GOJEK"
}

Incremental Authorization

Incremental Authorization is transaction that adds the amount to the preceding authorization. Need to add original_transaction_id for reference to the preceding transaction and amount to give the incremental amount.

{
  "type": "incremental_authorization",
  "amount": 10.00,
  "original_transaction_id": "551548997956215"
}

{
  "type": "ecom_authorization",
  "amount": 5.00,
  "merchant_name": "GOJEK"
}

Reversal

Reversal is transaction that returns the fund from the preceding transaction. It will returns the fund in full, so only need type and original_transaction_id as request parameter.

{
  "type": "reversal",
  "original_transaction_id": "551548997956216"
}

{
  "type": "ecom_authorization",
  "amount": 5.00,
  "merchant_name": "GOJEK"
}

Partial Reversal

Partial Reversal is transaction that partially returns the fund from the preceding transaction. Need type , amount and original_transaction_id as request parameter.

{
  "type": "partial_reversal",
  "amount": 4.00,
  "original_transaction_id": "551548997956216"
}

{
  "type": "ecom_authorization",
  "amount": 10.00,
  "merchant_name": "GOJEK"
}

ATM Cash Withdrawal

ATM Cash Withdrawal is transaction where cardholder uses an Automated Teller Machine (ATM) to withdraw cash from their account and reduce the account balance.

{
  "type": "atm_cash_withdrawal",
  "currency": "SGD",
  "mid": "123456789123456",
  "mcc": "5999",
  "merchant_name": "SIMULATOR",
  "merchant_location": "SINGAPORE",
  "merchant_country_code": "SG",
  "amount": 4
}

ATM Balance Inquiry

ATM Balance Inquiry is transaction where a cardholder checks the current balance of their account using an Automated Teller Machine. This won't reduce any balance, and will return current card balance on amount field.

{
  "type": "atm_balance_inquiry",
  "currency": "SGD",
  "mid": "123456789123456",
  "mcc": "5999",
  "merchant_name": "SIMULATOR",
  "merchant_location": "SINGAPORE",
  "merchant_country_code": "SG",
  "amount": 0
}

Preauthorization Hold

Preauthorization Hold refers to Transaction where the acquirer (such as hotel or gas station) holds some amount of money temporarily to ensure the card have sufficient amount before the final transaction amount.

{
  "type": "preauthorization_hold",
  "amount": 10.00,
  "currency": "HKD",
  "merchant_name": "Gas Station"
}

Preauthorization Release

Preauthorization Release is reversal to preauthorization hold transaction. It only requires the original_transaction_id as the original hold will be fully reversed.

{
  "type": "preauthorization_release",
  "original_transaction_id": "551548997956216"
}

{
  "type": "preauthorization_hold",
  "amount": 30.00
}

Preauthorization Completion

Preauthorization Completion is transaction that carries final amount of a hold transaction. It requires the final amount and the original_transaction_id from the preceding hold.

{
  "type": "preauthorization_completion",
  "amount": 8.00,
  "original_transaction_id": "551548997956216"
}

{
  "type": "preauthorization_hold",
  "amount": 30.00
}

Original Credit Transaction

Original Credit Transaction is transaction that directly add funds into cardholder account.

{
  "type": "original_credit_transaction",
  "amount": 50.00,
  "currency": "USD"
}

OOB Authentication

Transactions for cards with active OOB enrollment.

Card must have OOB enrollment with status ACTIVE
Authentication method must be set to OOB

{
  "type": "oob_authentication",
  "amount": 10.00,
  "currency": "SGD",
  "merchant_name": "Test Merchant"
}

Clearing Matched

Matches a previous Base 1 transaction using original_transaction_id or auth_code.

Base 1 transaction must exist and have reconciliation status pending or unmatched
Must provide either original_transaction_id or auth_code

{
  "type": "clearing_matched",
  "original_transaction_id": "551548997956216"
}

Clearing Offline Refund

Amount must be greater than 0.

original_transaction_id is optional

Useful for webhook verification in unmatched reconciliation scenarios

{
  "type": "clearing_offline_refund",
  "amount": 25.00,
  "currency": "SGD",
  "merchant_name": "Refund Merchant"
}

Clearing Offline Deduction

Amount must be greater than 0

original_transaction_id is optional

{
  "type": "clearing_offline_deduction",
  "amount": 30.00,
  "currency": "SGD",
  "merchant_name": "Deduction Merchant"
}

Clearing Partial Adjustment

Amount must be greater than 0

You must provide either original_transaction_id OR auth_code to link to the original transaction.

{
  "type": "clearing_partial_adjustment",
  "amount": 30.00,
  "merchant_name": "A Merchant",
  "original_transaction_id": "551548912345678",
  "auth_code": "J3S89X"
}

{
  "type": "clearing_partial_adjustment",
  "amount": 30.00,
  "merchant_name": "A Merchant",
  "auth_code": "J3S89X"
}

{
  "type": "clearing_partial_adjustment",
  "amount": 30.00,
  "merchant_name": "A Merchant",
  "original_transaction_id": "551548912345678",
}

Scenario Example

Below are example scenarios where the different transaction types apply.

Reversal using Ride-Sharing service

A cardholder booked a ride with a ride-sharing app like Uber and was charged 50 SGD for the trip. However, they decided to cancel the ride due to long wait times. The app initiated a full reversal of the transaction.

Original Transaction

{
  "type": "ecom_authorization",
  "amount": 50.00,
  "merchant_name": "Uber"
}

Reversed Transaction

{
  "type": "reversal",
  "original_transaction_id": "551548997956216"
}

Preauthorization Hold and Completion in Gas Station

John stopped at a gas station and used his card to refuel. The gas station placed a preauthorization hold of 50 USD to ensure sufficient funds were available. After filling up, the final amount was adjusted to 40 USD based on his actual fuel consumption.

Original transaction

{
  "type": "preauthorization_hold",
  "amount": 50.00,
  "currency": "USD",
  "merchant_name": "Gas Station ABC"
}

Preauthorization Completion

{
  "type": "preauthorization_completion",
  "amount": 40.00,
  "original_transaction_id": "551548997956216"
}

Partial Reversal using Food Delivery App

Mark ordered food from a food delivery app and paid 200 SGD using his card. Later, he realized some items were missing from the order. He complained, and the app issued a partial refund of 50 SGD to his card.

Original Transaction

{
  "type": "ecom_authorization",
  "amount": 200.00,
  "merchant_name": "Foodpanda"
}

Partial Reversal

{
  "type": "partial_reversal",
  "amount": 50.00
}