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 view and modify withdrawal objects on WePay:

/withdrawal
/withdrawal/find
/withdrawal/modify

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. Read our instant payment notification guide for more details):

started	The withdrawal has started processing.
captured	The withdrawal has been credited to the payee's bank account.
failed	The withdrawal has failed.

Withdrawal State Diagram

Version: v2 2019-04-03

POST Endpoint

https://wepayapi.com/v2/withdrawal

/withdrawal

Use this call 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 a 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 from which the funds are coming.
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 of money withdrawn from the WePay account and deposited into the bank account.
currency	String (3 chars)	The currency of the transaction. Possible values: `USD`, `CAD` Default: `USD`
type	String (255 chars)	The type of withdrawal. Will be `check` for a paper check, or `ach` for a withdrawal to a bank account (direct deposit).
bank_data	Bank Data Response Structure	Information about the bank to the funds are sent if the type of withdrawal was `ach`. Includes the nickname of the bank, the last four digits of the account, and a short note.
check_data	Check Data Response Structure	Information about the recipient if the withdrawal type was `check`.
withdrawal_data	Withdrawal Data Response Structure	Information about a withdrawal.
in_review	Boolean	Indicates if the withdrawal is in review prior to capture.

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",
        "cashed_time": 1332280083
    },
    "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"
    },
    "in_review": true
}

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"
    },
    "in_review": true
}

/withdrawal/find

Use this call to find withdrawals made from a specified account. This call returns an array of withdrawals associated with the account_id.

Arguments

Parameter	Required	Type	Description
account_id	One Of	Integer (64 bits)	A unique ID for the account for which you want to find withdrawals.
checkout_id	One Of	Integer (64 bits)	A unique ID for a checkout for which you want to find the associated withdrawal. If the provided checkout has not been withdrawn, an empty array will return.
limit	No	Integer (64 bits)	The maximum number of withdrawals to be returned. Default: `50`
start	No	Integer (64 bits)	Where to start in the withdrawal list if more than the specified `limit` of withdrawals are found.
sort_order	No	String (255 chars)	Sort the results of the search by time created. Use `desc` for most recent to oldest. Use `asc` for oldest to most recent. Default: `desc`
state	No	String (255 chars)	Filter by a withdrawal state (see the withdrawal states section for a list of possible states).

Example

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

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 from which the funds are coming.
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 of money withdrawn from the WePay account and deposited into the bank account.
currency	String (3 chars)	The currency of the transaction. Possible values: `USD`, `CAD` Default: `USD`
type	String (255 chars)	The type of withdrawal. Will be `check` for a paper check, or `ach` for a withdrawal to a bank account (direct deposit).
bank_data	Bank Data Response Structure	Information about the bank to the funds are sent if the type of withdrawal was `ach`. Includes the nickname of the bank, the last four digits of the account, and a short note.
check_data	Check Data Response Structure	Information about the recipient if the withdrawal type was `check`.
withdrawal_data	Withdrawal Data Response Structure	Information about a withdrawal.
in_review	Boolean	Indicates if the withdrawal is in review prior to capture.

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",
            "cashed_time": 1332280083
        },
        "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"
        },
        "in_review": true
    },
    {
        "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",
            "cashed_time": 1332280083
        },
        "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"
        },
        "in_review": true
    }
]

/withdrawal/modify

Use this call to change the callback_uri on a withdrawal. This call returns the same response as the /withdrawal call.

Arguments

Parameter	Required	Type	Description
withdrawal_id	Yes	Integer (64 bits)	The unique ID of the withdrawal which you want to modify.
callback_uri	No	String (2083 chars)	The URI that will receive POST notifications each time the withdrawal changes state. See the instant payment notifications guide for more details. This must be a full URI (ex https://www.example.com ) and must not `localhost` or `127.0.0.1`, or include `wepay.com`. Note: Your platform may test using ports in staging but ports are not allowed in production.

Example

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

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 from which the funds are coming.
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 of money withdrawn from the WePay account and deposited into the bank account.
currency	String (3 chars)	The currency of the transaction. Possible values: `USD`, `CAD` Default: `USD`
type	String (255 chars)	The type of withdrawal. Will be `check` for a paper check, or `ach` for a withdrawal to a bank account (direct deposit).
bank_data	Bank Data Response Structure	Information about the bank to the funds are sent if the type of withdrawal was `ach`. Includes the nickname of the bank, the last four digits of the account, and a short note.
check_data	Check Data Response Structure	Information about the recipient if the withdrawal type was `check`.
withdrawal_data	Withdrawal Data Response Structure	Information about a withdrawal.
in_review	Boolean	Indicates if the withdrawal is in review prior to capture.

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",
        "cashed_time": 1332280083
    },
    "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"
    },
    "in_review": true
}

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"
    },
    "in_review": true
}