Payout Merchants

At this point, you have successfully created a Merchant account, and processed a payment between a payer and said merchant. All that remains is to pay the Merchant out, and you’ll have completed the “happy path” of the payment lifecycle using the API.

In terms of relationships, we tie a Payout Method to a Legal Entity. But, you will also connect the Payout Method to an Account. An account can have multiple payout methods (one for each currency).

Once you are done with this section, you’ll be able to think about the payout flow for your merchants, and offer them the flexibility of choosing their payout schedule and specifying their banking details.

Create a Payout Method

Before you begin, be sure to grab your Legal Entity ID and Account ID from the Onboard Merchants section of this guide. Like the previous two articles, we recommend using the Tokenization strategy for collecting sensitive information, like a Merchant’s payment bank information. This will let you avoid handling sensitive information, like a Merchant’s account number.

First, we’ll need to make sure that the Merchant’s Legal Entity and Account have all 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 following information needs to be provided.  

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

GET /accounts/{id}/capabilities

If you successfully added in 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. You’ll want to create fields that capture the information below, using the Tokenization JS library:

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, send a POST, similar to the one below.

POST /payout_methods
{
	"legal_entity_id": "YOUR-LEGAL-ENTITY-ID-HERE",
	"nickname": "Test Payout Account",
	"token": {
		"id": "payout_methods-88ae04ca-0983-468b-9ca6-2ce18b66dafb"
	}
}

At this point, we’ve established a Payout Method, 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.

If you’d like to see how to create a Payout Method without Tokenization, read the below section. Otherwise, skip to Attach a Payout Method to a Merchant Account.

Attach a Payout Method to a Merchant Account

With a Payout Method ID handy, it’s time to connect an Account. First, determine what periods you will offer to your Merchants. We currently support daily, weekly, and monthly payout schedules. After that, send a POST to the accounts endpoint, similar to what we have below.

POST /accounts/{id}

{
  "payout": {
    "currencies": {
      "USD": {
        "payout_method_id": "YOUR-PAYOUT-METHOD-ID",
        "period": "daily"
      }
    }
  }
}

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 with a POST to /accounts{id} like this:

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

Set Notifications for Payouts

Notifications are WePay’s way of communicating important status information with your platform in real time. The table below shows use cases where you must send communication to your merchants, once you receive a notification from WePay.

For a full list of notifications to set for your platform and users, please visit the Platform Setup article.

Now that you’ve gotten end to end money movement down from Payer to Merchant, it’s time to discuss handling payment operations. Questions? Need help? Visit our support page!