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.

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



(Click to enlarge)

Get Started Get Started Get Started

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
Changed Parameters
statusCREATED changed to PENDING to more accurately reflect the status at this stage.
reason code
WALLET_NOT_FOUND

WALLET_NOT_MATCHED

WALLET_SUSPENDED

WALLET_NOT_ACTIVE


Generalized for both wallet and card:


PAYMENT_PROFILE_NOT_FOUND

PAYMENT_PROFILE_SUSPENDED

PAYMENT_PROFILE_NOT_ACTIVE

PAYMENT_PROFILE_FRAUDULENT
reason code
AMOUNT_TOO_LARGE

DAILY_DISBURSEMENT_LIMIT_MET

WORKERS_DAILY_LIMIT_MET

AMOUNT_DOES_NOT_COVER_FEES


For consistency and other internal structural reasons these are now:


AMOUNT_EXCEEDS_ORG_SINGLE_DISBURSEMENT_LIMIT

AMOUNT_EXCEEDS_ORG_DAILY_DISBURSEMENT_LIMIT

AMOUNT_EXCEEDS_WORKER_DAILY_DISBURSEMENT_LIMIT

AMOUNT_DOES_NOT_COVER_USER_FEES

Updated 9 days ago