REST Guide

Overview

---

You can review the Windcave REST API reference for detailed API functions and message explanations.

For detailed information about integration models, features, functionality and detail about getting started with REST API please review the below page.

To get started with your Windcave REST API integration you will need a development account, please sign up for an account or contact us and complete the requirements gathering form to request development credentials.

Once signed up our team will create development credentials based on the requirements provided in the above form, we will provide a API username and API Key; both of which must be securely transferred and stored on your web-server.

PCI SAQ

---

PCI SAQ (Self-Assessment Questionnaires) are validation tools intended to assist merchants and service providers to report the results of their PCI DSS self-assessment. For further information on SAQs please see the PCI security standards website.

Different functionality/integration methods are available that fit into the varying PCI SAQ levels, this section will help define what level PCI SAQ is needed to integrate to the REST API functionality.

Before choosing your desired integration method it is recommended that you speak with your primary merchant acquirer to confirm they allow the use of said integration method.

SAQ A

The Hosted Payment Page (HPP) provides merchants a PCI SAQ level A compliant solution by hosting the payment page/card capture within Windcave's secure network. At point of payment customers are redirected from the merchants website to the Windcave hosted payment page to enter their payment details securely, once entered the customer is redirected back to the merchants website with the payment result ensuring all payment details are capture securely within Windcave's secure payment environment.

For further details on integrating see the Hosted Payment Page section.

SAQ A-EP

The Merchant Hosted Payment Page (MHPP) utilizing client side form post or AJAX Post provides merchants a PCI SAQ level A-EP compliant solution while allowing a more native in appearance payment page. At point of payment sensitive payment details are posted directly to the Windcave secure environment from the customers browser using either a form post or AJAX post integration, during the payment process the customer remains on the merchants website however payment details are not allowed to pass through the merchant server.

For further details on integrating see the Windcave Form Post or AJAX Post section respectively.

SAQ D

The Merchant Hosted Payment Page (MHPP) utilizing server side post provides merchants a PCI SAQ level D compliant solution where merchants utilize a fully native payment page. At point of payment sensitive payment details are posted from the merchant server direct to Windcave, with card details being captured on the merchant server merchants are required to be PCI SAQ level D compliant. This integration method may not be supported by all acquirers, as such please consult with your primary merchant acquirer or Windcave Sales team before proceeding with a MHPP server side post integration.

For further details on integrating see the Server Side Post section.

Hosted Payment Page

---

Please note this section is documented in terms of purchase transactions, however Auth/Complete and Validate transaction types are also supported in these examples.

The Windcave Hosted Payment Page (HPP) is a payment page hosted on the Windcave secure payment network, merchants redirect their customers to the Windcave HPP to safely and securely enter their payment details before being redirected back to the merchant's website.

Commonly referred to as a hosted payment solution this integration method requires the least amount implementation effort and the lowest PCI compliance standard (PCI SAQ Level A) while still maintaining high levels of customisation and functionality.

HPP is regularly used in online booking, shopping carts, bill payments, and many more applications where secure payment processing is required.

HPP Walkthrough

In order to provide each cardholder a secure HPP to enter their sensitive payment information a session is created in the Windcave host, this session handles all interactions between the user's browser and the Windcave secure host including any multi-stage payment interactions.

New sessions are created on request and triggered by the merchant web server sending a create session request, the newly created session will be given a session id which is used to reference the users payment while navigating between the merchant website and HPP.

The below flow diagram represents a high level HPP transaction flow from start to finish, more in-depth information for each stage of the flow is detailed in the next section.

Creating a Session

In order to provide the user with a payment page to enter their payment information the merchant webserver first needs to create a hosted payment page session.

This is achieved by the merchant webserver sending a create session request with the transaction specific information i.e. amount, currency, merchant reference and call back URL’s and merchant REST username and authentication. Below is an example of a simple create session request:

By default new sessions have a 72 hour timeout period, alternatively merchants can control when the session expires by using the expires field in the create session request.

For more in-depth information on sending a create session request and processing the response please refer to the API reference documentation here.

Redirecting the User

After requesting the HPP session the merchant webserver next needs to be able to redirect the user to the newly created HPP to securely enter their payment details.

To achieve this the merchant webserver must read the URL link where “rel” is “hpp” from the create session response, and redirect the user to it. Below is an example of a simple create session response body and the “rel” as “hpp” containing the URI of the HPP:

