Testing Disbursements

Overview

Testing disbursements using the Sandbox can verify implementation functionality to ensure robustness when performing Disbursement Error Handling.

Check the handling of various HTTP Codes, reason_code values, and status values using Mock Responses generated directly by Branch. No effect will be applied to sandbox wallet funds.
Invoke integration tests of the Branch Direct Sandbox Debit Card's TabaPay dependency by using specific Test Amounts. No effect will be applied to sandbox debit card funds.

🚧
Prerequisite: Onboard a Worker in Sandbox
Follow instructions provided by your Account Manager to create sample workers in the sandbox for testing disbursements to Branch Wallet and Branch Direct. Use the provided dummy phone numbers and debit card numbers to properly configure the sandbox accounts.

Disbursement Mock Responses

The Create Disbursement metadata field has special handling in the Sandbox environment depending on the value associated with a mock_response key at the top level.

Upon providing a value to metadata.mock_response, the resulting disbursement will contain corresponding mock values for status, reason_code, and HTTP Response Code.

Example Disbursement Request Body and associated Mock Response

{
  "worker_id": "123456",
  "external_id": "7de69037-c2ca-4214-99a7-fc76a73642c1",
  "type": "PAYCHECK",
  "amount": 500,
  "description": "Deposit Test",
  "metadata": {
    "mock_response": "LIKELY_MATCH_FOUND"
  }
}

{
  "worker_id": "123",
  "amount": 500,
  "external_id": "7de69037-c2ca-4214-99a7-fc76a73642c1",
  "type": "PAYCHECK",
  "worker_group": "Store #1",
  "description": "Deposit Test",
  "display_header_label": "Paycheck",
  "display_sub_label": "Pizza Delivery Company",
  "status": "SKIPPED",
  "reason_code": "LIKELY_MATCH_FOUND",
  "payout": {
    "id": "123",
    "payment_type": "WALLET",
    "amount": 500,
    "fee": 100,
    "org_paid_fee": 50,
    "time_completed": "2025-07-16T22:37:20.000Z"
  },
  "metadata": {
    "mock_response": "LIKELY_MATCH_FOUND"
  },
  "time_created": "2025-07-16T22:37:30.301Z",
  "time_modified": "2025-07-16T22:37:30.301Z"
}

Generated Response Values for mock_response

mock_response	Reason Code	Status	HTTP
`AMOUNT_ZERO`	`AMOUNT_ZERO`	`COMPLETED`	`201`
`RETRY_PERIOD_ELAPSED`	`RETRY_PERIOD_ELAPSED`	`SKIPPED`	`200`
`RETRY_LIMIT_EXCEEDED`	`RETRY_LIMIT_EXCEEDED`	`SKIPPED`	`200`
`LIKELY_MATCH_FOUND`	`LIKELY_MATCH_FOUND`	`SKIPPED`	`200`
`WORKER_NOT_FOUND`	`WORKER_NOT_FOUND`	`FAILED`	`202`
`PAYMENT_PROFILE_NOT_FOUND`	`PAYMENT_PROFILE_NOT_FOUND`	`FAILED`	`202`
`PAYMENT_PROFILE_SUSPENDED`	`PAYMENT_PROFILE_SUSPENDED`	`FAILED`	`202`
`PAYMENT_PROFILE_NOT_ACTIVE`	`PAYMENT_PROFILE_NOT_ACTIVE`	`FAILED`	`202`
`PAYMENT_PROFILE_FRAUDULENT`	`PAYMENT_PROFILE_FRAUDULENT`	`FAILED`	`202`
`TRANSFER_FAILED`	`TRANSFER_FAILED`	`FAILED`	`202`
`AMOUNT_EXCEEDS_ORG_` `SINGLE_DISBURSEMENT_LIMIT`	`AMOUNT_EXCEEDS_ORG_` `SINGLE_DISBURSEMENT_LIMIT`	`FAILED`	`202`
`AMOUNT_EXCEEDS_ORG_` `DAILY_DISBURSEMENT_LIMIT`	`AMOUNT_EXCEEDS_ORG_` `DAILY_DISBURSEMENT_LIMIT`	`FAILED`	`429`
`AMOUNT_EXCEEDS_WORKER_` `DAILY_DISBURSEMENT_LIMIT`	`AMOUNT_EXCEEDS_WORKER_` `DAILY_DISBURSEMENT_LIMIT`	`FAILED`	`202`
`AMOUNT_DOES_NOT_` `COVER_USER_FEES`	`AMOUNT_DOES_NOT_` `COVER_USER_FEES`	`FAILED`	`202`
`UNEXPECTED_ERROR`	`UNEXPECTED_ERROR`	`FAILED`	`202`
`PAYOUT_PENDING`	`PAYOUT_PENDING`	`PENDING`	`202`
`SCHEDULED`	null	`SCHEDULED`	`201`
`DUPLICATE_SCHEDULED`	null	`SCHEDULED`	`200`
`COMPLETED`	null	`COMPLETED`	`201`
`DUPLICATE_COMPLETED`	null	`COMPLETED`	`200`
`CANCELED`	null	`CANCELED`	`200`
`BAD_REQUEST`	null	null	`400`
`INTERNAL_SERVER_ERROR`	null	null	`500`

Test Payments to Branch Wallet in Sandbox

Any amounts can be used when testing disbursements to the Branch Wallet.

Test Payments to Branch Direct Debit Card in Sandbox

When testing Disbursements to Branch Direct users in the Branch sandbox, the TabaPay sandbox debit card backend will generate different scenarios depending on the net amount disbursed. For more detailed information about this behavior, visit here.

Test Amount Calculation

The testing amounts which trigger the following scenarios are derived by subtracting the fee from the total Disbursement.

Test Case Amount = Total Disbursement - Fee
(e.g. $0.02 amount = $2.02 total - $2.00 fee)

Testing Scenarios

Amount $0.01 will return a transaction error
Amount $0.02 will return an unknown processing failure
Amounts $0.03 and $0.04 will complete after pending for up to 40 seconds
Amounts from $0.05 to $0.25 will succeed
Amounts greater than $0.25 will exceed the max transaction limit for testing
The daily limit for total testing amounts is $10.00 per test card