Transactions Sandbox Simulator

New
  • Published on Jun 5, 2025
  • 17 minute(s) read
Prev Next

Use transaction simulators to help troubleshoot future customer payment issues and let developers test payment integrations with realistic responses. With these simulated transaction errors and edge cases, you can prepare steps for handling potential errors in the Sandbox before going live.

Activate Transaction Simulators

You can activate each transaction simulator with a corresponding transaction amount, called a trigger. Read each section for steps to set up triggers and activate transaction simulators.

Set Your Simulator Trigger

You can set trigger amounts for transaction simulators using different methods:

  • Portal: The Amount field for the Quick Charge panel or the Create Payments page.  

  • API: The total parameter for POST /txns requests.

  • Integrated Payment Page: The config.amount parameter for PayFields and PayFrame.

Important!

Format all amounts as integers for API and integrated payment pages. Omit decimal points in transaction requests. For example, $101.03 should be formatted as 10103.

Use Test Card Data

Use the following test card data to ensure proper activation when triggering transaction simulators:

  • Number: 4242 4242 4242 4242

  • CVV: Any three-digit number. For example, 123.

  • Expiration: Any valid future date values in MMYY format. For example, 1234.

Review the Simulator Response Message

When triggering the transaction simulator with a relevant amount, an artificial platform response is returned with a message explaining the reason.

To find the platform transaction simulator response messages:

  • Portal: Access the Alerts menu of the Transaction Details page.

  • API: Review the .errors[].msg response parameter for POST /txns requests.

  • Integrated Payment Page: Review the responseValue JavaScript elements.

Trigger Vantiv Simulators

Vantiv transaction simulators use Sale transaction types to simulate different responses at different points of the transaction lifecycle without changing the transaction type.  

Use each amount as the transaction amount or total request parameter to trigger each simulator. For example, using $500.04 returns an “Insufficient Funds” error.

To trigger a Vantiv Sale transaction simulator:  

  1. Set the transaction type to Sale.

  2. Enter the test card data.

  3. Provide one of the following trigger amounts and process the transaction to simulate a potential Vantiv platform credit card sale processing error:

    Trigger Amount

    Simulator Response Message

    $95.87

    Declined

    $500.01

    Exceeds Approval Amount Limit

    $500.04

    Insufficient Funds

    $565.56

    Transaction not supported by issuer.

    $566.56

    Blocked by cardholder/contact cardholder.

    $848.00

    Processing Network Unavailable

    $848.01

    Issuer Unavailable

    $848.02

    Re-submit Transaction

    $848.03

    Call Issuer

    $848.04

    Merchant not certified/enabled for IIAS.

    $848.05

    Issuer Generated Error

    $848.06

    Restricted Card

    $848.07

    Card Not Active

    $848.08

    Illegal Transaction

    $848.09

    Duplicate Transaction

    $848.10

    System Error

    $848.11

    System Error (cannot process)

    $848.12

    Lost/Stolen Card

    $848.13

    Expired Card

    $848.14

    Restricted Card

    $848.15

    No such issuer

    $848.16

    Transaction not allowed at terminal.

    $848.17

    Cardholder transaction not permitted.

    $848.18

    Cardholder requested that recurring or installment payment be stopped.

    $848.19

    Do Not Honor

    $848.20

    Decline - Request Positive ID

    $848.21

    Processing Network Error

    $848.22

    Soft Decline - Primary Funding Source Failed

    $848.23

    Soft Decline - Auto Recycling In Progress

    $848.24

    Internal System Error - Call Vantiv

    $848.25

    Generic Decline

    Important!

    Do not use values outside the specified triggers to activate Sandbox simulators. Non-trigger values return standard successful server responses for normal testing.

Result: The transaction simulator returns the platform simulator response message aligned with the amount.

Trigger VCore Simulators

VCore transaction simulators are divided into Authorization (Auth) and Capture transaction categories:

  • Auth: Credit card authorization responses.

  • Capture: Credit card sale or authorization transaction settlement batching responses.

Sale transactions combine the Auth and Capture processes into one step. This process seeks immediate authorization while assigning the transaction to the daily batch. Using Sale transactions works for VCore simulators and eliminates the need for a second manual capture after a prior Authorization transaction.

Important!

You must include "platform": "VCORE" in API request bodies to set the correct platform before triggering VCore transaction simulators.

Trigger Auth Transaction Simulators

Merchants use Auth transactions to collect payment information and get approval from a cardholder's financial institution to hold and capture funds.

To trigger a VCore Auth transaction simulator:  

  1. Set the transaction type to Authorization Only.

  2. Enter the test card data.

  3. Provide one of the following trigger amounts and process the transaction to simulate a potential VCore platform credit card authorization error:

    Authorization Amount

    Simulated Authorization Error

    $101.03

    Invalid Merchant ID

    $101.05

    Generic Authorization Decline

    $101.13

    Invalid Amount

    $101.14

    Invalid Account Number

    $101.30

    Message Format Error

    $101.39

    No Credit Account

    $101.51

    Insufficient Funds

    $101.54

    Expired Card

    $101.82

    Invalid CVV

    $101.83

    Unable to Verify PIN

    $101.96

    System Error

    Important!

    Do not use values outside the specified triggers to activate Sandbox simulators. Non-trigger values return standard successful server responses for normal testing.