Also returned in the create session response is a URL that can be used in the Query Session request, this is read where the “rel” is “self” and is further detailed in the Obtaining the Transaction Result section.

For more in-depth information on sending a create session request and processing the response please refer to the API reference documentation here.

Entering Payment Information

After being redirected to the HPP the user will be presented with the available payment option(s) (a default option pre-selected based on the merchants REST user configuration) and an area to enter their payment information.

The user can review the payment details supplied by the merchant and if everything is correct enter their payment information and submit the transaction, alternatively if the details do not appear correct the user can cancel the payment.

Result Page

After submitting or cancelling the payment the user will be presented with a page displaying the result of their transaction along with transaction unique information for their reference.

Returning to the Merchant Website

After clicking next on the HPP result page the user is automatically redirected to the callback URLs specified in the create session request with a sessionId parameter in the URL.

Below is an example of the URL where the customer was redirected to the approved callback URL specified in the create session request.

Obtaining the Transaction Result

The merchant webserver now needs to obtain the result of the transaction to update its internal order system etc.

Upon receiving a response to any of the callback URLs the merchant webserver should extract the sessionId value, then submit a query session request to obtain the transaction result. Below is an example of the query session HTTPS GET request:

The response returned from the REST API contains the result of the specified session, this includes all transaction attempts made during the session. The merchant webserver must read the “authorised” attribute of the 0th transaction to determine the final result of the session, if true is returned the payment has been successfully authorized otherwise false will be returned to indicate payment has not been authorized.

Depending on individual merchant requirements additional details should be read and used to update the merchants internal order system. Below is a simple example of the query session response:

For more in-depth information on sending a query session request and processing the response please refer to the API reference documentation here.

HPP & FPRN

Fail Proof Result Notification (FPRN) helps ensure the merchant web application receives the payment outcome in scenarios such as; the cardholder not returning to the merchant website due to browser being closed prior or the merchant web server being temporarily unavailable just prior to the transaction being processed.

The HPP solution supports FPRN and it is enabled by default for any new account setups, for further information please see Fail Proof Result Notification.

iframe Embedded HPP

Using an iframe allows the merchant website to embed another webpage within their page, embedding the Hosted Payment Page into an iframe provides a sense of comfort and familiarity to end users who may be uneasy about being redirected away from the merchant website.

The below image shows examples of iframe implementations:

Implementing iframes

As explained in the HPP Walkthrough process merchants should redirect to the URL returned in the create session response where "rel" is "hpp", for iframe implementations the merchant should instead load the same URL into a responsive iframe on their checkout payment page; this way the HPP is embedded within their own webpage.

Merchants can use the below sample code to create a responsive iframe in their webpage, setting the value for the src attribute to the URL returned in the create session response where "rel" is "hpp":

Breaking out of an iframe

After the payment process has been completed, the HPP will be redirected back to the merchant's website per the callbackUrls nominated in the create session request. The merchant webpage should expect and handle this scenario appropriately by breaking out of the iframe once the payment result has been received.

Below is a JavaScript code snippet that can be set on the merchant callback webpage to break out of an iframe, this will result in the top page being redirected the URL of the iframe which should be the callbackUrl nominated in the create session request:

iframe css

The CSS example below demonstrates how a merchant webpage can control the size of the iframe based on the user's screen size, this is achieved by utilizing media queries to create breakpoints for different screen sizes:

Form Post

---

Please note this section is documented in terms of purchase transactions, however Auth/Complete and Validate transaction types are also supported in these examples.

The Merchant Hosted Payment Page (MHPP) form post integration utilizes a client side HTML form, the secure card data is securely posted from the cardholder's browser directly to the Windcave Host. With the MHPP form being hosted on the merchant's website it provides a merchant controlled UI experience for users.

This method may be preferred for merchants as there is no redirection for their customer, meaning they do not need to leave the merchant website to enter their payment details. This however will increase the PCI SAQ scope (SAQ A-EP) and this integration method is not supported by all acquirers, it is strongly recommended that you discuss with your chosen acquirer before proceeding with this integration method.

Form Post Walkthrough

For merchants to be able to securely post their users sensitive payment information from the client side form directly to Windcave; a session is created in the Windcave host for each payment.

New sessions are created on request and triggered by the merchant web server sending a create session request, the newly created session will be given a session id which is used to reference the users payment.

The below flow diagram represents a high level Form Post transaction flow from start to finish, more in-depth information for each stage of the flow is detailed in the next section.

