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, a Payout Method has a child relationship to an Account. An account can have multiple payout methods (one for each currency, though WePay currently supports once currency per Account). In addition, the Legal Entity acts as a ‘grandparent’ to the Payout Method object.

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

How Payouts Work

Payouts, at a high level, consist of a few pieces: payment processing, reserves, and receiving deposits. Throughout the guide, we’ve covered payment processing, and we’re ready to discuss reserves and payouts.

At a high level: Once payments are processed from payer to merchant, they are placed into a merchant’s Account and are subject to reserves. From there, a merchant can receive deposits via the Payouts API at a frequency of daily, weekly, or monthly. Review and reserves are necessary steps to ensure protection from fraudulent parties (merchants and/or payers), and must be completed before Payouts can occur.

Here is an example of the end-to-end Payment to Payout flow:

Before a Payment can be included in a Payout, the following requirements must be met:

1. The Account Capability payments must be "enabled": true; see here for specifics.
2. The Account Capability payouts must be "enabled": true; see here for specifics.
3. The Legal Entity’s controller, entity, and any additional representatives must have a Verification status of "verified": true
   • Enabling Payments and Payouts typically satisfy this requirement, but WePay may also require additional documentation in order to verify a Legal Entity. See here for specifics.
   • WePay takes a risk-based approach to verification, and may require additional supporting documentation after a Legal Entity has been verified.
4. The Payment must have "status": "completed"; this means:
   • WePay review must be complete and successful
   • Any delayed capture Payments must go through the capture step
   • ACH/Echeck Payment Methods must be verified (1-3 business days if not already verified)
   • ACH/Echeck Payments must pass the 2 business day hold (this is in place to mitigate rejections from the issuing bank)
5. The Payment must not be in the Account’s reserved balance.
   • Identify these Payments by fetching the Account’s balances.currencies.X.reserve and reconciling against the amount for the Account’s most recent Payments.

Reserves

Before a merchant receives payment, a merchant’s funds will be subject to WePay’s reserve policies. A reserve is defined as a threshold on a merchant’s account, reviewed by WePay Risk, with any money above the reserve released after 7 days.

Every merchant can have their own threshold, but the default is $500 per week, which means, at most, a merchant can receive $500 per week. Any amount over this threshold will be available 7 days after the payment was received.

Example 1  

Let’s say a merchant receives 3 payments of $250 each. The first two payments worth is available for withdrawal (and, if they have a Chase account, potentially settle the same day), but the 3rd payment will not be available until one week after the 3rd payment was made, regardless of payout frequency settings. The same applies for consequent payments after the 3rd.

Example 2  

Let’s say a merchant receives 3 payments on Monday: $501, $100, and $250. Because payments are not split, the first payment will place the Merchant’s account above the $500/week ceiling. As a result, $501 will be available for payouts the following Monday (7 days).

Please contact either your account manager or the WePay support team at support@wepay.com to modify the default $500 per week reserve for merchants. Once your Merchant has available funds (total funds under reserve amount), they can receive payouts. The next section describes when they will actually receive money.

Payouts

WePay offers automatic Same-Day Deposit capabilities for merchants on your Platform. If a merchant adds a Chase Bank Account where funds are to be deposited, they will receive their cash same day for all payments approved (completed API state) by the cutoff time Sunday-Friday. Plus, Saturday transactions will be deposited Sunday morning.

For a non-Chase Bank Account, deposits will occur on the next business day, depending on the receiving bank. Essentially, we are reducing the existing ACH payout window to 1-3 business days (from the historical 2-5). Keep in mind that Payments must meet all 5 requirements above before the 1-3 business day Payout time line comes into effect.

There is no additional cost for this functionality.

For exact time frames and cutoff times, please reference this table:

Same-Day Deposit requirements:

• Depending on your platform’s vertical (crowdfunding or SMB), your merchants will be setup with either a 5 pm PT or a 12 am PT cut-off time for transactions, based on the chart above. Reach out to your integration team, relationship executive, technical account manager, or api@wepay.com to find out more.
• The merchant must be based in the United States.

Same-Day Deposit limitations:

• Same-Day Deposits are currently rolling out. Rollout will be complete by the end of Q4 2019.
• ACH payments have a built-in delay of 2 business days. Once an ACH checkout is in a completed API state, it will be eligible for Same-Day Deposit.
• Saturday Deposits will be available on Sunday morning.
• Funds deposited to non-Chase bank accounts may post as soon as the next business day, depending on the receiving bank.
• Payments which are held in reserves will not be eligible for same day deposit until they are released from reserves. Read more on WePay’s reserve policy above.
• All transactions are subject to WePay terms of service and exclusions therein, including risk assessment and fraud monitoring, which may result in delays.

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

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. The field nickname should not contain any sensitive data, such as any part of the bank account number other than the last 4 digits.

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"
	}
}'

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.

If you’d like to see how to create a Payout Method without Tokenization, read the section in our Server to Server resource. Otherwise, continue below 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 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, send a POST to the accounts endpoint to either update the merchants existing Account or create their Account if not previously done. Our example below assumes that the merchant already has an API Account:

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

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

Reconcile Payouts

As a WePay partner using the Clear product, 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 cookbook.

Fetch Recoveries

Recoveries are the mechanism by which merchants’ WePay Account balances are kept whole.

When a negative balance occurs (due to a refund, for example) and any incoming payments do not bring the balance to a minimum of $0.00, a Recovery will pull the amount needed to reach $0.00 from the merchant’s active Payout Method.

Recoveries begin on the business day following the negative balance. This gives time for incoming payments to resolve the negative balance. For example, if a refund is issued on Monday, 10/22 and brings the balance negative, and if the balance is still negative on Tuesday, 10/23, then a Recovery will begin on 10/23.

Below are a few scenarios dealing with Recoveries:

You must subscribe to the recoveries.created Notification event topic in order to be notified when a Recovery occurs.

Set Notifications for Payouts

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

Required Communication

• Notify merchants of an invalidated Payout Method.
• Notify the merchant that a Payout failed.

Please visit the Platform Setup article to determine the actions to take for the given Required Communication and topic.

Next Up: Manage Payment Operations

Manage the operations that inherently go hand-in-hand with payment processing.

• Learn about and handle Disputes
• Issue refunds
• Consume Adjustments

Questions? Need help? Visit our support page!