Result: The Auth transaction simulator returns the platform simulator response message aligned with the amount shown in the table.  

Trigger Capture Transaction Simulators

Merchants use Auth transactions to collect payment information and get approval from a cardholder's financial institution to hold and capture funds.

To trigger a VCore Capture transaction simulator:

  1. Set the transaction type to Sale.

    Note

    The API provides a Capture transaction type ("type": 3) for past Auth transactions. However, the portal and integrated payment page capture transaction type is Sale.

  2. Enter the test card data.

  3. Provide one of the following trigger amounts and process the transaction to simulate a potential VCore platform credit card capture error:

    Authorization Amount

    Simulated Authorization Error

    $201.02

    Invalid authorization source code.

    $201.04

    Invalid or missing entry mode.

    $201.10

    Invalid or missing merchant category code (MCC).

    $201.11

    Invalid or missing transaction number.

    $201.12

    Invalid or missing merchant number presented by the merchant.

    $201.14

    Test card rejected for settlement.

    $201.20

    Transaction Amount Exceeds Network Limit.

    $201.21

    The transaction amount exceeds the internal limit. Transaction pending further review.

    $201.22

    Non-Debit Merchant USB

    $201.23

    Blocked Merchant

    $201.30

    Transaction Declined

    Important!

    • You can’t view Capture simulator responses until the transaction status is Captured. Capture simulator responses appear after the daily settlement batch closes at 9:30 PM Eastern Time.

    • Do not use values outside the specified triggers to activate Sandbox simulators. Non-trigger values return standard successful server responses for normal testing.

Result: The Capture transaction simulator returns the platform simulator response message aligned with the amount shown in the table.  

Simulator Examples

The following API examples demonstrate how simulators respond when activated by a total (Amount) trigger.

Vantiv: Insufficient Funds Simulator

In this example, the total amount provided is $500.04, which triggers the Vantiv simulator for an Insufficient Funds error. The following request body sets the total amount to trigger the Insufficient Funds simulator.

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
{
    "merchant": "t1_mer_123abc4d567890efg1h2i34",
    "origin": "2",
    "currency": "USD",
    "total": 50004,
    "first": "John",
    "last": "Doe",
    "zip": 12345,
    "payment": {
        "number": 4242424242424242,
        "cvv": 123
    },
    "expiration": "1234",
    "type": 2
}

The following response body shows the applicable error message simulating the Vantiv “Insufficient Funds” platform error response:

{
    "response": {
        "data": [
            {
                "payment": {
                    "id": "g123456abc7de8f",
                    "method": 2,
                    "number": "4242",
                    "routing": "0",
                    "bin": "424242",
                    "payment": null,
                    "lastChecked": null,
                    "last4": null,
                    "mask": null,
                    "plaidConsumerAccount": null
                },
                "id": "t1_txn_123abc4d567890efg1h2i34",
                "created": "2025-05-22 00:00:00.0000",
                "modified": "2025-05-22 00:00:00.0000",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "t1_log_123abc4d567890efg1h2i34",
                "ipCreated": "0.0.0.0",
                "ipModified": "0.0.0.0",
                "merchant": "t1_mer_123abc4d567890efg1h2i34",
                "token": null,
                "fortxn": null,
                "fromtxn": null,
                "batch": null,
                "subscription": null,
                "type": 2,
                "expiration": "1234",
                "currency": "USD",
                "platform": "VANTIV",
                "authDate": null,
                "authCode": null,
                "captured": null,
                "settled": null,
                "settledCurrency": null,
                "settledTotal": null,
                "allowPartial": 0,
                "order": "",
                "description": null,
                "descriptor": "Merchant Co.",
                "terminal": null,
                "terminalCapability": null,
                "entryMode": null,
                "origin": "2",
                "tax": null,
                "total": 50004,
                "cashback": null,
                "authorization": null,
                "approved": null,
                "cvv": 1,
                "swiped": 0,
                "emv": 0,
                "signature": 0,
                "unattended": null,
                "clientIp": null,
                "first": "John",
                "middle": null,
                "last": "Doe",
                "company": null,
                "email": null,
                "address1": null,
                "address2": null,
                "city": null,
                "state": null,
                "zip": "12345",
                "country": null,
                "phone": null,
                "mid": "12345678",
                "status": 2,
                "refunded": 0,
                "reserved": 0,
                "misused": null,
                "checkStage": "auth",
                "imported": 0,
                "inactive": 0,
                "frozen": 0,
                "discount": null,
                "shipping": null,
                "duty": null,
                "pin": 0,
                "traceNumber": null,
                "cvvStatus": null,
                "unauthReason": null,
                "fee": null,
                "fundingCurrency": "USD",
                "authentication": null,
                "authenticationId": null,
                "cofType": null,
                "copyReason": null,
                "originalApproved": null,
                "currencyConversion": null,
                "serviceCode": null,
                "authTokenCustomer": null,
                "debtRepayment": "0",
                "statement": null,
                "convenienceFee": 0,
                "surcharge": null,
                "channel": null,
                "funded": null,
                "fundingEnabled": "1",
                "requestSequence": 0,
                "processedSequence": 0,
                "mobile": null,
                "pinEntryCapability": null,
                "fbo": "WORLDPAY_FBO1",
                "returned": null,
                "txnsession": null,
                "networkTokenIndicator": null,
                "softPosDeviceTypeIndicator": null,
                "softPosId": null,
                "tip": null,
                "pinlessDebitConversion": null
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": [
            {
                "field": null,
                "code": 15,
                "severity": 2,
                "msg": "Transaction declined: Insufficient Funds",
                "errorCode": "insufficient_funds"
            }
        ]
    }
}

VCore: Invalid Merchant ID Simulator

In this example, the total amount provided is $101.03, which triggers the VCore simulator for an “Invalid Merchant ID” error. The following request body sets the total amount to trigger the simulator response:

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}  
{
    "merchant": "t1_mer_123abc4d567890efg1h2i34",
    "platform": "VCORE",
    "origin": "2",
    "currency": "USD",
    "total": 10103,
    "first": "John",
    "last": "Doe",
    "zip": 12345,
    "payment": {
        "number": 4242424242424242,
        "cvv": 123
    },
    "expiration": "1234",
    "type": 2
}

