Braintree Marketplace

Onboarding Sub-merchantsanchor

availability

If you're a new merchant looking for a marketplace solution, contact our Sales team.

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.

Full exampleanchor

Below is an example of a Merchant Account: Create call. Unless specified otherwise in the parameters section below, all fields are required.

  1. PHP
$merchantAccountParams = [
  'individual' => [
    'firstName' => 'Jane',
    'lastName' => 'Doe',
    'email' => 'jane@14ladders.com',
    'phone' => '5553334444',
    'dateOfBirth' => '1981-11-19',
    'ssn' => '456-45-4567',
    'address' => [
      'streetAddress' => '111 Main St',
      'locality' => 'Chicago',
      'region' => 'IL',
      'postalCode' => '60622'
    ]
  ],
  'business' => [
    'legalName' => 'Jane's Ladders',
    'dbaName' => 'Jane's Ladders',
    'taxId' => '98-7654321',
    'address' => [
      'streetAddress' => '111 Main St',
      'locality' => 'Chicago',
      'region' => 'IL',
      'postalCode' => '60622'
    ]
  ],
  'funding' => [
    'descriptor' => 'Blue Ladders',
    'destination' => BraintreeMerchantAccount::FUNDING_DESTINATION_BANK,
    'email' => 'funding@blueladders.com',
    'mobilePhone' => '5555555555',
    'accountNumber' => '1123581321',
    'routingNumber' => '071101307'
  ],
  'tosAccepted' => true,
  'masterMerchantAccountId' => "14ladders_marketplace",
  'id' => "blue_ladders_store"
];
$result = $gateway->merchantAccount()->create($merchantAccountParams);

Parametersanchor

Individual parametersanchor

individual parameters are always required when creating a sub-merchant, even if you are also providing information for a registered company under business

  • phone is optional.
  • ssn is required if the sub-merchant is not a registered business. You must provide the full 9 digit Social Security Number in this field. For background, generally businesses use an EIN, while sole proprietors and individuals will use a Social Security Number.

Business parametersanchor

  1. PHP
'business' => [
      'legalName' => 'Jane's Ladders',
      'dbaName' => 'Jane's Ladders',
      'taxId' => '98-7654321',
      'address' => [
        'streetAddress' => '111 Main St',
        'locality' => 'Chicago',
        'region' => 'IL',
        'postalCode' => '60622'
      ]
    ],

If the sub-merchant you are onboarding is a registered company, the Merchant Account: 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:

  • legal_name and tax_id are both required if the sub-merchant is a registered business.
  • All other parameters shown in the example above are optional.

Funding parametersanchor

  1. PHP
'funding' => [
      'destination' => BraintreeMerchantAccount::FUNDING_DESTINATION_BANK,
      'email' => 'funding@blueladders.com',
      'mobilePhone' => '5555555555',
      'accountNumber' => '1123581321',
      'routingNumber' => '071101307'
    ],

This is the funding information for the sub-merchant. The parameters you must specify in your `Merchant Account: Create call to disburse funds to a bank account include:

  • destination is required, and the value must be bank.
  • account_number and routing_number are 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 destination is anything other than bank.
  • email and mobile_phone are both optional.
  • descriptor is optional. This field sets the description that will appear on the sub-merchant's deposits from Braintree when destination is set to bank.
    • 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.

availability

Venmo funding destinations are no longer supported for new merchants. Contact us with questions or concerns.

important

We do not verify that bank account details are correct, so if there is an error with the final disbursement, you will be notified with a disbursement exception webhook and the funds will be held until the details are updated.

Terms of service accepted parameteranchor

  1. PHP
'tosAccepted' => true

tos_accepted 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, 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 Customer Success team.

Master merchant account ID parameteranchor

  1. PHP
'masterMerchantAccountId' => "14ladders_marketplace"

master_merchant_account_id 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:

  1. Log into either the production Control Panel or the sandbox Control Panel, depending on which environment you are working in
  2. Click on the gear icon in the top right corner
  3. Click Business from the drop-down menu

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.

important

If you're testing in the sandbox, be sure to change the master_merchant_account_id when moving to production.

ID parameteranchor

  1. PHP
'id' => "blue_ladders_store"

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.

Result handlinganchor

Assuming that your Merchant Account: Create call is valid, it will return a Braintree result object like this one:

  1. PHP
$result = $gateway->merchantAccount()->create(merchantAccountParams);
$result->success;
// true
$result->merchantAccount->status;
// "pending"
$result->merchantAccount->id;
// "blue_ladders_store"
$result->merchantAccount->masterMerchantAccount->id;
// "14ladders_marketplace"
$result->merchantAccount->masterMerchantAccount->status;
// "active"

This confirms:

  • 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.

See alsoanchor


Next Page: Confirmation →