Merchant Boarding Sandbox Simulator

Replicate realistic merchant boarding responses with Merchant boarding simulators, which could otherwise usually take hours or days for manual risk review and underwriting for each platform's legal entity. Emulate risk declines or manual reviews, configure handling steps, and set customer experience standards for new merchants awaiting onboarding approval.

Activate Merchant Boarding Simulators

You can activate each Merchant boarding simulator with a platform-specific value, known as a trigger. The simulator response reflects a typical manual risk denial or hold for review by an underwriter, aiding in building your merchant boarding experience to incorporate scenarios needing review from the Payrix Pro Underwriting Team.

Set Your Simulator Trigger

You can set trigger values for Merchant boarding simulators using different methods:

Merchant Signup Form: The web-based Merchant self-signup form.
Direct API Integration: POST /entities requests.

Review Simulator Responses

When triggering the Merchant boarding simulators, an artificial platform risk review updates the Merchant's boarding status. You can verify expected responses and simulated platform messages with the portal or API.

You can verify the Merchant boarding simulator responses in two ways:

Portal: Access the Boarding Status field in the Business menu Account tab on the Merchant Profile page.
API: Review the status response parameter for POST /entities requests and query GET /merchantResults.

Trigger Vantiv Simulators

Vantiv Merchant boarding simulators use the Zip (zip) field to trigger the realistic boarding status updates without manual Payrix Pro Underwriting Team intervention or review.

To trigger a Merchant boarding simulator:

Create a Merchant Signup Form or build a POST /entities request.
Use one of the following trigger values for the zip parameter to simulate a manual review or decline Payrix Pro risk review scenario:

Zip Value	Merchant Boarding Status	Simulator Response Message
11111	Manual Review	Platform denied boarding this merchant.
55555	Denied	Platform denied boarding this merchant.

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

Submit the new Merchant Signup Form or POST /entities request.
Verify the Merchant’s boarding status:
- Portal: The Boarding Status field in the Business menu Account tab on the Merchant Profile page.
- API: The status response parameter for the initial POST /entities request.

Result: The boarding status for your new Sandbox Merchant is shown as Manual Review or Denied, depending on the trigger.

Trigger VCore Simulators

VCore Merchant boarding simulators use the EIN (ein) field to trigger the realistic boarding status updates without manual Payrix Pro Underwriting Team intervention or review.

To trigger a Merchant boarding simulator:

Create a Merchant Signup Form or build a POST /entities request.
Use the following trigger value as the employer identification number (EIN) to simulate a decline Payrix Pro risk review scenario:

EIN Value	Merchant Boarding Status	Simulator Response Message
[2-9]xxxxxxxx	Denied	Platform denied boarding this merchant.

Note: The EIN value can be any nine-digit number that starts with 2 through 9, such as 234567890. The EIN can’t begin with the number 1 to trigger the desired simulator response.

Submit the new Merchant Signup Form or POST /entities request.
Verify the Merchant’s boarding status:
- Portal: The Boarding Status field in the Business menu Account tab on the Merchant Profile page.
- API: The status response parameter for the initial POST /entities request.

Result: Your new Sandbox Merchant’s boarding status becomes Denied. The simulator response message appears in the portal on the Alerts tab of the Merchant Profile page. You can query GET /merchantResults with a SEARCH: merchant[equals]={id} header using the new Merchant’s ID to get the simulator response message.

Note

The Alerts page and GET /merchantResults responses indicate the platform is Vantiv. However, VCore simulators can only be triggered by EIN values.

Simulator Examples

The following API examples demonstrate how simulators respond after being activated by a zip or ein trigger from the request.

Vantiv: Denied Boarding Status

In this example, the zip value provided is 55555, which triggers the Vantiv simulator for a Denied boarding status update:

BASH

POST /entities HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

JSON

{
    "type": 2,
    "name": "My Merchant",
    "address1": "12345 Address Ave",
    "address2": null,
    "city": "New York",
    "state": "NY",
    "zip": "55555",
    "country": "USA",
    "phone": "5555555555",
    "fax": null,
    "email": "Go.Avs@testmail.com",
    "ein": "123456789",
    "website": "http://testwebsite.com",
    "tcVersion": "1.0",
    "currency": "USD",
    "accounts": [
        {
            "primary": "1",
            "currency": "USD",
            "account": {
                "method": "8",
                "number": "1234567890",
                "routing": "122000661"
            }
        }
    ],
    "merchant": {
        "dba": null,
        "new": "1",
        "mcc": "1799",
        "status": "1",
        "members": [
            {
                "title": "CEO",
                "first": "John",
                "middle": null,
                "last": "Doe",
                "ssn": null,
                "dob": "20000101",
                "dl": "0123456789",
                "dlstate": "NY",
                "ownership": 10000,
                "email": "john@testmail.com",
                "fax": null,
                "phone": "5626446130",
                "primary": "1",
                "address1": "123 Address Ave",
                "address2": null,
                "city": "New York",
                "state": "MD",
                "zip": "12345",
                "country": "USA"
            }
        ]
    }
}

