V2 API Migration guide

Starting in early December 2023 customers can migrate to a v2 version of the Branch API, which includes changes to the disbursement endpoints, providing additional parameters that give you more fine-tune control over disbursements.

Both the v1 and v2 API endpoints are documented in detail in the API reference section.

Example Migration Reference

To make things easy, we've created an infographic as a quick visual reference demonstrating some differences between v1 and v2. This infographic covers the endpoint migration from Create Disbursement V1 to Create Disbursement V2. We will be adding more endpoints to the graphic in the coming days.

Usage and best practices for migration

As you can see in the reference documentation and the infographic above, the Branch v2 API endpoints can be identified by urls that begin with v2.

v2/organizations/:orgId/workers/:workerId/disbursements

The documentation shows these new urls and the parameters for both requests and responses when using v2, and the infographic highlights the differences between v1 and v2, to help you adjust your integration to adapt to v2. The tables below provide explanations of new and changed parameters. For a complete reference view of the parameters see the diagrams above.

Create Disbursement: Request

New Parameters

display_header_label

Allows your org to customize the first line in a user's transaction view by passing through a string of your choice. This is an optional parameter.

Changed Parameters

POST v2/organizations/:orgId/workers/:workerId/disbursements

"employee" changed to "worker" in all V2 disbursement endpoints.

Create Disbursement: Response

New Parameters

display_header_label

A description of the disbursement, see request section above for details.

payout

Since payments are no longer always sent to a worker's wallet, payout parameters were added to enable orgs to get more information about how, when, and in what amount a payment was sent.

id
payment_type
amount
fee
time_completed

Migrating the Disbursement reason_code

V1 Reason CodeMapped V2 Reason Code
PENDINGPAYOUT_PENDING
WORKER_NOT_FOUNDWORKER_NOT_FOUND
WORKER_NOT_MATCHEDPAYMENT_PROFILE_NOT_FOUND
WALLET_NOT_FOUNDPAYMENT_PROFILE_NOT_FOUND
WALLET_SUSPENDEDPAYMENT_PROFILE_SUSPENDED
WALLET_NOT_ACTIVEPAYMENT_PROFILE_NOT_ACTIVE
N / APAYMENT_PROFILE_FRAUDULENT
TRANSFER_FAILEDTRANSFER_FAILED
AMOUNT_ZEROAMOUNT_ZERO
AMOUNT_TOO_LARGEAMOUNT_EXCEEDS_ORG_SINGLE_DISBURSEMENT_LIMIT
DAILY_DISBURSEMENT_LIMIT_METAMOUNT_EXCEEDS_ORG_DAILY_DISBURSEMENT_LIMIT
WORKERS_DAILY_LIMIT_METAMOUNT_EXCEEDS_WORKER_DAILY_DISBURSEMENT_LIMIT
AMOUNT_DOES_NOT_COVER_FEESAMOUNT_DOES_NOT_COVER_USER_FEES
INVOICING_FAILEDUNEXPECTED_ERROR
RETRY_PERIOD_ELAPSEDRETRY_PERIOD_ELAPSED
LIKELY_MATCH_FOUNDLIKELY_MATCH_FOUND
UNEXPECTED_ERRORUNEXPECTED_ERROR