WePay Developer

The /preapproval API calls

The "preapproval" object represents an authorization from a user to execute a payment against the selected payment method. The following calls let you create, view, and modify "preapproval" objects on WePay:

Preapproval States

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

new
The pre-approval was created by the application.
approved
The payer approved the payments on WePay.
expired
Preapprovals expire if they are still in state new after 30 minutes (ie they have been abandoned).
revoked
The pre-approval was revoked by the paying user.
cancelled
The pre-approval was cancelled by the application.
stopped
The auto recurring pre-approval was stopped because we were unable to charge the card.
completed
Preapprovals are completed once they are past their end_time and can no longer be used.
retrying
If we fail to charge an auto_recur preapproval we will put it into state retry and then retry the payment 1 day later. Then it will either return to state Approved if the charge is successful or go to state Stopped if the charge fails.

API Preapproval State Diagram

/preapproval

This call allows you to lookup the details of a payment preapproval on WePay.

Arguments:

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

Example:

{
  "preapproval_id":12345
}

Response:

Response Type Description
preapproval_id Integer (64 bits) The unique ID of the preapproval.
preapproval_uri String (2083 chars) The uri that you send the user to so they can enter their payment info and approve the preapproval. Do not store the returned URI on your side as it can change.
manage_uri String (2083 chars) A uri that you can send the user to if they need to update their payment method. Do not store the returned URI on your side as it can change.
account_id Integer (64 bits) The unique ID of the WePay account where the money will go.
short_description String (255 chars) A short description of what the payer is being charged for.
long_description String (2047 chars) A longer description of what the payer is being charged for (if set).
currency String (255 chars) The currency that any charges will take place in (USD for now).
amount Decimal (64 bits) The amount in dollars that the application can charge the payer automatically every period.
fee_payer String (255 chars) Who is paying the fee (either "payer" for the person paying, "payee" for the person receiving the money, "payer_from_app" if payer is paying for app fee and the app is paying WePay fees, or "payee_from_app" if payee is paying for app fee and app is paying for WePay fees).
state String (255 chars) The state that the preapproval is in. See the preapproval states section for the full list.
redirect_uri String (2083 chars) The uri that the payer will be redirected to after approving the preapproval.
app_fee Decimal (64 bits) The fee that will go to the API application's account (if set). Limited to 20% of the preapproval amount.
period String (255 chars) How often the API application can execute payments for a payer with this preapproval. Can be: daily, weekly, biweekly, monthly, quarterly, yearly, and once. Once period is if you only want to get authorization for a future charge and don't need it to be recurring.
frequency Integer (64 bits) The number of times the API application can execute payments per period.
start_time Integer (64 bits) When the API application can begin executing payments with this preapproval. Will be a unix timestamp.
end_time Integer (64 bits) The last time that the API application can execute a payment with this preapproval. Will be a unix timestamp.
reference_id String (255 chars) The reference_id passed by the application (if set).
callback_uri String (2083 chars) The uri which instant payment notifications will be sent to.
shipping_address Address Structure If 'require_shipping' was set to true and the payment was made, this will be the shipping address structure (a JSON object, not a JSON serialized string) that the payer entered.
shipping_fee Decimal (64 bits) The amount that was paid in shipping fees (if any).
tax Decimal (64 bits) The dollar amount of taxes paid (if any).
auto_recur Boolean Whether or not the preapproval automatically executes the payments every period.
payer_name String (255 chars) The name of the payer.
payer_email String (255 chars) The email of the payer.
create_time Integer (64 bits) The unixtime when the preapproval was created.
next_due_time Integer (64 bits) The unixtime of the next scheduled charge +/- 5 minutes (will only show up for approved auto_recur preapprovals).
last_checkout_id Integer (64 bits) The checkout ID of the last successful checkout (captured state) for the preapproval.
last_checkout_time Integer (64 bits) The unixtime when the last successful checkout occurred.
mode String (255 chars) The mode that the preapproval was displayed in.

Example:

