Delayed Payouts

Tip

Permission is required to use this feature. Please contact your account manager.


Scenario

Charge a payer but don’t let the merchant withdraw the funds to their bank account until some trigger condition is met. This is different from Tipping Point Payments where a payer’s credit card information is collected but not charged until a tipping point or trigger condition is met.

Delayed payouts are available only in the United States and Canada at this time.


Example

Assume you are a platform that helps small businesses sell their goods. Someone orders a physical good from one of your small businesses. You want to charge the payer immediately, but you don’t want to release the funds to the small business until the item is shipped.

At WePay, the small business is the merchant and buyers are payers and we’ll use those terms below.


Key Concepts

You will charge the customer like normal with the /checkout/create call, and set the auto_release flag to false to indicate that you want the payment captured. Once you want the payment to be made available to the merchant, you will make another API call (/checkout/release).

There are two options to facilitate charging the card for delayed payouts.

  • Iframe (Embedded) - Iframe uses the /checkout/create API call to obtain a checkout_uri which will be embedded on your site to let the payer complete the payment. This method lets you use WePay’s pre-built and optimized form to collect credit card information. This method minimizes necessary PCI compliance, because information is shared securely between the browser and WePay.
  • Tokenization (Custom) - Tokenization uses WePay’s tokenization.js to obtain a credit card token which can then be used to charge the card with the /checkout/create API call. This method lets you use your own form to collect credit card information. As there is exposure to developer error or fraud, there is more PCI compliance required than there is with iframe.

Note

It is important to know that you can only delay payout for 14 days. If the payment has not been released 14 days after initial payment, it will be refunded. If your use-case needs to delay payout for longer than 14 days, then you might want to take a look at tipping-point payments.


Solutions

Solutions include:


Iframe

Summary

  1. Call /checkout/create and set the auto_release parameter to false.
  2. Use the resulting checkout_uri to drive the user through the checkout flow.
  3. Call /checkout/release when you want the payment to be made available for withdrawal.

Detailed Example

Step 1:

Call /checkout/create as you would normally, but set the auto_release parameter to false. Setting auto_release to false indicates that the payment will be held in the captured state and will not be immediately available to the merchant for withdrawal.

  • PHP
  • cURL
  • Ruby
  • Python

Step 2:

Use the resulting checkout_uri to drive the user through the checkout flow.

Now that you have the checkout_uri for the payment flow, you can embed it in an iframe on your payment page.

  • HTML

Step 3:

Use the checkout_id from Step 1 to make the /checkout/release call which will release the funds to the merchant.

  • PHP
  • cURL
  • Ruby
  • Python

When you make this call, the payment will go from state captured to state released. This means that the payment is now available for withdrawal by the merchant and will get sent to the merchant’s bank account the next time a withdrawal happens.


Tokenization

Summary

  1. Tokenize the credit card using WePay’s tokenization.js to obtain a credit_card_id.
  2. Charge the card with the /checkout/create call and set the auto_release parameter to false.
  3. Call /checkout/release when you want the payment to be made available for withdrawal.

Detailed Example

Step 1:

Tokenize the credit card using WePay’s tokenization.js.

Follow the steps in the tokenization tutorial to get a credit_card_id that represents the payer’s method of payment. You will use this credit_card_id in the next step to charge the credit card.

Step 2:

Call /checkout/create to immediately charge the card, and set the auto_release parameter to false. Setting auto_release to false indicates that the payment will be held in the captured state and will not be immediately available to the merchant for withdrawal.

  • PHP
  • cURL
  • Ruby
  • Python

If the payment clears successfully, it will go into state captured which indicates that the payment is successful, but has not been released to the merchant for withdrawal.

Step 3:

Use the checkout_id from Step 2 to make the /checkout/release call which will release the funds to the merchant.

  • PHP
  • cURL
  • Ruby
  • Python

When you make this call, the payment will go from state captured to state released. This means that the payment is now available for withdrawal by the merchant and will get sent to the merchant’s bank account the next time a withdrawal happens.