Upgrade to new version
You are viewing old calls for version 2015-08-15. Please upgrade checkout object calls to version 2015-09-09 for latest functionality.
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:
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).
/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). |
| withdrawal_uri | String (2083 chars) | The uri that you will send the account owner to to complete the withdrawal. Do not store the returned URI on your side as it can change. |
| redirect_uri | String (2083 chars) | The uri that the account owner will return to after completing the withdrawal. |
| callback_uri | String (2083 chars) | The uri that we will post notifications to each time the state on this withdrawal changes. |
| 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) |
| note | String (255 chars) | A short description for the reason of the withdrawal. |
| recipient_name | String | The sanitized name of the recipient (example: "Test Bank XXXXXX1351" or the name of the recipient for check withdrawals). |
| recipient_confirmed | Boolean | Whether the recipient of the money has been confirmed (for bank withdrawals this is the receiving bank account). |
| 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. |
| create_time | Integer (64 bits) | The unixtime when the withdrawal was created. |
| capture_time | Integer (64 bits) | The unixtime when the withdrawal was captured and credited to the payee's bank account. Returns 0 if withdrawal is not yet captured. |
Example:
{
"withdrawal_id":54321,
"account_id":12345,
"state":"new",
"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",
"amount":100,
"currency": "USD",
"note":"Withdrawing money from the account",
"create_time":1332280083,
"capture_time":0,
"recipient_name":"Test Bank XXXXXX1351",
"recipient_confirmed":true
}
/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",
"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",
"amount":100,
"currency": "USD",
"note":"Withdrawing money from the account"
}
]
/withdrawal/create/
This call allows you to create a withdrawal object. A withdrawal object represents the movement of money from a WePay account to a bank account.
Use /account/get_update_uri instead
We've improved our flow for paying out funds to merchants. Now instead of having to manually schedule withdrawals, any available funds in a merchant's account will automatically be withdrawn to their bank account on a regular schedule. You can read more about this in the tutorial on facilitating withdrawals.
Arguments:
| Parameter | Required | Type | Description |
| account_id | Yes | Integer (64 bits) | The unique ID of the WePay account the money will be withdrawn from. |
| currency | No | String (3 chars) | The currency used ("USD" for now) |
| redirect_uri | No | String (2083 chars) | The uri that the account owner will be sent to after they authorize the withdrawal. Defaults to the application homepage. |
| callback_uri | No | String (2083 chars) | The uri that will receive POST notifications each time the withdrawal changes state. See the IPN reference 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. |
| fallback_uri | No | String (2083 chars) | The uri that the payer will be redirected to if cookies cannot be set in the iframe; will only work if mode is iframe. |
| note | No | String (255 chars) | A short description of the withdrawal. |
| mode | No | String (255 chars) | What mode the withdrawal will be displayed in. The options are 'iframe' or 'regular'. Choose 'iframe' if this is an iframe withdrawal. Mode defaults to 'regular'. |
Example:
{
"account_id":12345,
"currency": "USD",
"redirect_uri":"http://www.example.com/withdrawal/52513",
"callback_uri":"http://www.example.com/withdrawal/52513",
"note":"Withdrawing money from the account"
}
Response:
| Response | Type | Description |
| withdrawal_id | Integer (64 bits) | The unique ID of the withdrawal. |
| withdrawal_uri | String (2083 chars) | The uri that you need to send the account owner to so they can approve the withdrawal. Do not store the returned URI on your side as it can change. |
Example:
{
"withdrawal_id":54321,
"withdrawal_uri":"https://stage.wepay.com/api/withdrawal/54321/a5xc62"
}
/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.