{
  "preapproval_id":12345,
  "preapproval_uri":"https://stage.wepay.com/api/preapproval/12345",
  "manage_uri":"https://stage.wepay.com/preapproval/view/12345",
  "account_id":54321,
  "short_description":"Pledge for building a rocket ship",
  "long_description":"You are authorizing us to charge you at a later date when campaign ends",
  "currency":"USD",
  "amount":15,
  "fee_payer":"payer",
  "state":"approved",
  "redirect_uri":"http://www.everribbon.com/callback/confirmation/51224",
  "app_fee":5,
  "period":"once",
  "frequency":1,
  "start_time":1319752361,
  "end_time":1351374761,
  "reference_id":"123abc",
  "callback_uri":"http://www.everribbon.com/callback/status/51224",
}

/preapproval/find

This call lets you search the preapprovals associated with an account or an application. If account_id is blank, then the response will be all preapprovals for the application. Otherwise, it will be specifically for that account. You can search by state and/or reference_id, and the response will be an array of all the matching preapprovals.

Arguments:

Parameter Required Type Description
account_id No Integer (64 bits) The unique ID of the account whose preapprovals you are searching. If empty, then the response will be all preapprovals for the application.
state No String (255 chars) The state of the preapproval you are searching for.
reference_id No String (255 chars) The reference ID of the preapproval you are searching for (set by the app in in /preapproval/create call).
start No Integer (64 bits) The start position for your search (default 0).
limit No Integer (64 bits) The maximum number of returned entries (default 50).
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'.
last_checkout_id No Integer (64 bits) Finds the preapproval associated with the given checkout ID. The checkout must have been successful (captured state).
shipping_fee No Decimal (64 bits) All preapprovals with the given shipping fee.

Example:

{
  "account_id":54321,
  "state":"authorized",
  "reference_id":"123abc"
}

Response:

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

Example:

[
  {
    "preapproval_id":12345,
    "account_id":54321,
    "short_description":"Pledge for building a rocket ship",
    "long_description":"You are authorizing us to charge you at a later date when campaign ends",
    "currency":"USD",
    "amount":15,
    "fee_payer":"payer",
    "state":"approved",
    "redirect_uri":"http://www.everribbon.com/callback/confirmation/51224",
    "app_fee":5,
    "period":"once",
    "frequency":1,
    "start_time":1319752361,
    "end_time":1351374761,
    "reference_id":"123abc",
    "callback_uri":"http://www.everribbon.com/callback/status/51224",
  }
]

/preapproval/create

Creates a new payment preapproval request object 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.

To make the payments execute automatically every month, set auto_recur to true. If you set auto_recur to true, then the first payment will execute at the start_time for that preapproval. If you do not pass a start_time in the /preapproval/create call, then the start_time will default to the time that /preapproval/create was called. The payments will then automatically execute every period after the start_time. So if you set the start_time to January 20th, then the first payment will occur on January 20th, and the next payment will occur on February 20th, and so on.

Arguments:

Parameter Required Type Description
account_id No Integer (64 bits) The WePay account where the money will go when you use this preapproval to execute a payment.
amount No Decimal (64 bits) The amount for the preapproval. The API application can charge up to this amount every period.
currency No String (3 chars) The currency used, default "USD" ("USD" for now).
short_description Yes String (255 chars) A short description of what the payer is paying for.
period Yes String (255 chars) Can be: daily, weekly, biweekly, monthly, quarterly, yearly, or once. The API application can charge the payer every period.
reference_id No String (255 chars) The reference id of the preapproval. Can be any string, but must be unique for the application/user pair.
app_fee No Decimal (64 bits) The application fee that will go to the API application's account.
fee_payer No String (255 chars)

