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.
/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 | Shipping Address Structure | If 'require_shipping' was set to true 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). |
| 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 period, 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 1st and the period is "monthly", then the first payment will occur on January 1st, and the next payment will occur on February 1st, and so on.
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) | Can be: daily, weekly, biweekly, monthly, quarterly, yearly, or once. The API application can charge the payer every period. |
| 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, default "USD" ("USD" for now). |
| 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. |
| 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.