The following response body displays the standard new Merchant creation response with an immediate status update to "status": 4 (Denied):

JSON

{
    "response": {
        "data": [
            {
                "id": "t1_mer_123abc4d567890efg1h2i34",
                "created": "2025-05-22 18:44:30.4315",
                "modified": "2025-05-22 18:44:36.0056",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "t1_log_123abc4d567890efg1h2i34",
                "lastActivity": null,
                "entity": "t1_ent_123abc4d567890efg1h2i34",
                "dba": null,
                "new": 1,
                "established": null,
                "annualCCSales": 0,
                "avgTicket": 0,
                "amex": null,
                "discover": null,
                "mcc": "1799",
                "status": 4,
                "boarded": null,
                "inactive": 0,
                "frozen": 0,
                "environment": "cardPresent",
                "visaMvv": null,
                "chargebackNotificationEmail": null,
                "statusReason": null,
                "totalApprovedSales": 0,
                "autoBoarded": 1,
                "saqType": null,
                "saqDate": null,
                "qsa": null,
                "letterStatus": 0,
                "letterDate": null,
                "tcAttestation": 0,
                "visaDisclosure": 0,
                "disclosureIP": null,
                "disclosureDate": null,
                "accountClosureReasonCode": null,
                "accountClosureReasonDate": null,
                "annualCCSaleVolume": null,
                "annualACHSaleVolume": null,
                "riskLevel": null,
                "creditRatio": null,
                "creditTimeliness": null,
                "chargebackRatio": null,
                "ndxDays": null,
                "ndxPercentage": null,
                "advancedBilling": null,
                "locationType": null,
                "percentKeyed": null,
                "totalVolume": null,
                "percentEcomm": null,
                "seasonal": null,
                "amexVolume": null,
                "incrementalAuthSupported": null,
                "tmxSessionId": null,
                "percentBusiness": null,
                "applePayActive": 0,
                "applePayStatus": null,
                "googlePayActive": 1,
                "passTokenEnabled": null,
                "naics": null,
                "naicsDescription": null,
                "expressBatchCloseMethod": null,
                "expressBatchCloseTime": null
            }
        ],
        "details": {
            "requestId": 1,
            "totals": [],
            "page": {
                "current": 1,
                "last": 1,
                "hasMore": false
            }
        },
        "errors": []
    }
}

After the new test Merchant is created, query GET /merchantResults with a SEARCH: merchant[equals]={id} header using the new Merchant’s ID to get the simulated platform response message:

BASH

GET /merchantResults HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
SEARCH: merchant[equals]={merchantId}

The following response body shows the simulated error message simulating the Vantiv Platform failed boarding this merchant platform error response:

JSON

{
  "response": {
    "data": [
      {
        "id": "t1_mrt_123abc4d567890efg1h2i34",
        "created": "2025-05-27 19:00:06.2325",
        "modified": "2025-05-27 19:00:06.2325",
        "creator": "t1_log_123abc4d567890efg1h2i34",
        "modifier": "t1_log_123abc4d567890efg1h2i34",
        "merchant": "t1_mer_123abc4d567890efg1h2i34",
        "type": "platform",
        "platform": "VANTIV",
        "message": "Platform failed boarding this merchant",
        "boardingProcessID": "1ab2cd3e-4f5g-6h7i-8901-2abcde34f567"
      }
    ],
    "details": {
      "requestId": 1,
      "totals": [],
      "page": {
        "current": 1,
        "last": 1,
        "hasMore": false
      }
    },
    "errors": []
  }
}

VCore: Denied Boarding Status

In this example, the ein value provided is 23-4567890, which triggers the VCore simulator for a Denied boarding status update:

BASH

POST /entities HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

JSON

