FuturePay Agreements provide a very flexible combination of periodic, ad-hoc or cumulative debiting structures. It is possible to control such Agreements via the WorldPay Customer Management System although, if there are a substantial number of Agreements, where calculations are required prior to making alterations, or changes are time-critical, it may be more appropriate to automate these processes.
It is important to recognise that once a FuturePay Agreement is set up by the Merchant and accepted by the Shopper on the WorldPay Payment Gateway, the structure of it is fixed. The degree of flexibility offered by WorldPay for each type of FuturePay Agreement should be fully understood before implementation.
If you have not yet requested FuturePay to be enabled for your Company ID please visit https://support.worldpay.com/products_services. Once this is acknowledged then you can request FuturePay be enabled for your installation ID(s).
If you intend to use third-party software for your web site integration with WorldPay using FuturePay, please verify with your software provider that it supports FuturePay before upgrading your WorldPay Company ID.
FuturePay Regular Agreements are set up for periodic debits. WorldPay will initiate those debits where possible once they are due. The interval between when debits are due cannot be altered. Agreements can run for a fixed or unlimited period of time.
Below is a list of the remote administration facilities available for each type of FuturePay Regular Agreement.
The start date must be in the future and cannot be today. The start date may only be successfully set once per Agreement.
The start date must be in the future and cannot be today. The start date may only be successfully set once per Agreement.
This can be done any number of times during the lifetime of the Agreement, but can only succeed if there are at least two weeks before the next debit is due.It is possible to set the
amountto0, if you wish to implement a "payment holiday". Changing theamountto the existing value (i.e. no change) is permitted.
The start date must be at least two weeks in the future. The start date may only be successfully set once per Agreement.
This can be done any number of times during the lifetime of the Agreement, but can only succeed if there are at least fourteen days before the next debit is due.If the amount is not set with enough time before the next debit is due then nothing will be debited.
FuturePay Limited Agreements can be much more versatile than those of FuturePay Regular - indeed, they are only limited by the parameters you choose to add in the original token submitted to WorldPay. The major difference is that the Agreement specifies the structure within which the payments may be initiated by the merchant, not WorldPay. Agreements can run for a fixed or unlimited period of time.
Below is a list of the remote administration facilities available for all types of FuturePay Limited Agreement.
Debits are actioned immediately.
You will need an installation ID set up for this type of remote administration. Typically this is a Select Junior installation (but could be a Select Pro one), which will be used independently of your existing web site. It will need to be set up with a "remote authorisation password" which you can specify when asking for this facility to be set up by contacting integrations@worldpay.com. Note this is limited to 20 characters.
If you already have this facility set up as detailed in http://support.worldpay.com/kb/reference/faqs/remote_postauth_and_refunds.html, you can already use everything detailed in this document.
Please note that these facilities can be used regardless of the integration method used to submit the original FuturePay Agreement to WorldPay.
This code should never be available on your web site for shoppers to use. If you suspect that the remote authorisation password referred to below has been compromised then please contact your local Technical Support team at the earliest opportunity so that it can be changed.
Below is an example in HTML of code for each of the remote administration facilities. If you are intending to implement any of these functions on your web site it would be advised to implement this functionality within a server-side script, such that:
instId and authPW are not revealed to the public.It is possible to implement these functions using the Select Junior and Select Pro methods of integration but not, at this time, using Select COM.
The HTML examples are shown here only as one method of submitting the data to WorldPay as a POST. You can use either POST or GET for submitting these details to WorldPay, generated using any server-side scripting language.
If you are using a Select Junior installation ID with an MD5 secret for transactions enabled to protect purchase tokens it is ignored here; you do not have to generate the parameters signature and signatureFields when submitting the information to WorldPay.
Do not add any M_, MC_ or CM_ variables in the requests as these will be discarded.
If you wish to use FuturePay and callback, please see http://support.worldpay.com/kb/reference/faqs/callback_faqs.html#callback_futurepay.
The new installation ID and remote authorisation password are referred to below as XXXXX and YYYYY respectively. These will need to be changed to the installation ID and password provided by your local Technical Support team.
You must use https:// URLs.
<form action="https://select.worldpay.com/wcc/iadmin" method="post">
<input type="hidden" name="instId" value="XXXXX">
<input type="hidden" name="authPW" value="YYYYY">
<p>Enter the start date of the FuturePay Regular Agreement (YYYY-MM-DD) <input type="text" name="startDate" value=""></p>
<p>Enter the FuturePay Regular Agreement to initiate: <input type="text" name="futurePayId" value="" size="10"></p>
<input type="hidden" name="op-startDateRFP">
<input type="submit" name="startDate" value="Set Agreement start date">
</form>
You must use the response generated to determine the success of the request; no FuturePay callback will be triggered.
| Response string | Meaning |
| Y,Start set OK | You have successfully set startDate for this futurePayId |
| E,Agreement already has start date | You cannot amend the startDate of a futurePayId if it has already been set |
| E,Missing start date | You are attempting to start a FuturePay Regular agreement with no startDate |
| E,Start date must be >= 2 weeks in the future | You are attempting to start a FuturePay Regular agreement (option 1 or 2), with a startDate less than 2 weeks from now |
| E,Start date must be in the future | You are attempting to start a FuturePay Regular agreement with a startDate either today or in the past |
| E,Failed to set start date | WorldPay could not set the startDate of this futurePayId |
| E,Date format not understood - use yyyy-mm-dd | startDate not in recognised format |
| E,Agreement is not RFP | You cannot remotely set the startDate of a FuturePay Limited agreement |
<form action="https://select.worldpay.com/wcc/iadmin" method="post">
<input type="hidden" name="instId" value="XXXXX">
<input type="hidden" name="authPW" value="YYYYY">
<p>Enter the FuturePay Agreement to be cancelled: <input type="text" name="futurePayId" value="" size="10"></p>
<input type="hidden" name="op-cancelFP">
<input type="submit" name="cancel" value="Cancel this FuturePay Agreement">
</form>
You must use the response generated to determine the success of the request; FuturePay callback will not always be triggered.
| Response string | Meaning |
| Y,Agreement cancelled | You have successfully cancelled this futurePayId |
| E,Problem cancelling agreement | Could not cancel this futurePayId |
<form action="https://select.worldpay.com/wcc/iadmin" method="post">
<input type="hidden" name="instId" value="XXXXX">
<input type="hidden" name="authPW" value="YYYYY">
<p>Enter the amount to request from the FuturePay Regular Agreement: <input type="text" name="amount" value="" size="7"></p>
<p>Enter the FuturePay Regular Agreement to take payment from: <input type="text" name="futurePayId" value="" size="10"></p>
<input type="hidden" name="op-adjustRFP">
<input type="submit" name="setPayment" value="Set next payment(s)">
</form>
You must use the response generated to determine the success of the request; no FuturePay callback will be triggered.
| Response string | Meaning |
| Y,Amount updated | You have successfully updated the amount for this futurePayId |
| E,Not a RFP | You are attempting to alter the amount of a FuturePay Limited Agreement |
| E,Amount is fixed | For this futurePayId you cannot change the amount |
| E,Invalid amount | The amount specified is invalid, e.g. 199.9r |
| E,Inside warning period | Attempt to change amount inside the warning period for this futurePayId |
<form action="https://select.worldpay.com/wcc/iadmin" method="post">
<input type="hidden" name="instId" value="XXXXX">
<input type="hidden" name="authPW" value="YYYYY">
<p>Enter the amount to request from the FuturePay Limited Agreement: <input type="text" name="amount" value="" size="7"> (Merchant's currency)</p>
<p>Enter the FuturePay Limited Agreement to take payment from: <input type="text" name="futurePayId" value="" size="10"></p>
<input type="hidden" name="op-paymentLFP">
<input type="submit" name="setPayment" value="Take set payment">
</form>
You must use the response generated to determine the success of the request; FuturePay callback will not always be triggered.
| Response string | Meaning |
| Y,transId,A,rawAuthMessage,Payment successful | You have successfully debited this futurePayId |
| E,Agreement does not allow payment | This FuturePay Limited agreement has not yet started or the originally specified amountLimit has been reached |
| E,Not a LFP | You are attempting to debit from a FuturePay Regular Agreement |
| E,Payment amount cannot exceed limit! | Attempting to debit a FuturePay Limited Agreement beyond its limits |
|
The following messages, applicable only when attempting to debit a FuturePay Limited agreement, use transId for the resultant WorldPay transaction ID, and rawAuthMessage for either the authorisation code or indication of the failure. |
|
| N,transId,A,rawAuthMessage,Payment failed - customer's card failed | An attempted debit failed. The shopper should amend the payment details associated with this futurePayId |
| N,transId,A,rawAuthMessage,Payment failed - customer's WorldAccount has insufficient balance | An attempted debit failed. The shopper should amend the payment details associated with this futurePayId |
| N,transId,A,rawAuthMessage,Payment failed - merchant account is suspended | An attempted debit failed. Please contact your local Technical Support team with details of the error and the futurePayId you're using |
| N,transId,A,rawAuthMessage,Payment failed due to bank connection problem | There was an error in trying to submit the debit request; if retrying the request doesn't resolve the problem please contact your local Technical Support team with details of the error and the futurePayId you're using |
| N,transId,A,rawAuthMessage,Payment failed - customer's card has expired | An attempted debit failed. The shopper should amend the payment details associated with this futurePayId |
| N,transId,A,rawAuthMessage,Payment failed - unexpected exception | An attempted debit failed. Please contact your local Technical Support team with details of the error and the futurePayId you're using |
| N,transId,A,rawAuthMessage,Unknown result code | An attempted debit failed. Please contact your local Technical Support team with details of the error and the futurePayId you're using |
Below is a list of the responses provided when using the FuturePay Remote Administration code not covered specifically above. The mechanism by which you submit the request to WorldPay must also be able to capture and correctly interpret these responses.
| Response string | Meaning |
| E,Problem checking password | Either instId or authPW are incorrect. |
| E,Invalid agreement ID | Invalid futurePayId specified, e.g. 1009ed |
| E,Missing agreement ID | futurePayId not present |
| E,Problem building agreement | WorldPay could not retrieve details of this futurePayId |
| E,No such agreement | A non-existent futurePayId specified |
| E,Not company agreement | futurePayId does not belong to your Company ID |
| E,Problem checking ownership | WorldPay could not determine which Company ID owns this futurePayId |
| E,Agreement already complete, cancelled or suspended | Agreement complete, cancelled or suspended |
| E,Invalid operation | The op- variable is not known to WorldPay |
WorldPay performs all of its time calculations using GMT (also known as UTC).
When using FuturePay it is important to consider the following:
intervalUnit or startDelayUnit are 3 or 4), and a debit is due on a date which does not exist (e.g. 31 February 2004), the end of the debit interval will be the last date of the month (e.g. 29 February 2004).
When using FuturePay Regular the end of the debit interval means from when WorldPay will first attempt to debit the Agreement. When using FuturePay Limited this specifies the last date by which the debit can be initiated.
If timing is an important issue in your application, use thetransTimeparameter returned in the callback when the FuturePay Agreement was initially created as the starting point for your calculations. You could then calculate by when payments should normally be due (or by when changes or debit requests can be attempted).You could also use
transTime,transStatusanddescin FuturePay authorisation callbacks to determine when attempts were made, whether they were successful or not, and for which corresponding payment. For more details please see http://support.worldpay.com/kb/reference/faqs/callback_faqs.html#callback_futurepay.
If a shopper amends payment details associated with the FuturePay Agreement on the WorldPay Shopper Management System then any outstanding payments are attempted by WorldPay from the following day onwards, one attempt per day until either there are no outstanding payments or there have been three consecutive failures. In the latter case the Agreement will become suspended.
option 1 or 3, the debit interval behaviour is different, as explained in the table below:
intervalMult | intervalUnit | Maximum interval length within which noOfPayments may be taken |
1 | 1 | Per 1 day 00:00:00 through to 23:59:59 |
1 | 2 | Per 1 calendar week 00:00:00 GMT on Sunday through to 23:59:59 on Saturday |
1 | 3 | Per 1 calendar month 00:00:00 GMT on 1st of month through to 23:59:59 on last day of month |
1 | 4 | Per 1 calendar year 00:00:00 GMT on 1st January through to 23:59:59 on 31st December |
The number of intervals - either in part or full - within which noOfPayments may be taken is defined by the duration of the Agreement; i.e. the time from when it starts (set using either startDelayUnit and startDelayMult, an explicit startDate, or from when the Agreement is created if neither of these are specified), to when it is either cancelled or eventually expires (set using either lengthUnit and lengthMult, an explicit endDate, or never if neither of these are specified).
END
Last update: 08 July 2005