WePay

The /account API calls

The "account" object represents a payment account for accepting payments. The following calls let you create, view, and modify "account" objects on WePay:

Older version?

You can view the older version 2011-01-15 here.

Account States

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

action_required
The account is not active and requires some action to be taken by the account owner.
pending
The account was created using a temporary access token and needs to be confirmed by the account owner.
active
The account is active and no further action is required.
disabled
The account has been disabled by WePay and can no longer accept payments.
deleted
The account has been deleted.

API Account State Diagram

/account

This call allows you to lookup the details of a payment account on WePay. The payment account must belong to the user associated with the access token used to make the call.

Arguments:

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

Example:

{
  "account_id":12345
}

Response:

Response Type Description
account_id Integer (64 bits) The unique ID of the account.
name String (255 chars) The name of the account.
state String (255 chars) The state of the account: action_required, active, disabled or deleted.
description String (65535 chars) The account description.
owner_user_id Integer (64 bits) The unique ID the user who is the current financial owner of this account.
reference_id String (255 chars) The unique reference ID of the account (this is set by the application in the /account/create or /account/modify call).
gaq_domains Array An array of Google Analytics domains associated with the account. See the analytics tutorial for more details.
theme_object Theme Structure The theme structure (a JSON object, not a JSON serialized string) you want to be used for account's flows and emails
type String (255 chars) The account type. Can be "personal", "nonprofit", or "business".
create_time Integer (64 bits) The unixtime when the account was created.
balances Array Array of account balances for each currency. See the structures page for more info.
statuses Array Array of account incoming and outgoing payments status for each currency.
action_reasons Array Array of action strings explaining all the actions that are required to make this account active. It will be empty if no action is required. Possible values are bank_account and kyc
disabled_reasons Array Array of strings explaining all reasons for why an account was disabled. It will be empty if the account is enabled. Possible values are fraud, high_risk_chargeback, reported_user, tos_violation, country_not_supported and no_settlement_path
disablement_time Timestamp For accounts that have not provided KYC and settlement information, the Unix time when the account will be disabled.
country String (2 chars) The account's country of origin 2-letter ISO code (e.g. US or CA)
currencies Array Array of supported currency strings for this account (e.g. ["USD"]). Both USD and CAD are currently supported.

Example:

{
  "account_id":12345,
  "name":"Example account",
  "state":"active",
  "description":"this account is just an example.",
  "owner_user_id":539291,
  "reference_id":"123abc",
  "type":"personal",
  "create_time":1367958263,
  "disablement_time":null,
  "country":"US",
  "currencies":[
    "USD"
  ],
  "balances":[
    {
      "currency":"USD",
      "balance":390.50,
      "incoming_pending_amount":635.30,
      "outgoing_pending_amount":210.00,
      "reserved_amount":0,
      "disputed_amount":0,
      "withdrawal_period":"daily",
      "withdrawal_type":"ach",
      "withdrawal_next_time":1370112217,
      "withdrawal_bank_name":"WellsFargo XXXXX3102"
    }
  ],
  "statuses":[
    {
      "currency":"USD",
      "incoming_payments_status":"ok",
      "outgoing_payments_status":"ok"
    }
  ],
  "action_reasons": [
    "bank_account",
    "kyc"
  ],
  "disabled_reasons": [
    "country_not_supported",
    "fraud",
    "high_risk_chargeback",
    "no_settlement_path",
    "reported_user",
    "tos_violation"
  ]
}

/account/find

This call lets you search the accounts of the user associated with the access token used to make the call. You can search by name or reference_id, and the response will be an array of all the matching accounts. If both name and reference_id are blank, this will return an array of all of the user's accounts.

Arguments:

Parameter Required Type Description
name No String (255 chars) The name of the account you are searching for.
reference_id No String (255 chars) The reference ID of the account you are searching for (set by the app in in /account/create or /account/modify).
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'.

Example:

{
  "name":"Example Acccount",
  "reference_id":"123abc"
}

Response:

An array of accounts matching the search parameters. Each element of the array will include the same data as returned from the /account call.

Example:

[
  {
    "account_id":12345,
    "name":"Example account",
    "state":"active",
    "description":"this account is just an example.",
    "owner_user_id":539291,
    "reference_id":"123abc",
    "type":"personal",
    "create_time":1367958263,
    "disablement_time":null,
    "country":"US",
    "currencies":[
      "USD"
    ],
    "balances":[
      {
        "currency":"USD",
        "balance":390.50,
        "incoming_pending_amount":635.30,
        "outgoing_pending_amount":210.00,
        "reserved_amount":0,
        "disputed_amount":0,
        "withdrawal_period":"daily",
        "withdrawal_next_time":1370112217,
        "withdrawal_bank_name":"WellsFargo XXXXX3102"
      }
    ],
    "statuses":[
      {
        "currency":"USD",
        "incoming_payments_status":"ok",
        "outgoing_payments_status":"ok"
      }
    ],
    "action_reasons": [
      "bank_account",
      "kyc"
    ],
    "disabled_reasons": [
      "country_not_supported",
      "fraud",
      "high_risk_chargeback",
      "no_settlement_path",
      "reported_user",
      "tos_violation"
    ]
  }
]

