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
/preapproval/find
/preapproval/create
/preapproval/cancel
/preapproval/modify

Preapproval Structures

Preapproval Prefill Info Structure

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.

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 2019-04-03

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`</code>.
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: `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 (UTC).
end_time	Integer (64 bits)	The last time that the API application can execute a payment with this preapproval. Will be a Unix timestamp (UTC).
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 timestamp (UTC) when the preapproval was created.
next_due_time	Integer (64 bits)	The Unix timestamp (UTC) 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 timestamp (UTC) 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": 1234,
    "account_id": 987654321,
    "preapproval_uri": "https://stage.wepay.com/api/preapproval/1234/0a64df86",
    "short_description": "Pledge for building a rocket ship",
    "currency": "USD",
    "amount": 0,
    "fee_payer": "payer",
    "state": "new",
    "redirect_uri": null,
    "app_fee": 0,
    "period": "once",
    "frequency": 1,
    "start_time": 1488322404,
    "end_time": 1646107034,
    "create_time": 1488322404,
    "manage_uri": "https://stage.wepay.com/preapproval/view/1234/0a64df86",
    "mode": "regular"
}

/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`</code>.
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: `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 (UTC).
end_time	Integer (64 bits)	The last time that the API application can execute a payment with this preapproval. Will be a Unix timestamp (UTC).
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 timestamp (UTC) when the preapproval was created.
next_due_time	Integer (64 bits)	The Unix timestamp (UTC) 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 timestamp (UTC) 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": 1234,
        "account_id": 987654321,
        "preapproval_uri": "https://stage.wepay.com/api/preapproval/1234/0a64df86",
        "short_description": "Pledge for building a rocket ship",
        "currency": "USD",
        "amount": 0,
        "fee_payer": "payer",
        "state": "new",
        "app_fee": 0,
        "period": "once",
        "frequency": 1,
        "start_time": 1488322404,
        "end_time": 1646107034,
        "create_time": 1488322404,
        "manage_uri": "https://stage.wepay.com/preapproval/view/1234/0a64df86",
        "mode": "regular",
        "redirect_uri": "http://www.example.com/callback/confirmation/51224",
        "callback_uri": "http://www.example.com/callback/status/51224"
    },
    {
        "preapproval_id": 13579,
        "account_id": 86420,
        "preapproval_uri": "https://stage.wepay.com/api/preapproval/13579/0a64df86",
        "short_description": "Pledge for building a rocket ship",
        "currency": "USD",
        "amount": 0,
        "fee_payer": "payer",
        "state": "new",
        "app_fee": 0,
        "period": "once",
        "frequency": 1,
        "start_time": 1488322404,
        "end_time": 1646107034,
        "create_time": 1488322404,
        "manage_uri": "https://stage.wepay.com/preapproval/view/13579/0a64df86",
        "mode": "regular",
        "redirect_uri": "http://www.example.com/callback/confirmation/51225",
        "callback_uri": "http://www.example.com/callback/status/51225"
    }
]

/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)	This parameter grants the API application authorization to charge the customer in the future. 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.
currency	No	String (3 chars)	The currency used. Possible values: `USD`, `CAD`. 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. Note: WePay does not allow underscores in subdomains, and using an underscore will violate the matching domain requirement.
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`. Note: Your platform may test using ports in staging but ports are not allowed in production.
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 (UTC) or a parsable date-time. If no timezone is included with the parseable datetime, the API will convert your datetime into UTC.
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 (UTC) 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. If no timezone is included with the parseable datetime, the API will convert your datetime into UTC.
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	Preapproval 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.example.com/preapproval/confirm/51231415",
    "callback_uri": "http://www.example.com/preapproval/callback/51231415",
    "short_description": "Pledge for building a rocket ship",
    "period": "once",
    "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.
client_id	No	Integer (64 bits)	Include your app's client ID. This parameter is required to cancel preapprovals that were created without an `account_id `.
client_secret	No	String	Include your app's client secret. This parameter is required to cancel preapprovals that were created without an `account_id`.

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`. Note: Your platform may test using ports in staging but ports are not allowed in production.

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`</code>.
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: `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 (UTC).
end_time	Integer (64 bits)	The last time that the API application can execute a payment with this preapproval. Will be a Unix timestamp (UTC).
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 timestamp (UTC) when the preapproval was created.
next_due_time	Integer (64 bits)	The Unix timestamp (UTC) 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 timestamp (UTC) 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": 13579,
    "account_id": 86420,
    "preapproval_uri": "https://stage.wepay.com/api/preapproval/13579/0a64df86",
    "short_description": "Pledge for building a rocket ship",
    "currency": "USD",
    "amount": 0,
    "fee_payer": "payer",
    "state": "new",
    "app_fee": 0,
    "period": "once",
    "frequency": 1,
    "start_time": 1488322404,
    "end_time": 1646107034,
    "create_time": 1488322404,
    "manage_uri": "https://stage.wepay.com/preapproval/view/13579/0a64df86",
    "mode": "regular",
    "redirect_uri": "http://www.example.com/callback/confirmation/51225",
    "callback_uri": "https://www.example.com/ipn/12345"
}

Preapproval Structures

Preapproval Prefill Info Structure

Specifies prefill information for the preapprovals flow.

Fields

Field	Required	Type	Description
name	No	String (255 chars)	The name of the person.
email	No	String (255 chars)	The email address of the person.
zip	No	String (14 chars)	The the postcode/zip for the address.
country	No	String (2 chars)	The 2-letter ISO-3166-1 country code.

Example

{
    "name": "Bill Clerico",
    "phone_number": "555-555-5555"
}