Creating a Session

In order to be able to securely post the users sensitive payment information the merchant webserver first needs to create a form post session.

This is achieved by the merchant webserver sending a create session request with the transaction specific information i.e. amount, currency, merchant reference and call back URL’s and merchant REST username and authentication. Below is an example of a simple create session request:

By default new sessions have a 72 hour timeout period, alternatively merchants can control when the session expires by using the expires field in the Create Session request.

For more in-depth information on sending a create session request and processing the response please refer to the API reference documentation here.

Extracting the URL

After creating a session the merchant webserver next needs a URL that the client side form can use to post the users sensitive payment information to process payment.

To achieve this the merchant webserver must read the URL link where “rel” is “submitCard” from the Create Session response. Below is an example of a simple create session response body and the “rel” as “submitCard” containing the URL :

Also returned in the create session response is a URL that can be used in the query session request, this is read where the “rel” is “self” and is further detailed in the Obtaining the Transaction Result section.

For more in-depth information on sending a create session request and processing the response please refer to the API reference documentation here.

Rendering the Form

After requesting the MHPP session the merchant webserver next needs to be able to render the client side Merchant Hosted HTML form where customers can securely enter their payment details, this form must contain the below minimum required template of HTML form tag and input tag with the same name attribute:

Note: The merchant website should include client side validation on each card form field, especially validating CardNumber with a standard Luhn Check using standard JavaScript. Also including a basic future expiry date and CVC digits length check.

Entering Payment Information

The merchant webserver should now be presenting a HTML client side form to the user to enter their payment details into, the user will check all details i.e. amount and reference are correct before entering their sensitive payment information.

As this is a client side form the merchant webserver is not to have access to any of the data populated in these fields.

Post Form Data

After entering all their payment details the user clicks the submit button on the client side form, this should trigger the client side to securely post the sensitive payment data to the Windcave host directly using the HREF value entered into the HTML form.

Once received the Windcave host processes the transaction via the merchant's acquirer to the payment schemes.

Redirecting Customer to Callback URL

After completing all processing of the transaction the Windcave host will redirect the user to the Approved/Declined/Cancelled callback URL nominated in the create session request by the merchant webserver.

Appended to the Approved/Declined/Cancelled callback URL will be the session id, here the merchant webserver will capture this session id before proceeding to the next stage.

Below is an example of the URL where the customer was redirected to the approved callback URL specified in the create session request.

Obtaining the Transaction Result

The merchant webserver now needs to obtain the result of the transaction to update its internal order system etc.

Upon receiving a response to any of the callback URLs the merchant webserver should extract the sessionId value, then submit a query session request to obtain the transaction result. Below is an example of the query session HTTPS GET request:

The response returned from the REST API contains the result of the specified session, this includes all transaction attempts made during the session. The merchant webserver must read the “authorised” attribute of the 0th transaction to determine the final result of the session, if true is returned the payment has been successfully authorized otherwise false will be returned to indicate payment has not been authorized.

Depending on individual merchant requirements additional details should be read and used to update the merchants internal order system. Below is a simple example of the query session response:

For more in-depth information on sending a query session request and processing the response please refer to the API reference documentation here.

Form Post & FPRN

Fail Proof Result Notification (FPRN) helps ensure the merchant web application receives the payment outcome in scenarios such as; the cardholder not returning to the merchant website due to browser being closed prior or the merchant webserver being temporarily unavailable just prior to the transaction being processed.

The Form Post solution supports FPRN and it is enabled by default for any new account setups, for further information please see Fail Proof Result Notification.

AJAX Post

---

Please note this section is documented in terms of purchase transactions, however Auth/Complete and Validate transaction types are also supported in these examples.

The Merchant Hosted Payment Page (MHPP) AJAX post integration utilizes a client-side form, the secure card data is securely posted from the cardholder's browser directly to the Windcave Host. With the MHPP form being hosted on the merchant's website it allows merchants to offer a more native payment page experience.

AJAX or Asynchronous JavaScript and XML involves the loading of data in the background and displaying it on the webpage without reloading the whole page, for more information about AJAX you can refer to https://www.w3schools.com/jquery/jquery_ajax_intro.asp.

This method may be preferred for merchants as there is no redirection for their customer, meaning they do not need to leave the merchant website to enter their payment details. This however will increase the PCI SAQ scope (SAQ A-EP) and this integration method is not supported by all acquirers, it is strongly recommended that you discuss with your chosen acquirer before proceeding with this integration method.

