Skip to content

Simulate Card Transaction ​

POST /openapi/v2/cards/transactions/simulate

Sandbox only. Acceptance does not mean the purchase has completed; verify the final result through transaction queries and merchant webhooks.

ItemValue
HTTP methodPOST
Request path/openapi/v2/cards/transactions/simulate
Request typeapplication/json

Product capabilities ​

Card productSupported simulation typesMerchant information
Mastercard Hong Kong USD cardAUTHORIZE, CAPTUREOptional
Mastercard Global USD cardAUTHORIZE, VOID, REFUNDAll five merchant fields below are required

The current request currency supports only USD (a three-character code), not USDT. The service-provider currency comes from the card product; the request cannot change the product's settlement currency.

Request parameters ​

FieldTypeRequiredDescription
requestNostringYesCaller-provided business idempotency key, from 1 to 64 visible ASCII characters without spaces.
cardIdstringYesCard ID, up to 128 characters.
transactionTypestringYesAUTHORIZE, CAPTURE, VOID, or REFUND; see the product capabilities above.
originalTransactionIdstringConditionalRequired for CAPTURE, VOID, and REFUND, up to 128 characters. Must be the original service-provider transaction ID for the same tenant and card, not a requestNo or simulationNo.
amountnumberYesGreater than zero, with up to 18 integer digits and 18 decimal places; product amount limits still apply.
currencystringYesCurrently use USD.
mccstringConditionalMerchant category code, up to 8 characters; required for the Global USD card.
merchantNamestringConditionalMerchant name, up to 128 characters; required for the Global USD card.
merchantCountrystringConditionalTwo-letter merchant country or region code; required for the Global USD card.
merchantCitystringConditionalMerchant city, up to 128 characters; required for the Global USD card.
merchantPostcodestringConditionalMerchant postal code, up to 32 characters; required for the Global USD card.

For subsequent operations, use the previous response's providerTransactionId or the service-provider ID of a stored transaction. The platform must recognize the original transaction as belonging to this card before continuing; HTTP 200 alone does not indicate transaction success. Use an amount below the original purchase amount to simulate a partial refund. When the original purchase is known, the refund must not exceed its remaining amount after successful refunds.

Request example ​

Replace cardId with an available Sandbox card owned by the current tenant:

json
{
  "requestNo": "SIM-20261010-001",
  "cardId": "card_001",
  "transactionType": "AUTHORIZE",
  "amount": 10.5,
  "currency": "USD",
  "mcc": "5812",
  "merchantName": "Example Restaurant",
  "merchantCountry": "US",
  "merchantCity": "New York",
  "merchantPostcode": "10001"
}

Response data ​

FieldTypeDescription
simulationNostringPlatform simulation order number.
requestNostringCaller-provided business idempotency key.
cardIdstringCard ID.
providerNamestringPublic channel alias: CPS, PHY; an unmapped channel returns UNKNOWN.
transactionTypestringRequested simulation type.
acceptedbooleanWhether the request was explicitly accepted; does not indicate purchase completion.
statusstringSimulation request status: CREATED, PROCESSING, UNKNOWN, or FAILED; accepted requests usually return PROCESSING.
providerTransactionIdstring/nullService-provider transaction ID; null when one is not returned.
codestring/nullResult or failure code; evaluate separately from the outer code.
messagestring/nullResult or failure message.

UNKNOWN means the request outcome is unknown; do not treat it as a failure and debit or refund again. Verify the final business result through List Card Transactions and Merchant Webhooks.