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 /entitiesrequests.
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
statusresponse parameter forPOST /entitiesrequests and queryGET /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 /entitiesrequest.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 /entitiesrequest.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 /entitiesrequest.Verify the Merchant’s boarding status:
Portal: The Boarding Status field in the Business menu Account tab on the Merchant Profile page.
API: The
statusresponse parameter for the initialPOST /entitiesrequest.
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 /merchantResultsresponses 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:
POST /entities HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}{
"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": "[email protected]",
"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": "[email protected]",
"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):
{
"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:
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:
{
"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:
POST /entities HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}{
"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": "[email protected]",
"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": "[email protected]",
"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):
{
"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:
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:
{
"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": []
}
}