AJAX Post Walkthrough

The below flow diagram represents a high-level AJAX Post transaction flow from start to finish, more in-depth information for each stage of the flow is detailed in the next section.

Creating a Session

In order to be able to securely post the users sensitive payment information the merchant web server first needs to create an AJAX POST session; this is achieved by the merchant web server sending a create session request.

Below is an example of a simple create session request:

For more in-depth information on sending a create session request and processing the response please refer to the API reference documentation.

Handling the Session Response

Upon receiving the create session response the merchant web server must extract the URL link where "rel" is "ajaxSubmitCard", this URL must be stored for use in the AJAX POST action when submitting payment details.

Additionally, the merchant web server must extract the unique session id from the id field in the response, this should be retained and associated with your own cart session; merchants must ensure the session Id referenced is always the Id expected for the current cart session.

Below is an example of a simple create session response:

For more in-depth information on processing the response please refer to the API reference documentation.

Rendering the MHPP

A MHPP client-side payment form must be rendered to allow the cardholder to enter their payments details, how the MHPP is rendered is the responsibility of the merchant however the below fields must be included at a minimum:

It is recommended that client-side validation such as performing a Luhn check to validate the cardNumber field, basic future expiry date check and CVC digit length check be performed before submitting the data to the Windcave host.

AJAX Request (POST)

Upon MHPP submission trigger an AJAX POST request is sent to the AJAX Post endpoint (ajaxSubmitCard URL), the body of the request is in JSON format with a card object containing the payment details entered into the MHPP form.

Below is an example of the AJAX POST request:

Once received the Windcave host processes the transaction via the merchant's acquirer to the payment schemes.

Handling the AJAX Response

Upon receiving a response, the merchants AJAX must ensure the response is for the current cart session, this is done by comparing the id value returned to that stored from the create session response.

Please note if the appropriate callbackUrls were populated in the create session request this will also be returned in the response, merchants can choose to redirect the page to the link where "rel" is "done" however this is optional.

Below is an example of an AJAX Response:

Obtaining the Transaction Result

To obtain the result of the transaction the merchant web server must submit a query session request using the id stored from the create session response.

Below is an example of a query session request:

The response to the query session request includes all transaction attempts during the specified session, the merchant web server must read the “authorised” attribute of the 0th transaction to determine the final result of the session; if true is returned the payment has been successfully authorized otherwise false will be returned and indicates the payment has not been authorized.

Optionally merchants may read and use additional details in the response to update their internal order system.

Below is a simple example of the query session response:

For more in-depth information on sending a query session request and processing the response please refer to the API reference documentation.

AJAX Post & FPRN

Fail Proof Result Notification (FPRN) helps ensure the merchant web application receives the payment outcome in scenarios such as; the cardholder prematurely closes the merchant website or the merchant webserver being temporarily unavailable just prior to the transaction being processed.

The AJAX Post solution supports FPRN and it is enabled by default for any new account setups, for further information please see Fail Proof Result Notification.

Server Side Post

---

Please note this section is documented in terms of purchase transactions, however Auth/Complete and Validate transaction types are also supported in these examples.

The Merchant Hosted Payment Page (MHPP) server side post integration utilizes a server side form, the secure card data is posted from the merchant webserver directly to the Windcave host. As the MHPP is hosted on the merchant's website it allows merchants to offer a fully native payment page experience.

This method may be preferred for some merchants as the fully native payment page provides further control and capture of full card details. This however will increase the PCI SAQ scope (SAQ D) and this integration method is not supported by all acquirers, it is strongly recommended that you discuss with your chosen acquirer before proceeding with this integration method.

Please note merchants may be requested to provide their PCI-DSS Attestation of Compliance (AOC) to Windcave before proceeding with integrating to this method, a Non-Disclosure Agreement (NDA) may be put in place prior to sharing the PCI-DSS AOC.

Server Side Walkthrough

The below flow diagram represents a high level server side post transaction flow from start to finish, more in-depth information for each stage of the flow is detailed in the next section.

Capturing Payment Information

In order to process payment the merchant webserver first needs to securely capture the customer's sensitive payment information, this is handled by the merchant but should meet PCI-DSS security standards to ensure customer's data is safe.

Create Transaction Request

In order to process payment for the user the merchant webserver must securely post the payment details to the Windcave host, this is achieved by submitting a Create Transaction request via the REST API. Below is an example of a simple create transaction request:

