availability

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

As part of the sub-merchant onboarding process for Braintree Marketplace, you can confirm the creation of a merchant account as either approved or declined via a webhook. The webhook is triggered after the sub-merchant's information has been verified with several third-party services.

Webhooks allow Braintree to push messages to your servers when you configure a webhook endpoint URL. If you are not using webhooks already, you will need to follow the webhooks guide to get started.

note

The btSignature and btPayload variables in the code snippets below represent parameters received from the webhook POST request. For more information, read the documentation on parsing webhooks.

Sub-merchant approved

Once you have webhooks configured, you can listen for a SubMerchantAccountApproved webhook that looks like this:

Java
Copy
Copied
WebhookNotification notification = gateway.webhookNotification().parse(
  btSignature,
  btPayload
);

notification.getKind() == WebhookNotification.Kind.SUB_MERCHANT_ACCOUNT_APPROVED;
// true
notification.getMerchantAccount().getStatus();
// "active"
notification.getMerchantAccount().getId();
// "blue_ladders_store"
notification.getMerchantAccount().getMasterMerchantAccount().getId();
// "14ladders_marketplace"
notification.getMerchantAccount().getMasterMerchantAccount().getStatus();
// "active"

Once you've confirmed that the new sub-merchant has been successfully onboarded, you can start to run transactions on their account.

Sub-merchant declined

You can also listen for a SubMerchantAccountDeclined webhook that looks like this:

Java
Copy
Copied
WebhookNotification notification = gateway.webhookNotification().parse(
  btSignature,
  btPayload
);

notification.getKind() == WebhookNotification.Kind.SUB_MERCHANT_ACCOUNT_DECLINED;
// true
ValidationErrors errors = notification.getErrors();
for(ValidationError error : errors.getAllDeepValidationErrors()) {
  System.out.println(error.getMessage()); // "Credit score is too low"
}

If it is Declined, the webhook will contain validation errors indicating why the sub-merchant was declined. There are several reasons this can occur:

  • Failed OFAC
  • Failed Mastercard MATCH
  • Failed KYC
  • SSN invalid
  • SSN matches deceased person

See merchant account validations for specific errors.

In this case, we'll need to gather more information about the sub-merchant in order to approve them. Please email our Accounts team with the sub-merchant's first and last name and we’ll be happy to assist.

See also

Next Page: Creating Transactions →