The /withdrawal API calls

The "withdrawal" object represents a single payout to the user's bank account or a check sent to the user. The following calls let you create, view, and modify "withdrawal" objects on WePay:

Older version?

You can view the older version 2015-08-15 here.

Withdrawal States

The "withdrawal" object has the following states and the following possible state transitions (you can receive callback notifications when the withdrawal changes state, please read our IPN reference for more details):

new
The withdrawal was created by the application.
started
The withdrawal has started processing.
captured
The withdrawal has been credited to the payee's bank account.
failed
The withdrawal has failed.
expired
Withdrawals get expired if they are still in state new after 60 minutes (i.e. the payee abandoned the flow without adding complete withdrawal information).

API Withdrawal State Diagram

/withdrawal

This call allows you to lookup the details of a withdrawal. A withdrawal object represents the movement of money from a WePay account to a bank account.

Arguments:

Parameter Required Type Description
withdrawal_id Yes Integer (64 bits) The unique ID of the withdrawal you want to look up.

Example:

{
  "withdrawal_id":54321
}

Response:

Response Type Description
withdrawal_id Integer (64 bits) The unique ID of the withdrawal.
account_id Integer (64 bits) The unique ID of the account that the money is coming from.
state String (255 chars) The state that the withdrawal is in (see the section on withdrawal states section for a list of possible states).
amount Decimal (64 bits) The amount on money withdrawn from the WePay account to the bank account.
currency String (3 chars) The currency used ("USD" for now)
type String (255 chars) The type of withdrawal. Will be "check" for a sent paper check, or "ach" for a withdrawal to a bank account.
bank_data Bank Data Structure Bank information for a withdrawal by bank account.
check_data Check Data Structure Check information for a withdrawal by check.
withdrawal_data Withdrawal Data Structure Information about a withdrawal.

Example for a Check withdrawal:

{
  "withdrawal_id":54321,
  "account_id":12345,
  "state":"new",
  "amount":100,
  "currency":"USD",
  "type":"check",
  "bank_data": null,
  "check_data": {
      "name":"Bill Clerico",
      "city":"Redwood City",
      "state":"CA",
      "zip":"94063",
      "note":"Withdrawing money from the account"
  },
  "withdrawal_data": {
      "create_time":1332280083,
      "capture_time":0,
      "redirect_uri":"http://www.example.com/withdrawal/51341",
      "callback_uri":"http://www.example.com/withdrawal/callback/51341",
      "withdrawal_uri":"https://stage.wepay.com/api/withdrawal/54321/s341bxd"
  }
}

Example for an ACH withdrawal:

{
  "withdrawal_id":67890,
  "account_id":12345,
  "state":"new",
  "amount":100,
  "currency":"USD",
  "type":"check",
  "bank_data": {
      "bank_name":"TestBank XXXXXX3123",
      "account_last_four":"3123",
      "note":"Withdrawing money from the account"
  },
  "check_data": null,
  "withdrawal_data": {
      "create_time":1332280083,
      "capture_time":0,
      "redirect_uri":"http://www.example.com/withdrawal/51341",
      "callback_uri":"http://www.example.com/withdrawal/callback/51341",
      "withdrawal_uri":"https://stage.wepay.com/api/withdrawal/54321/s341bxd"
  }
}

/withdrawal/find/

This call allows you to find withdrawals.

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to look up withdrawals for.
limit No Integer (64 bits) The maximum number of withdrawals that will be returned.
start No Integer (64 bits) If more than "limit" withdrawals are found, where to start in the withdrawal list.
sort_order No String (255 chars) Sort the results of the search by time created. Use 'DESC' for most recent to least recent. Use 'ASC' for least recent to most recent. Defaults to 'DESC'.
state No String (255 chars) Filter by a withdrawal state (see the section on withdrawal states section for a list of possible states).

Example:

{
  "account_id":12345,
  "limit":10,
  "start":0
}

Response:

The response will be an array of withdrawals with the same details as the /withdrawal call.

Example:

[
  {
    "withdrawal_id":54321,
    "account_id":12345,
    "state":"new",
    "amount":100,
    "currency":"USD",
    "type":"check",
    "bank_data": null,
    "check_data": {
        "name":"Bill Clerico",
        "city":"Redwood City",
        "state":"CA",
        "zip":"94063",
        "note":"Withdrawing money from the account"
    },
    "withdrawal_data": {
        "create_time":1332280083,
        "capture_time":0,
        "redirect_uri":"http://www.example.com/withdrawal/51341",
        "callback_uri":"http://www.example.com/withdrawal/callback/51341",
        "withdrawal_uri":"https://stage.wepay.com/api/withdrawal/54321/s341bxd"
    }
  },
  {
    "withdrawal_id":67890,
    "account_id":12345,
    "state":"new",
    "amount":100,
    "currency":"USD",
    "type":"check",
    "bank_data": {
        "bank_name":"TestBank XXXXXX3123",
        "account_last_four":"3123",
        "note":"Withdrawing money from the account"
    },
    "check_data": null,
    "withdrawal_data": {
        "create_time":1332280083,
        "capture_time":0,
        "redirect_uri":"http://www.example.com/withdrawal/51341",
        "callback_uri":"http://www.example.com/withdrawal/callback/51341",
        "withdrawal_uri":"https://stage.wepay.com/api/withdrawal/54321/s341bxd"
    }
  }
]

/withdrawal/modify

This call allows you to change the callback_uri on a withdrawal.

Arguments:

Parameter Required Type Description
withdrawal_id Yes Integer (64 bits) The unique ID of the withdrawal you want to look up.
callback_uri No String (2083 chars) The uri that will receive POST notifications each time the withdrawal changes state. See the IPN tutorial for more details. Needs to be a full uri (ex https://www.wepay.com ) and must NOT be localhost or 127.0.0.1 or include wepay.com.

Example:

{
  "withdrawal_id":54321,
  "callback_uri":"https://www.example.com/ipn/12345"
}

Response:

This call will return the same response as the /withdrawal call.