Payout Merchants

Your platform must deliver Payout management UIs to merchants who were not onboarded with access to the WePay Merchant Center. At a high-level, delivering Payout UIs requires the following capabilities:

Create Payout Methods
Tie Payout Methods to merchants' WePay Accounts
Get API Notifications when a Payout is automatically created
Allow merchants to update their Payout Method details and preferences

Create a Payout Method

Now that you understand how to payout merchants, let's walk through how to build your Payout flow. Be sure to grab your merchant's Legal Entity ID and Account ID from the Onboard Merchants section. Like the previous two articles, we recommend using the Tokenization strategy for collecting sensitive information, like a merchant's payment bank information.

First, we'll need to make sure that the merchant's Legal Entity and Account have all the necessary information to enable Payouts. As a reminder, we had to add extra information to begin processing payments; similar information is required to send payouts. Start by doing the following:

GET /legal_entities/{id}/verifications

You'll notice what information is missing before the Legal Entity can enable payouts. In order to fully unlock payouts, the information documented at Enable Payouts needs to be provided.

Once that is completed, send the equivalent call for Accounts:

GET /accounts/{id}/capabilities

If you successfully added the missing Legal Entity information, you'll see the Payouts section enabled to true in the Accounts response. If you don't, use the response to fill in information to update the Legal Entity and Account.

Let's now collect Payout Information for merchants. We'll start with the front end, where a merchant will enter their payout bank information. In your UI, be sure to collect the payer's decision to use a bank account for use later in this process. You'll want to create fields that capture the information below, using the Tokenization JS library:

Copy

Copied

WePay.tokens.create({
"resource": "payout_methods",
"payout_methods": {
  		"type": "payout_bank_us",
    		"payout_bank_us": {
    			"account_number": "12345678",
"routing_number": "021000021",
			"account_type": "checking"
}
  	}
}, {}, function(response) {
  console.log(response);
});

This will return a token. Using the token, create a Payout Method by sending a POST /payout_methods request, similar to the one below. The field nickname should not contain any sensitive data, such as any part of the bank account number other than the last 4 digits.

Copy

Copied

curl -X POST \
  --url 'https://stage-api.wepay.com/payout_methods' \
  -H 'Accept: application/json'\
  -H 'App-Id: {your-app-id}'\
  -H 'App-Token: {your-app-token}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
	"legal_entity_id": "{YOUR-LEGAL-ENTITY-ID-HERE}",
	"nickname": "Test Payout Account",
	"token": {
		"id": "payout_methods-88ae04ca-0983-468b-9ca6-2ce18b66dafb"
	}
}'

We've provided a sample UI to simulate creating and tokenizing a Payout Method, see below. This UI example allows a merchant to provide their Payout bank information, in which a Payout Method token will be created and returned.

At this point, the API will return a Payout Method ID, which is linked to a Legal Entity. Keep reference to the Payout Method ID, as we'll connect it back to an Account, and attach a Payout schedule.

Note

If a duplicate Payout Method is created (i.e. identical account number, routing number, and nick name), a new Payout Method ID will be returned. On the back end, the original and new Payout Method ID(s) will point to the same object. Put into practice, this means you should fetch Payouts based on the merchant's Account ID instead of Payout Method ID if they have multiple Payout Methods associated with their Legal Entity.

Attach a Payout Method to a Merchant Account

With a Payout Method ID handy, it's time to connect an Account. First, determine which payout periods you will offer to your merchants. Note that it is a legal requirement to offer the same selection to all of your merchants. We currently support daily, weekly, and monthly payout schedules for bank account Payout Methods.

Once your Payout period offerings are established and selected by your merchant, either update the merchants existing Account by sending a POST /account/id request or create their Account if not previously done by sending a POST /accounts request. Our example below assumes that the merchant already has an API Account:

Copy

Copied

curl -X POST \
  --url 'https://stage-api.wepay.com/accounts/id' \
  -H 'Accept: application/json'\
  -H 'App-Id: {your-app-id}'\
  -H 'App-Token: {your-app-token}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "payout": {
    "currencies": {
      "USD": {
        "payout_method_id": "{YOUR-PAYOUT-METHOD-ID}",
        "period": "weekly"
      }
    }
  }
}'

In case the account accepts multiple currencies, you will need to create multiple Payout Methods for each currency.

Remove a Payout Method from a Merchant Account

If a Payout Method ever needs to be removed from an Account (i.e. if the merchant submitted incorrect banking info but hasn't located the correct info yet), it's possible to remove the payout method by updating the account with a POST /account/id request like this:

Copy

Copied

{
  "payout": {
    "currencies": {
      "USD": null
    }
  }
}

Reconcile Payouts

As a WePay partner using the Clear product with custom components, you are required to build out reporting for your merchants. The simplest way to provide reconciliation reports is outlined here:

First, send a GET /payouts API request with the query parameter owner_id. The value here will be the merchant's Account ID. The response body will contain an array of Payouts for that Account.

Note that, if not provided, the create_time_start query parameter defaults to 7 days in the past, and the create_time_end query parameter defaults to the time of the request. Additionally, the delta between create_time_start and create_time_end cannot exceed 35 days.

Next, compile a report containing all transactional resources (Payments, Refunds, Disputes, Adjustments, Recoveries, and Payouts) in chronological order.

To read more about building out reports for your merchants, take a look at our Reporting article.

Questions? Need help? Visit our support page!