After sending the payment request the merchant webserver needs to obtain the transaction result so that the customer can be alerted of the outcome of their transaction.

In order to obtain the transaction result the merchant webserver needs to parse the create transaction response for the authorised field, this field will indicate true if the transaction was approved or false if the transaction was declined. Below is an example of a simple create transaction response:

In the event the transaction is still being processed by the parties involved the REST API will respond to the merchant webserver 10 seconds after the initial request was received, this ensures the merchant webserver has confirmation the request was received and has a means of checking the result once the transaction has been processed. Below is an example of a simple create transaction response where the transaction was not processed within the 10 seconds:

Once received the merchant webserver can periodically submit the query transaction request by reading the URL link where “rel” is “self”, the query transaction response will return a HTTP 202 Accepted response if the transaction is still being processed.

The query transaction response will return a HTTP 200 OK response if the transaction has finished processing. Below is an example of a query transaction response where the transaction has been processed:

In order to obtain the transaction result the merchant webserver needs to parse the query transaction response for the authorised field, this field will indicate true if the transaction was approved or false if the transaction was declined.

For more in-depth information on sending a create transaction request and processing the response please refer to the API reference documentation here.

Displaying The Transaction Result

After discovering the result of the transaction the merchant webserver is required to display the transaction result to the user, this can be done by simply redirecting the user to a success/failure page indicating the result of the payment but how this is managed is entirely up to the merchant's webserver.

Server Side Post & FPRN

Fail Proof Result Notification (FPRN) helps ensure the merchant web application receives the payment outcome in scenarios such as; the merchant webserver being temporarily unavailable just prior to the transaction being processed.

The Server-Side Post solution supports FPRN and it is enabled by default for any new account setups, for further information please see Fail Proof Result Notification.

Fail Proof Result Notification

---

Fail Proof Result Notification (FPRN) is a Windcave server-side service, it is designed to provide an additional level of assurance that the merchant web server receives notification of the payment outcome.

In the event the merchant web server is temporarily unavailable when the cardholder's payment is being finalized or if the cardholder prematurely closing their browser before navigating back to the merchant's webpage, these are scenarios where FPRN can provide assistance to help ensure the merchant web server can obtain the payment outcome.

Implementing FPRN

Merchants implementing FPRN should include the notificationUrl field in their Create Session or Create Transaction request, this field should be populated with the merchant's endpoint that will accept and handle the FPRN notifications. Please note the notificationUrl should not require cookies in the request to function, the FPRN notification is sent from Windcave not the cardholders browser.

Below is an example of a simple Create Session request with notificationUrl:

Below is an example of a simple Create Transaction request with notificationUrl:

By default, FPRN notifications are sent immediately upon session or transaction completion; it is sent in the form of a HTTP GET request with a query string parameter of sessionId or transactionId appended. Using the query string parameter the merchant web server can initiate a Query Session or Query transaction request to obtain the outcome of the payment.

Upon receiving the notification, the merchant notificationUrl should resolve to a HTTP 200, 302 or 303 HTTP status code, this indicates to the Windcave Host that the notification has been successfully received.

In the event the merchants notificationUrl is unreachable or returns any HTTP status code other than 200 (OK) or 404 (Not Found), the Windcave host will reattempt sending of the FPRN notification. For more information about reattempts please see FPRN Reattempts.

Merchant FPRN Guidelines

To ensure the merchant web application is in the best position to acknowledge the outcome of each and every FPRN notification, merchants should ensure the below guidelines are adhered to:

FPRN Reattempts

If the merchants notificationUrl is unreachable or returns any HTTP status code other than 200 (OK), 404 (Not Found) or 502 (Bad Gateway), FPRN will reattempt sending the notification according to the Restful users FPRN configuration. By default, FPRN notifications are reattempted once every 10minutes for the first hour after which time it will be reattempted once every hour for the next 24 hours.

Windcave recommend using the default configuration where possible, however custom FPRN configurations can be created for merchants that have unique notification reattempt requirements.

Additionally, if required an email address can be configured for custom FPRN reattempts, in the event all reattempts have failed an email will be sent to the configured address with a subject line indicating that FPRN has failed for a particular transactionId.

FPRN HTTP POST

By default, the FPRN notification is sent as a HTTP GET request, this can however be configured per Restful API username to send a HTTP POST request if preferred/required by merchants.