The following response body shows the applicable error message simulating the VCore “Invalid Merchant ID” platform error response:

{
    "response": {
        "data": [
            {
                "payment": {
                    "id": "g123456abc7de8f",
                    "method": 2,
                    "number": "4242",
                    "routing": "0",
                    "bin": "424242",
                    "payment": null,
                    "lastChecked": null,
                    "last4": null,
                    "mask": null,
                    "plaidConsumerAccount": null
                },
                "id": "t1_txn_123abc4d567890efg1h2i34",
                "created": "2025-05-22 00:00:00.0000",
                "modified": "2025-05-22 00:00:00.0000",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "t1_log_123abc4d567890efg1h2i34",
                "ipCreated": "0.0.0.0",
                "ipModified": "0.0.0.0",
                "merchant": "t1_mer_123abc4d567890efg1h2i34",
                "token": null,
                "fortxn": null,
                "fromtxn": null,
                "batch": null,
                "subscription": null,
                "type": 2,
                "expiration": "1234",
                "currency": "USD",
                "platform": "VCORE",
                "authDate": null,
                "authCode": null,
                "captured": null,
                "settled": null,
                "settledCurrency": null,
                "settledTotal": null,
                "allowPartial": 0,
                "order": "",
                "description": null,
                "descriptor": "Merchant Co.",
                "terminal": null,
                "terminalCapability": null,
                "entryMode": null,
                "origin": "2",
                "tax": null,
                "total": 10103,
                "cashback": null,
                "authorization": "123456",
                "approved": null,
                "cvv": 1,
                "swiped": 0,
                "emv": 0,
                "signature": 0,
                "unattended": null,
                "clientIp": null,
                "first": "John",
                "middle": null,
                "last": "Doe",
                "company": null,
                "email": null,
                "address1": null,
                "address2": null,
                "city": null,
                "state": null,
                "zip": "12345",
                "country": null,
                "phone": null,
                "mid": "12345678",
                "status": 2,
                "refunded": 0,
                "reserved": 0,
                "misused": null,
                "checkStage": "auth",
                "imported": 0,
                "inactive": 0,
                "frozen": 0,
                "discount": null,
                "shipping": null,
                "duty": null,
                "pin": 0,
                "traceNumber": null,
                "cvvStatus": null,
                "unauthReason": null,
                "fee": null,
                "fundingCurrency": "USD",
                "authentication": null,
                "authenticationId": null,
                "cofType": null,
                "copyReason": null,
                "originalApproved": null,
                "currencyConversion": null,
                "serviceCode": null,
                "authTokenCustomer": null,
                "debtRepayment": "0",
                "statement": null,
                "convenienceFee": 0,
                "surcharge": null,
                "channel": null,
                "funded": null,
                "fundingEnabled": "1",
                "requestSequence": 0,
                "processedSequence": 0,
                "mobile": null,
                "pinEntryCapability": null,
                "fbo": "WORLDPAY_FBO1",
                "returned": null,
                "txnsession": null,
                "networkTokenIndicator": null,
                "softPosDeviceTypeIndicator": null,
                "softPosId": null,
                "tip": null,
                "pinlessDebitConversion": null
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": [
            {
                "field": null,
                "code": 15,
                "severity": 2,
                "msg": "Transaction declined: Invalid Merchant ID",
                "errorCode": "invalid_merchant_id"
            }
        ]
    }
}

Related articles