Simulate Card Transaction
POST/openapi/v2/cards/transactions/simulateSandbox only. Acceptance does not mean the purchase has completed; verify the final result through transaction queries and merchant webhooks.
| Item | Value |
|---|---|
| HTTP method | POST |
| Request path | /openapi/v2/cards/transactions/simulate |
| Request type | application/json |
Product capabilities
| Card product | Supported simulation types | Merchant information |
|---|---|---|
| Mastercard Hong Kong USD card | AUTHORIZE, CAPTURE | Optional |
| Mastercard Global USD card | AUTHORIZE, VOID, REFUND | All 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
| Field | Type | Required | Description |
|---|---|---|---|
requestNo | string | Yes | Caller-provided business idempotency key, from 1 to 64 visible ASCII characters without spaces. |
cardId | string | Yes | Card ID, up to 128 characters. |
transactionType | string | Yes | AUTHORIZE, CAPTURE, VOID, or REFUND; see the product capabilities above. |
originalTransactionId | string | Conditional | Required 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. |
amount | number | Yes | Greater than zero, with up to 18 integer digits and 18 decimal places; product amount limits still apply. |
currency | string | Yes | Currently use USD. |
mcc | string | Conditional | Merchant category code, up to 8 characters; required for the Global USD card. |
merchantName | string | Conditional | Merchant name, up to 128 characters; required for the Global USD card. |
merchantCountry | string | Conditional | Two-letter merchant country or region code; required for the Global USD card. |
merchantCity | string | Conditional | Merchant city, up to 128 characters; required for the Global USD card. |
merchantPostcode | string | Conditional | Merchant 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:
{
"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
| Field | Type | Description |
|---|---|---|
simulationNo | string | Platform simulation order number. |
requestNo | string | Caller-provided business idempotency key. |
cardId | string | Card ID. |
providerName | string | Public channel alias: CPS, PHY; an unmapped channel returns UNKNOWN. |
transactionType | string | Requested simulation type. |
accepted | boolean | Whether the request was explicitly accepted; does not indicate purchase completion. |
status | string | Simulation request status: CREATED, PROCESSING, UNKNOWN, or FAILED; accepted requests usually return PROCESSING. |
providerTransactionId | string/null | Service-provider transaction ID; null when one is not returned. |
code | string/null | Result or failure code; evaluate separately from the outer code. |
message | string/null | Result 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.