Once enabled on the Restful API username, the Windcave host will send a HTTP POST request instead of a HTTP GET request to the merchant web server. The content of the HTTP POST request follows the Query Transaction response format for all Restful integration methods, this means the payment result is returned directly in the FPRN notification and no additional request is required. For further information regarding the format of the HTTP POST content, please refer to the query transaction response section of the API reference documentation.

FPRN Custom Features

The below are custom FPRN features that can be enabled if required:

• Custom FPRN HTTP Status Behavior
• Custom FPRN Query String Parameters
• Static URL FPRN
• Custom FPRN Send Delay

Stored Card

---

Merchants can utilize Stored Card functionality to generate a secure token of the payment card used at checkout, with the cardholder’s permission merchants can use this token to speed up the checkout process for future payments or process recurring payments.

3D Secure & Rebilling

Stored Card Tokens

Merchants utilizing stored card functionality will be returned a Windcave generated multiuse token, this token links to the stored card credentials at Windcave and allows the merchant to initiate future payments initiated by the cardholder or by the merchant on the cardholder's behalf.

The default token type returned is a cardId, this token is a 16-digit numeric value. The cardId value does not have a one-to-one relationship with the card number, as such multiple captures of the same card will generate different cardId values.

Supported Payment Methods

Not all payment methods support stored card functionality, by default any non-supported payment methods will not be available for selection on the HPP when the storeCard field is set to "true".

Below are the payment methods that currently support stored card functionality:

• card
• visacheckout

Windcave can enable non supported payment methods to be available on the HPP even if storeCard is set to "true", however these payment methods will NOT return a stored card token value in the final transaction response.

Stored Card Implementation

Stored Card Indicators

Mandates from the major card schemes require merchants indicate the reason a card is being stored and/or stored card being charged at time of payment.

To comply with these mandates merchants must include the appropriate storedCardIndicator in the Create Session or Create Transaction request, the value used depends on the payments position in the rebilling sequence.

Stored Card Indicators can be broken into three groups:

• Initial - Payment is the first/initial transaction in the rebilling sequence
• Established - Payment is a continuation of an already established rebilling sequence
• Industry Specific Business Practice (ISBP) - Special use cases for Industry Specific Business Practices

Initial Stored Card Indicators

The below storedCardIndicator values should be used for the initial payment in the rebilling sequence, this could be at the time of storing the card or when the cardholder/merchant are initiating a new rebilling sequence i.e., cardholder adds a new subscription to their account.

storedCardIndicator	Description	Additional Requirements
credentialonfileinitial	Cardholder will save card and for future orders the cardholder selects to reuse the saved card for the one-off payment.
unscheduledcredentialonfileinitial	Cardholder will save their card and for future order based on an event (such as top-up) the merchant will reuse the saved card on behalf of the cardholder for the one-off payment.
recurringfixedinitial	Cardholder will save their card and merchant will reuse the saved card on behalf of cardholder for the subscribed recurring payments of fixed amount e.g., monthly account fee for streaming service	Merchants must also include the fields recurringExpiry and recurringFrequency in the Create Session/Create Transaction Request.
recurringvariableinitial	Cardholder will save their card and merchant will reuse the saved card on behalf of cardholder for the subscribed recurring payments of variable amount e.g., recurring payment for power bill where amount due may vary	Merchants must also include the fields recurringExpiry and recurringFrequency in the Create Session/Create Transaction Request.
installmentinitial	Cardholder will save their card and merchant will reuse the saved card on behalf of cardholder for the installment payments.	Merchants must also include the fields installmentCount and installmentNumber in the Create Session/Create Transaction Request.

Established Stored Card Indicators

The below storedCardIndicator values should be used for payments that are part of an already established rebilling sequence, this could be the next monthly payment in the cardholders billing cycle or cardholder using their saved card to make a one-off payment.