/account/create

Creates a new payment account for the user associated with the access token used to make this call. If reference_id is passed, it MUST be unique for the application/user pair or an error will be returned. NOTE: You cannot create an account with the word 'wepay' in it. This is to prevent phishing attacks.

Arguments:

Parameter Required Type Description
name Yes String (255 chars) The name of the account you want to create.
description Yes String (65535 chars) The description of the account you want to create.
reference_id No String (255 chars) The reference id of the account. Can be any string, but must be unique for the application/user pair.
type No String (255 chars) The type of account you are creating. Can be "nonprofit", "business", or "personal".
image_uri No String (2083 chars) The uri for an image that you want to use for the accounts icon. This image will be used in the co-branded checkout process.
gaq_domains No Array An array of Google Analytics domains associated with the account. See the analytics tutorial for more details.
theme_object No Theme Structure The theme structure (a JSON object, not a JSON serialized string) you want to be used for account's flows and emails
mcc No Integer (64 bits) The mcc code that is relevant to the type of account this is. See the mcc reference page for more information.
callback_uri No String (2083 chars) The uri that will receive IPNs for this account. You will receive an IPN whenever the account is verified or deleted.
country No String (2 chars) The account's country of origin 2-letter ISO code (e.g. 'US' or 'CA')
currencies No Array Array of supported currency strings for this account (e.g. ["USD"]) Both "USD" and "CAD" are currently supported.

Example:

{
  "name":"Example Account",
  "description":"This is just an example WePay account.",
  "reference_id":"abc123",
  "image_uri":"https://stage.wepay.com/img/logo.png",
  "country":"US",
  "currencies":[
    "USD"
  ]
}

Response:

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

/account/modify

Updates the specified properties. If reference_id is passed, it must be unique for the user/application pair.

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to modify.
name No String (255 chars) The name for the account.
description No String (65535 chars) The description for the account.
reference_id No String (255 chars) The reference id for the account. Can be any string, but must be unique for the application/user pair.
image_uri No String (2083 chars) The uri for an image that you want to use for the accounts icon. This image will be used in the co-branded checkout process.
gaq_domains No Array The array of Google Analytics domains to be associated with the account. An empty array will remove all the Google Analytics domains previously associated with the account. See the analytics tutorial for more details.
theme_object No Theme Structure The theme structure (a JSON object, not a JSON serialized string) you want to be used for account's flows and emails
callback_uri No String (2083 chars) The uri that will receive IPNs for this account. You will receive an IPN whenever the account is verified or deleted.

Example:

{
  "account_id":12345,
  "name":"Example Account",
  "description":"This is just an example WePay account. Modify the text.",
  "reference_id":"abc123",
  "image_uri":"https://stage.wepay.com/img/logo.png"
}

Response:

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

/account/delete

Deletes the account specified. The use associated with the access token used must have permission to delete the account. An account may not be deleted if it has a balance or pending payments.

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to delete.
reason No String (255 chars) Reason for deleting the account.

Example:

{
  "account_id":12345
}

Response:

Response Type Description
account_id Integer (64 bits) The unique ID of the account that was successfully deleted.
state String (255 chars) The state of the account.

Example:

{
  "account_id":12345,
  "state":"deleted"
}

/account/get_update_uri

This call allows you to add or update all incomplete items for an account like KYC info, bank account, etc. It will return a URL that a user can visit to update info for his or her account.

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to add or update info for.
mode No String (255 chars) What mode the process will be displayed in. The options are 'iframe' or 'regular'. Choose iframe if you would like to frame the process on your site. Mode defaults to 'regular'.
redirect_uri No String (2083 chars) The uri the user will be redirected to after completing the process.

Example:

{
  "account_id":12345,
  "mode":"iframe"
}

Response:

Response Type Description
account_id Integer (64 bits) The id of the account that is updated by the URI
uri String (2083 chars) The URI to add or update info for the specified account id. Do not store the returned URI on your side as it can change.

Example:

{
  "account_id":12345,
  "uri":"http://stage.wepay.com/api/account_update_uri/12345"
}

/account/get_reserve_details

This call returns information about reserves and release schedule for a particular account.

Arguments:

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to view reserve details for.
currency No String (255 chars) The currency for the reserves. Defaults to "USD".

Example:

{
  "account_id":12345
}

Response:

Response Type Description
account_id Integer (64 bits) The id of the account you added the bank account to.
currency String (255 chars) The currency for the reserves.
reserved_amount Decimal (64 bits) The actual amount of money that is reserved and is not available for withdrawal.
withdrawals_schedule Array An array of time/amount pairs up to the next 10 withdrawals based on current balance, the reserves and withdrawals schedules. It will be empty if withdrawals are not yet configured or if there is no balance.

Example:

{
  "account_id":12345,
  "currency":"USD",
  "reserved_amount":390.50,
  "withdrawals_schedule":[
    {
      "time":1386096217,
      "amount":390.50
    }
  ]
}