Use payout simulators to troubleshoot issues with available balance payouts to linked bank accounts in a controlled environment. By simulating payout errors and edge cases, you can prepare steps for handling potential errors in the Sandbox before going live.
Activate Payout Simulators
You can activate each payout simulator with a corresponding payout amount, called a trigger.
Unlike other simulators, all payout simulator triggers work on both Vantiv and VCore platforms for seamless cross-platform payout response simulation.
Set Your Simulator Trigger
You can set trigger amounts for payout simulators using different methods:
Portal: The Amount field with an Actual Amount Type in the Schedule Payout creation dialog on the Payout Schedules page.
API: The amount parameter with
"um": "2"forPOST /payoutsrequests.
Important!
Format all amounts as integers for API and integrated payment pages. Omit decimal points in transaction requests. For example, $101.25 should be formatted as
10125.
Review the Simulator Response Message
When triggering the payout simulator with a relevant amount, an artificial platform response is returned with a message explaining the reason.
To find the platform payout simulator response messages:
Portal: Access the Alerts section of the Payout Details page.
API: Review the
messageresponse parameter forGET /disbursements?expand[disbursementResults]requests.
Note
The API usage process is the same for merchants and partners using the
POST /payoutsendpoint. However, the portal’s page titles and labels differ, where Partners see Withdrawals and Merchants see Payouts.
Trigger Simulators
To trigger a payout simulator:
Use the Payout Schedules page or build a POST /payouts request.
Use one of the following trigger values for the Amount parameter to simulate a potential Vantiv and VCore platform payout processing error:
Trigger Amount
Simulator Response Message
Failure Code
$101.25
Insufficient funds in account.
R01
$201.26
Account is closed.
R02
$301.27
No account on file.
R03
$401.28
Invalid account number.
R04
$501.29
Unauthorized debit to consumer account.
R05
$601.31
Returned at request of ODFI.
R06
Submit the new Payout Schedule or POST /payouts request.
Result: The payout simulator returns the platform simulator response message aligned with the amount.
Simulator Examples
The following API examples demonstrate how payout simulators respond when activated by an amount (Amount) trigger.
Insufficient Funds Simulator
In this example, the amount provided is $101.25, which triggers the simulator for an “Insufficient Funds” payout error response. The following request body sets the amount to trigger the simulator:
POST /payouts HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}{
"entity": "t1_ent_123abc4d567890efg1h2i34",
"account": "12a345b6c7890d12ef3456g789012h34",
"name": "Operating Account Deposit 1",
"amount": "10125",
"schedule": "5",
"start": "20250527",
"um": "2"
}The successful request returns the standard new payout creation response:
{
"response": {
"data": [
{
"id": "t1_pay_123abc4d567890efg1h2i34",
"created": "2025-05-27 14:54:21.4232",
"modified": "2025-05-27 14:54:21.4232",
"creator": "t1_log_123abc4d567890efg1h2i34",
"modifier": "t1_log_123abc4d567890efg1h2i34",
"login": "t1_log_123abc4d567890efg1h2i34",
"account": "12a345b6c7890d12ef3456g789012h34",
"entity": "t1_ent_123abc4d567890efg1h2i34",
"payoutFlow": null,
"name": "Operating Account Deposit 1",
"description": "",
"schedule": "5",
"scheduleFactor": 1,
"start": "20250527",
"currency": "USD",
"um": "2",
"amount": 10125,
"minimum": null,
"float": 0,
"skipOffDays": "0",
"inactive": 0,
"frozen": 0,
"sameDay": 0,
"maximum": null,
"billing": null,
"secondaryDescriptor": null
}
],
"details": {
"requestId": 1
},
"errors": []
}
}After the new test payout is created, query GET /disbursements?expand[disbursementResults][] with a SEARCH: payout[equals]={payoutId} header using the new payout ID. This query gets the simulated “Insufficient Funds” platform response message and associated failure code (originalCode):
{
"response": {
"data": [
{
"disbursementResults": [
{
"id": "t1_drt_123abc4d567890efg1h2i34",
"created": "2025-05-27 18:42:20.9381",
"modified": "2025-05-27 18:42:20.9381",
"creator": "000000000000001",
"modifier": "000000000000001",
"disbursement": "t1_dbm_123abc4d567890efg1h2i34",
"code": "platform",
"platform": null,
"message": "Insufficient funds",
"disbursementRef": null,
"amount": null,
"data": null,
"originalCode": "R01"
},
{
"id": "t1_drt_234abc6d789012efg3h4i56",
"created": "2025-05-27 18:42:20.9202",
"modified": "2025-05-27 18:42:20.9202",
"creator": "000000000000001",
"modifier": "000000000000001",
"disbursement": "t1_dbm_123abc4d567890efg1h2i34",
"code": "general",
"platform": null,
"message": "Disbursement reversed",
"disbursementRef": "t1_drf_68363fccdc384e6c24024ab",
"amount": 10125,
"data": null,
"originalCode": null
},
{
"id": "t1_drt_345abc6d789012efg3h4i56",
"created": "2025-05-27 18:23:49.7101",
"modified": "2025-05-27 18:23:49.7101",
"creator": "000000000000001",
"modifier": "000000000000001",
"disbursement": "t1_dbm_123abc4d567890efg1h2i34",
"code": "transferDetails",
"platform": "VANTIV",
"message": "Disbursement trace details",
"disbursementRef": null,
"amount": 10125,
"data": null,
"originalCode": null
}
],
"id": "t1_dbm_123abc4d567890efg1h2i34",
"created": "2025-05-27 18:23:35.5902",
"modified": "2025-05-27 18:42:20.9419",
"creator": "000000000000001",
"modifier": "000000000000001",
"entity": "t1_ent_123abc4d567890efg1h2i34",
"account": "12a345b6c7890d12ef3456g789012h34",
"payout": "t1_pay_123abc4d567890efg1h2i34",
"funding": null,
"description": "Disbursement for payout t1_pay_123abc4d567890efg1h2i34",
"amount": 10125,
"status": 4,
"processed": null,
"currency": "USD",
"platform": null,
"payment": "t1_pmt_123abc4d567890efg1h2i34",
"approvedAmount": null,
"expiration": null,
"sameDay": 0,
"returnedAmount": null,
"originalDisbursement": null,
"statement": null,
"settlement": null,
"lastNegativeEntry": null,
"lastNegativePendingEntry": null,
"lastPositiveReserveEntry": null,
"disbursementEntriesStatus": "pending",
"lastPositiveEntry": null,
"lastPositivePendingEntry": null,
"lastNegativeReserveEntry": null,
"fundingStatus": "pending",
"secondaryDescriptor": null
}
],
"details": {
"requestId": 1,
"totals": [],
"page": {
"current": 1,
"last": 1,
"hasMore": false,
"disbursementResults": {
"current": 1,
"last": 1,
"hasMore": false
}
}
},
"errors": []
}
}