Who will pay the fees (WePay's fees and any app fees).

Set to "payer" (case-sensitive) to charge fees to the person paying (Payer will pay amount + fees, and payee will receive amount).

Set to "payee" to charge fees to the person receiving money (Payer will pay amount, and payee will receive amount - fees).

Set to "payer_from_app" so that payer will be charged app fee (if there is one) and API application will be charged WePay fee.

Set to "payee_from_app" so that payee will be charged the app fee (if there is one) and the API application will be charged the WePay fee. Note that for the xxx_from_app calls: if the application's account goes negative, WePay will recover funds from bank account.

Defaults to "payer".

redirect_uri No String (2083 chars) The uri the payer will be redirected to after approving the preapproval.
callback_uri No String (2083 chars) The uri that any instant payment notifications will be sent to. 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.
require_shipping No Boolean Defaults to false. If set to true then the payer will be require to enter their shipping address when they approve the preapproval.
shipping_fee No Decimal (64 bits) The dollar amount of shipping fees that will be charged.
charge_tax No Boolean Defaults to false. If set to true then any applicable taxes will be charged.
payer_email_message No String (65535 chars) A short message that will be included in the payment confirmation email to the payer.
long_description No String (2047 chars) An optional longer description of what the payer is paying for.
frequency No Integer (64 bits) How often per period the API application can charge the payer.
start_time No Integer (64 bits) or String (255 chars) When the API application can start charging the payer. Can be a unix_timestamp or a parse-able date-time.
end_time No Integer (64 bits) or String (255 chars) The last time the API application can charge the payer. Can be a unix_timestamp or a parse-able date-time. The default value is five (5) years from the preapproval creation time. Make sure you give your app a bit of wiggle room in case you need to delay charging the customer.
auto_recur No Boolean Set to true if you want the payments to automatically execute every period. Default value is false. Only the following periods are allowed if you set auto_recur to true: Weekly, Biweekly, Monthly, Quarterly, Yearly
mode No String (255 chars) What mode the preapproval confirmation flow will be displayed in. The options are 'iframe' or 'regular'. Choose 'iframe' if this is an iframe preapproval. Mode defaults to 'regular'.
prefill_info No Prefill_Info Structure Information to pre fill certain fields in the preapproval flow (a JSON object, not a JSON serialized string).
funding_sources No String (255 chars) What funding sources you want to accept for this checkout. Options are: "bank,cc" to accept both bank and cc payments, "cc" to accept just credit card payments, and "bank" to accept just bank payments.
payment_method_id No Integer (64 bits) If you are using credit card tokenization use the credit_card_id you received from the /credit_card/create call.
payment_method_type No String (255 chars) Set to 'credit_card' for tokenization.

Example:

{
  "account_id":12345,
  "reference_id":"abc123",
  "amount":15.00,
  "currency": "USD",
  "app_fee":5,
  "fee_payer":"payer",
  "redirect_uri":"http://www.everribbon.com/preapproval/confirm/51231415",
  "callback_uri":"http://www.everribbon.com/preapproval/callback/51231415",
  "short_description":"Pledge for building a rocket ship",
  "long_description":"You are authorizing us to charge you at a later date when campaign ends",
  "period":"once",
  "frequency":1,
  "start_time":1320191240,
  "end_time":1351813639
}

Response:

Response Type Description
preapproval_id Integer (64 bits) The unique ID of the preapproval.
preapproval_uri String (2083 chars) The uri that you will send the payer to get the preapproval approved. Do not store the returned URI on your side as it can change.

Example:

{
  "preapproval_id":619202,
  "preapproval_uri":"https://stage.wepay.com/api/preapproval/619202",
}

App Level preapprovals

If you want to get authorization to send money to any account you can make the /preapproval/create call with your client_id and client_secret instead of the account_id and access_token.

The preapproval will then be able to authorize payments to any account you have set up for your users.

/preapproval/cancel

Allows you to cancel the preapproval. If cancelled the preapproval cannot be used to execute payments.

Arguments:

Parameter Required Type Description
preapproval_id Yes Integer (64 bits) The unique ID of the preapproval you want to cancel.

Example:

{
  "preapproval_id":619202
}

Response:

Response Type Description
preapproval_id Integer (64 bits) The unique ID of the preapproval.
state String (255 chars) The state the preapproval is now in. Will be 'cancelled'.

Example:

{
  "preapproval_id":619202,
  "state":"cancelled",
}

/preapproval/modify

This call allows you to modify the callback_uri on a preapproval.

Arguments:

Parameter Required Type Description
preapproval_id Yes Integer (64 bits) The unique ID of the preapproval you want to modify.
callback_uri No String (2083 chars) The uri that any instant payment notifications will be sent to. 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:

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

Response:

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