{
    "type": 2,
    "name": "My Merchant",
    "platform": "VCORE",
    "address1": "12345 Address Ave",
    "address2": null,
    "city": "New York",
    "state": "NY",
    "zip": "55555",
    "country": "USA",
    "phone": "5555555555",
    "fax": null,
    "email": "Go.Avs@testmail.com",
    "ein": "234567890",
    "website": "http://testwebsite.com",
    "tcVersion": "1.0",
    "currency": "USD",
    "accounts": [
        {
            "primary": "1",
            "currency": "USD",
            "account": {
                "method": "8",
                "number": "1234567890",
                "routing": "122000661"
            }
        }
    ],
    "merchant": {
        "dba": null,
        "new": "1",
        "mcc": "1799",
        "status": "1",
        "members": [
            {
                "title": "CEO",
                "first": "John",
                "middle": null,
                "last": "Doe",
                "ssn": null,
                "dob": "20000101",
                "dl": "0123456789",
                "dlstate": "NY",
                "ownership": 10000,
                "email": "john@testmail.com",
                "fax": null,
                "phone": "5626446130",
                "primary": "1",
                "address1": "123 Address Ave",
                "address2": null,
                "city": "New York",
                "state": "MD",
                "zip": "12345",
                "country": "USA"
            }
        ]
    }
}

The following response body displays the standard new Merchant creation response with an immediate status update to "status": 4 (Denied):

JSON

{
    "response": {
        "data": [
            {
                "id": "t1_mer_123abc4d567890efg1h2i34",
                "created": "2025-05-22 18:44:30.4315",
                "modified": "2025-05-22 18:44:36.0056",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "t1_log_123abc4d567890efg1h2i34",
                "lastActivity": null,
                "entity": "t1_ent_123abc4d567890efg1h2i34",
                "dba": null,
                "new": 1,
                "established": null,
                "annualCCSales": 0,
                "avgTicket": 0,
                "amex": null,
                "discover": null,
                "mcc": "1799",
                "status": 4,
                "boarded": null,
                "inactive": 0,
                "frozen": 0,
                "environment": "cardPresent",
                "visaMvv": null,
                "chargebackNotificationEmail": null,
                "statusReason": null,
                "totalApprovedSales": 0,
                "autoBoarded": 1,
                "saqType": null,
                "saqDate": null,
                "qsa": null,
                "letterStatus": 0,
                "letterDate": null,
                "tcAttestation": 0,
                "visaDisclosure": 0,
                "disclosureIP": null,
                "disclosureDate": null,
                "accountClosureReasonCode": null,
                "accountClosureReasonDate": null,
                "annualCCSaleVolume": null,
                "annualACHSaleVolume": null,
                "riskLevel": null,
                "creditRatio": null,
                "creditTimeliness": null,
                "chargebackRatio": null,
                "ndxDays": null,
                "ndxPercentage": null,
                "advancedBilling": null,
                "locationType": null,
                "percentKeyed": null,
                "totalVolume": null,
                "percentEcomm": null,
                "seasonal": null,
                "amexVolume": null,
                "incrementalAuthSupported": null,
                "tmxSessionId": null,
                "percentBusiness": null,
                "applePayActive": 0,
                "applePayStatus": null,
                "googlePayActive": 1,
                "passTokenEnabled": null,
                "naics": null,
                "naicsDescription": null,
                "expressBatchCloseMethod": null,
                "expressBatchCloseTime": null
            }
        ],
        "details": {
            "requestId": 1,
            "totals": [],
            "page": {
                "current": 1,
                "last": 1,
                "hasMore": false
            }
        },
        "errors": []
    }
}

After the new test Merchant is created, query GET /merchantResults with a SEARCH: merchant[equals]={id} header using the new Merchant’s ID to get the simulated platform response message:

BASH

GET /merchantResults HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
SEARCH: merchant[equals]={merchantId}

The following response body shows the simulated error message simulating the Vantiv “Platform failed boarding this merchant” platform error response:

JSON

{
  "response": {
    "data": [
      {
        "id": "t1_mrt_123abc4d567890efg1h2i34",
        "created": "2025-05-27 19:00:06.2325",
        "modified": "2025-05-27 19:00:06.2325",
        "creator": "t1_log_123abc4d567890efg1h2i34",
        "modifier": "t1_log_123abc4d567890efg1h2i34",
        "merchant": "t1_mer_123abc4d567890efg1h2i34",
        "type": "platform",
        "platform": "VANTIV",
        "message": "Platform failed boarding this merchant",
        "boardingProcessID": "1ab2cd3e-4f5g-6h7i-8901-2abcde34f567"
      }
    ],
    "details": {
      "requestId": 1,
      "totals": [],
      "page": {
        "current": 1,
        "last": 1,
        "hasMore": false
      }
    },
    "errors": []
  }
}