Payouts Sandbox Simulator

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" for POST /payouts requests.

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 message response parameter for GET /disbursements?expand[disbursementResults] requests.

Note

The API usage process is the same for merchants and partners using the POST /payouts endpoint. 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:

CODE

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

JSON

{
    "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:

JSON

{
    "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):

JSON

 {
    "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": []
    }
}