storedCardIndicator	Description	Additional Requirements
credentialonfile	Cardholder selects their saved card to make the one-off payment.
unscheduledcredentialonfile	Merchant initiated and event driven one-off rebilling with stored card (e.g., auto top-ups).
recurringnoexpiry	Merchant initiated recurring transaction with a stored card token where no card expiry check needs to occur (e.g., subscriptions).	Merchants must also include the fields recurringExpiry and recurringFrequency in the Create Session/Create Transaction Request.
recurringfixed	Merchant initiated recurring transaction with a stored card token (e.g., subscriptions) where amount is fixed e.g., monthly account fee for streaming service	Merchants must also include the fields recurringExpiry and recurringFrequency in the Create Session/Create Transaction Request.
recurringvariable	Merchant initiated recurring transaction with a stored card token (e.g., subscriptions) where amount is varied e.g., monthly power bill payment	Merchants must also include the fields recurringExpiry and recurringFrequency in the Create Session/Create Transaction Request.
installment	Merchant initiated rebilling payments in installments with a stored card token.	Merchants must also include the fields installmentCount and installmentNumber in the Create Session/Create Transaction Request.

ISBP Stored Card Indicators

The below storedCardIndicator values should be used for industry specific business practices only.

storedCardIndicator	Description	Additional Requirements
partialshipment	Merchant initiated transaction with token for part of a shipment e.g., shipping items as they become available and taking payment for only items shipped.
incremental	Merchant initiated incremented transaction amount to rebill e.g., hospitality or rentals etc.
resubmission	Merchant resubmits rebill with token where it requested an authorization but may have received a decline due to insufficient funds and the order already delivered to the cardholder. Used with the token to get an outstanding payment from cardholder.
reauthorisation	Merchant initiated when the completion or conclusion of the original order or service extends beyond the authorization validity. Common for retail (split or delayed shipments) and hospitality or rental services scenarios.
delayedcharges	Merchant initiated to process additional account rebill charge after original order and payment has already been processed and fulfilled.
noshow	Merchant initiated to charge the cardholder a penalty relevant to the merchant’s cancellation policy. Common for guaranteed reservations scenarios (e.g., Hospitality).

Recurring Expiry & Frequency

Some storedCardIndicator require the merchant web application to include a recurringExpiry and recurringFrequency to outline the frequency and end of the recurring payments.

The below outlines the requirements for the recurringExpiry and recurringFrequency fields:

Field	Value	Additional Notes
recurringExpiry	YYYY-MM-DD	Configured to the date the recurring payments will end/expire. For scenarios where no expiry/end date is established i.e., subscription payments, the merchant web application should use "9999-12-31" as the value.
recurringFrequency	daily weekly every2weeks every4weeks monthly monthly28th monthlylastcalendarday monthlysecondlastcalendarday monthlythirdlastcalendarday twomonthly threemonthly sixmonthly annually	Configured to one of the value options listed and indicates the frequency recurring payments for the stored card.

Storing Phase

It is at this phase that the merchant web application requests a card be stored for future rebilling, the process below outlines the deviations from the standard integration walkthrough process detailed here: HPP, Form Post, AJAX Post or Server-Side Post.

When sending a Create Session/Create transaction request to store a card, the merchant web application must set the storeCard boolean to "true" and include an appropriate storedCardIndicator in their request.

Below is an example of a basic Create Session request with storeCard and storedCardIndicator included:

Below is an example of a basic Create Transaction request with storeCard and storedCardIndicator included:

Once the payment has been processed and the merchant web application has received the final Query Session/Create Transaction response, the merchant web application needs to extract and store the token value.

The cardId token is stored in the card object of the transaction record, the merchant web application should extract the value from the id field of the card object and associate/store this against their account records for the cardholder.

Below is an example of a basic card object with a cardId token:

Rebilling Phase

It is at this phase that the merchant web application requests a stored card be rebilled, the process below outlines the deviations from the standard integration walkthrough process detailed here: HPP, Form Post, AJAX Post or Server-Side Post.

When sending a Create Session/Create Transaction request to rebill a stored card, the merchant web application must include the token value and an appropriate storedCardIndicator in their request.

Create Session Rebill

Below is an example of a basic Create Session request with cardId and storedCardIndicator included:

Once the session has been created the merchant web application should:

• HPP Implementations must redirect the cardholder to the HPP link, if no further input is required the cardholder will be redirected to appropriate callback URL; alternatively the cardholder may be prompted to input further details, see Rebilling Exception Scenarios for further information and examples.
• Form Post Implementations must Post the client-side form even if no card data i.e., expiry date or CVC is to be included.
• AJAX Post Implementations must Post the client-side AJAX request even if no card data i.e., expiry date or CVC is to be included.

Create Transaction Rebill

Below is an example of a basic Create Transaction request with cardId and storedCardIndicator included:

Once the Create Transaction request has been submitted the merchant web application should follow the Server-Side Post Walkthrough process to obtain the transaction result.

