The master merchant must onboard each individual sub-merchant. The onboarding process consists of creating a merchant account on behalf of the sub-merchant and confirming the creation of this merchant account.
You'll need to gather certain information from each sub-merchant in order to create their merchant account. This will allow transactions to be processed through their account and funds to be disbursed to them directly. You can find a full example and list of parameters below.
MerchantAccountRequest request = new MerchantAccountRequest() .individual() .firstName("Jane") .lastName("Doe") .email("firstname.lastname@example.org") .phone("5553334444") .dateOfBirth("1981-11-19") .ssn("456-45-4567") .address() .streetAddress("111 Main St") .locality("Chicago") .region("IL") .postalCode("60622") .done() .done() .business() .legalName("Jane's Ladders") .dbaName("Jane's Ladders") .taxId("98-7654321") .address() .streetAddress("111 Main St") .locality("Chicago") .region("IL") .postalCode("60622") .done() .done() .funding() .descriptor("Blue Ladders") .destination(MerchantAccount.FundingDestination.BANK) .email("email@example.com") .mobilePhone("071101307") .accountNumber("1123581321") .routingNumber("071101307") .done() .tosAccepted(true) .masterMerchantAccountId("14ladders_marketplace") .id("blue_ladders_store"); Result<MerchantAccount> result = gateway.merchantAccount().create(request);
individual() parameters are always required when creating a sub-merchant, even if you are also providing information for a registered company under
ssnis optional. You can provide the full Social Security Number or the last 4 digits, or you can leave this field blank. If you provide the last 4 digits, we will use this information in combination with the sub-merchant's other details to attempt to retrieve the full SSN.
business() .legalName("Jane's Ladders") .dbaName("Jane's Ladders") .taxId("98-7654321") .address() .streetAddress("111 Main St") .locality("Chicago") .region("IL") .postalCode("60622") .done() .done()
If the sub-merchant you are onboarding is a registered company, the
MerchantAccount.create() call will also need to include the
business section with legal name, tax ID, address, and (optionally) DBA name. This is in addition to the
individual details because a sub-merchant must always be tied to an individual.
Keep in mind that:
taxIdare both required if either is present.
- All other parameters shown in the example above are optional.
funding() .destination(MerchantAccount.FundingDestination.BANK) .email("firstname.lastname@example.org") .mobilePhone("071101307") .accountNumber("1123581321") .routingNumber("071101307") .done()
This is the funding information for the sub-merchant. The parameters you must specify in your
MerchantAccount.create() call to disburse funds to a bank account include:
destinationis required, and the value must be
routingNumberare required. We'll deposit funds into the bank account associated with the provided account and routing numbers.
- The provided information must be for a checking account.
- These fields must not be sent when
destinationis anything other than
mobilePhoneare both optional.
descriptoris optional. This field sets the description that will appear on the sub-merchant's deposits from Braintree when
destinationis set to
- If not provided, one will be generated based on the individual name, business legal name, or DBA name.
See the reference for full details on all of these fields.
tosAccepted indicates that the sub-merchant has read and agreed to the Braintree Sub-Merchant Terms of Service (TOS). To allow sub-merchants to do this, the following text should be included in your website's Terms of Service for Braintree Marketplace sub-merchants:
"[MSP NAME] uses Braintree, a division of PayPal, Inc. (Braintree) for payment processing services. By using the Braintree payment processing services you agree to the Braintree Payment Services Agreement available at https://www.braintreepayments.com/legal/gateway-agreement, and the applicable bank agreement available at https://www.braintreepayments.com/legal/bank-agreement."
This way, sub-merchants can agree to both your terms and ours simultaneously. If you have questions about the requirements, please contact our Accounts team.
masterMerchantAccountId defines that:
- this new sub-merchant will be nested under this master merchant account
- this master merchant account is the destination for the service fees you charge.
You can find your master merchant account ID in the Control Panel. To get there, log into your sandbox or production account (depending on where you are testing) and navigate to Account > Merchant Account Info. If you do not have a master merchant account ID, you'll need to create one if in sandbox, or contact us if in production.
id is an optional field and allows you to define the sub-merchant ID that you will reference when creating a transaction. If you do not pass an
id when creating a sub-merchant, then one will be generated automatically by Braintree and returned in the result object.
MerchantAccountRequest request = new MerchantAccountRequest(); // append options result.isSuccess(); // true MerchantAccount ma = result.getTarget(); ma.getStatus() == MerchantAccount.Status.PENDING; // true ma.getId(); // "blue_ladders_store" ma.getMasterMerchantAccount().getId(); // "14ladders_marketplace" ma.getMasterMerchantAccount().getStatus() == MerchantAccount.Status.ACTIVE; // true
- that the sub-merchant creation is pending
- what the sub-merchant ID is
- under which master merchant account this sub-merchant is nested
See the page on merchant account result handling for information on how to check for the sub-merchant onboarding status. You'll need this information in order to set up webhooks that allow you to confirm that the sub-merchant was created successfully.
- Braintree Marketplace overview
- Merchant account result handling
- Creating transactions with service fees
Still have questions?
If you can’t find an answer, contact us