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 wallets.
Invoke integration tests of the Branch Direct Sandbox Debit Card's TabaPay dependency by using specific Test Amounts. These will result in sandbox "money" movement.

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. These Mock Response values are generated directly by Branch

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"
}

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`

Branch Direct Sandbox Debit Card

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