Rebilling Exception Scenarios

Outlined below are exceptions scenarios to the standard rebilling process where additional data or input is required:

Expired Card on Rebill

If the card associated with a token has expired, the cardholder can be prompted to enter a new expiry if their card issuer has reissued the same card with a new expiry.

The merchant web application should follow the below guidelines when encountering this scenario:

HPP Implementations

For merchants using a HPP implementation, upon redirecting the customer if the card to be used has expired the cardholder will be prompted to input a new expiry date into the HPP:

Once submitted the payment result will be returned per the standard HPP Walkthrough procedure.

Form Post Implementations

For merchants using a Form Post implementation, upon receiving declined transaction result the merchant web application can validate if the dateExpiryMonth and dateExpiryYear fields of the card object have expired or not.

If the card has expired the merchant web application should prompt the cardholder to input a new expiry or choose to provide a different payment card; this is achieved by rendering a client-side merchant hosted HTML form with only the ExpiryMonth and ExpiryYear form inputs (If the cardholder opts to provide a different payment card, then the standard Form Post Walkthrough procedure should be followed).

Once submitted the client-side HTML form should post the content of the ExpiryMonth and ExpiryYear fields as Key Values directly to the Windcave Form Post URL, the payment result will be handled per the standard Form Post Walkthrough procedure.

AJAX Post Implementations

For merchants using an AJAX Post implementation, upon receiving declined transaction result the merchant web application can validate if the dateExpiryMonth and dateExpiryYear fields of the card object have expired or not.

If the card has expired the merchant web application should prompt the cardholder to input a new expiry or choose to provide a different payment card; this is achieved by rendering a client-side merchant hosted form with only the dateExpiryMonth and dateExpiryYear inputs (If the cardholder opts to provide a different payment card, then the standard AJAX Post Walkthrough procedure should be followed).

Once submitted the client-side form should post the dateExpiryMonth and dateExpiryYear fields directly to the Windcave AJAX Post URL, the payment result will be handled per the standard AJAX Post Walkthrough procedure.

Server-Side Post Implementations

For merchants using a Server-Side Post implementation, upon receiving a declined transaction result the merchant webserver can validate if the dateExpiryMonth and dateExpiryYear fields of the card object have expired or not.

If the card has expired the merchant webserver should prompt the cardholder to input a new expiry or choose to provide a different payment card; how this is implemented is the responsibility of the merchant (If the cardholder opts to provide a different payment card, then the standard Server-Side Post Walkthrough procedure should be followed).

Once submitted the updated dateExpiryMonth and dateExpiryYear fields should be sent in the Create Transaction request, the payment result will be handled per the standard Server-Side Post Walkthrough procedure.

CVC Capture on Rebill

Some acquirers or merchant may require or prefer to capture the card security code (CVC) from the cardholder when rebilling a token.

The merchant web application should follow the below guidelines when encountering this scenario:

HPP Implementations

For merchants using a HPP implementation, the CVC capture on rebilling is handled by Windcave on the HPP.

Unless mandated by your acquirer CVC capture on rebilling is disabled by default, if you would like to enable CVC capture on rebilling, please contact [email protected] with your Rest username.

Once enabled when processing a rebilling transaction, the cardholder will be prompted to input their CVC once redirected to the HPP, the CVC input can be set to mandatory (CVC must be entered before proceeding) or optional (cardholder is prompted but not required to input their CVC).

Once submitted the payment result will be returned per the standard HPP Walkthrough procedure.

Form Post Implementations

For merchants using a Form Post implementation, the client-side merchant hosted HTML form should be rendered with only the Cvc2 input.

Once submitted the client-side HTML form should post the content of the Cvc2 field as a Key Value directly to the Windcave Form Post URL, the payment result will be handled per the standard Form Post Walkthrough procedure.

AJAX Post Implementations

For merchants using an AJAX Post implementation, the client-side merchant hosted form should be rendered with only the cvc2 input.

Once submitted the client-side form should post the content of the cvc2 field directly to the Windcave AJAX Post URL, the payment result will be handled per the standard AJAX Post Walkthrough procedure.

Server-Side Post Implementations

For merchants using a Server-Side Post implementation, the merchant webserver should request the cardholder input their cvc2; how this is implemented is the responsibility of the merchant.

Once submitted the updated cvc2 field should be sent in the Create Transaction request, the payment result will be handled per the standard Server-Side Post Walkthrough procedure.