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:

new The preapproval 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 (e.g., they have been abandoned).
revoked The preapproval was revoked by the paying user.
cancelled The preapproval was cancelled by the application.
stopped The preapproval 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 a recurring preapproval, we will put it into state retrying and then retry the payment one day later. Then it will either return to state approved if the payment is successful or go to state stopped if the payment fails.

Tip

You can receive callback notifications when the preapproval changes state. Read our Instant Payment Notifications (IPN) guide for more information.

Preapproval State Diagram

Version: v2 2016-08-10

POST Endpoint

https://wepayapi.com/v2/preapproval

/preapproval

Use this call 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.
callback_uri String (2083 chars) The URI to which instant payment notifications is sent.
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 in which any charges will take place.

Possible values: USD, CAD, and GBP.
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.

Possible values: daily, weekly, biweekly, monthly, quarterly, yearly, and once.
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 value passed by the application (if set).
shipping_address Shipping Address Structure If require_shipping was set to true in the /preapproval/create call and the payment was made, this will be the shipping 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).
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 Unix time when the preapproval was created.
next_due_time Integer (64 bits) The Unix time of the next scheduled charge +/- 5 minutes.
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 Unix time when the last successful checkout occurred.
mode String (255 chars) The mode in which the preapproval confirmation flow is displayed.

Possible values: iframe and regular.

Default: regular

Example

{
   "preapproval_id":12345,
   "preapproval_uri":"https://stage.wepay.com/api/preapproval/12345",
   "manage_uri":"https://stage.wepay.com/preapproval/view/12345",
   "callback_uri":"http://www.everribbon.com/callback/status/51224",
   "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 the campaign ends",
   "currency":"USD",
   "fee_payer":"payer",
   "state":"approved",
   "redirect_uri":"http://www.everribbon.com/callback/confirmation/51224",
   "app_fee":5,
   "reference_id":"123abc"
}

/preapproval/find

Use this call to 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. Each element of the array in the response includes the same data returned from the /preapproval call.

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 for which you searched.
reference_id No String (255 chars) The reference ID of the preapproval for which you searched (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.

Default: 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

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.
callback_uri String (2083 chars) The URI to which instant payment notifications is sent.
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 in which any charges will take place.

Possible values: USD, CAD, and GBP.
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.

Possible values: daily, weekly, biweekly, monthly, quarterly, yearly, and once.
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 value passed by the application (if set).
shipping_address Shipping Address Structure If require_shipping was set to true in the /preapproval/create call and the payment was made, this will be the shipping 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).
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 Unix time when the preapproval was created.
next_due_time Integer (64 bits) The Unix time of the next scheduled charge +/- 5 minutes.
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 Unix time when the last successful checkout occurred.
mode String (255 chars) The mode in which the preapproval confirmation flow is displayed.

Possible values: iframe and regular.

Default: regular

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 the campaign ends",
      "currency":"USD",
      "fee_payer":"payer",
      "state":"approved",
      "redirect_uri":"http://www.everribbon.com/callback/confirmation/51224",
      "app_fee":5,
      "reference_id":"123abc",
      "callback_uri":"http://www.everribbon.com/callback/status/51224"
   },
   {
      "preapproval_id":456789,
      "account_id":54321,
      "short_description":"Money to help you buy parts for your spacecraft",
      "long_description":"You are authorizing us to charge you at a later date when the campaign ends",
      "currency":"USD",
      "fee_payer":"payer",
      "state":"approved",
      "redirect_uri":"http://www.everribbon.com/callback/confirmation/51224",
      "app_fee":5,
      "reference_id":"456xyz",
      "callback_uri":"http://www.everribbon.com/callback/status/51224"
   }
]

/preapproval/create

Use this call to create 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.

Tip

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.

Arguments

Parameter Required Type Description
short_description Yes String (255 chars) A short description of what the payer is paying for.
period Yes String (255 chars) The API application can charge the payer every period. A period of once should be specified only if you want to get authorization for a future charge and do not want it to be recurring.

Possible values: daily, weekly, biweekly, monthly, quarterly, yearly, and once.

Default: once
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. Only use with recurring preapprovals (period is not once).
currency No String (3 chars) The currency used.

Possible values: USD, CAD, and GBP.

Default: USD
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.
Default: 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.example.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 If set to true, then the payer will be require to enter their shipping address when they approve the preapproval.

Default: false
shipping_fee No Decimal (64 bits) The dollar amount of shipping fees that 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 parsable 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 parsable 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.
mode No String (255 chars) The mode in which the preapproval confirmation flow is displayed.

Possible values: iframe and regular. Choose iframe if this is an iframe preapproval. The preapproval flow will be displayed on the partner site. When regular is chosen, the preapproval flow is seen entirely on the WePay site.

Default: regular
prefill_info No Prefill_Info Structure Information to prefill certain fields in the preapproval flow (a JSON object, not a JSON serialized string).
funding_sources No String (255 chars) The types of 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.

Default: bank and cc

Example

{
   "account_id": 12345,
   "reference_id": "abc123",
   "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 the campaign ends"
}

Response

Response Type Description
preapproval_id Integer (64 bits) A unique ID for 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"
}

/preapproval/cancel

Use this call to cancel a preapproval. If cancelled, the preapproval cannot be used to execute payments.

Arguments

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

Example

{
   "preapproval_id": 619202
}

Response

Response Type Description
preapproval_id Integer (64 bits) A unique ID for the preapproval.
state String (255 chars) The current state of the preapproval. If the call is successful the state will be cancelled).

Example

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

/preapproval/modify

Use this call to modify the callback_uri parameter on a preapproval. This call returns the same response as the /preapproval call.

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.example.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

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.
callback_uri String (2083 chars) The URI to which instant payment notifications is sent.
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 in which any charges will take place.

Possible values: USD, CAD, and GBP.
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.

Possible values: daily, weekly, biweekly, monthly, quarterly, yearly, and once.
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 value passed by the application (if set).
shipping_address Shipping Address Structure If require_shipping was set to true in the /preapproval/create call and the payment was made, this will be the shipping 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).
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 Unix time when the preapproval was created.
next_due_time Integer (64 bits) The Unix time of the next scheduled charge +/- 5 minutes.
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 Unix time when the last successful checkout occurred.
mode String (255 chars) The mode in which the preapproval confirmation flow is displayed.

Possible values: iframe and regular.

Default: regular

Example

{
   "preapproval_id":12345,
   "preapproval_uri":"https://stage.wepay.com/api/preapproval/12345",
   "manage_uri":"https://stage.wepay.com/preapproval/view/12345",
   "callback_uri":"http://www.everribbon.com/callback/status/51224",
   "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 the campaign ends",
   "currency":"USD",
   "fee_payer":"payer",
   "state":"approved",
   "redirect_uri":"http://www.everribbon.com/callback/confirmation/51224",
   "app_fee":5,
   "reference_id":"123abc"
}