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.


PCI SAQ


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.


HPP Diagram


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:


Endpoint:

POST   https://sec.windcave.com/api/v1/sessions


Headers:

Content-Type:application/json

Authorization: Basic ABC123


Request Body:

{

  "type": "purchase",

  "amount": "1.00",

  "currency": "NZD",

  "merchantReference": "1234ABC",

    "callbackUrls": {

    "approved": "https://example.com/success",

    "declined": "https://example.com/fail",

    "cancelled": "https://example.com/cancel"

  },

  "notificationUrl": "https://example.com/txn_result?123"

}


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:


HTTP Response Code:

202 Accepted


Response Body:

{

  "id": "00001200030240010c9e7ceadd26a6d8",

  "state": "init",

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/pxmi3/EF4054F622D6C4C1B512FC9E81F547FA45A6ED23237FF3B236283493E38BF97630A40CC2F072621C2",

      "rel": "hpp",

      "method": "REDIRECT"

    }

  ]

}


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.


https://example.com/success?sessionId=00001200030240010c9e7ceadd26a6d8


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:


Endpoint:

GET   https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8

Headers:

Content-Type:application/json

Authorization: Basic ABC123


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:


HTTP Response Code:

200 OK


Response Body:

{

  "id": "00001200030240010c9e7ceadd26a6d8",

  "state": "complete",

  "type": "purchase",

  "amount": "1.00",

  "currency": "NZD",

  "currencyNumeric": 554,

  "merchantReference": "1234ABC",

  "expires": "2020-05-11T03:06:07Z",

  "storedCardIndicator": "single",

  "callbackUrls": {

    "approved": "https://example.com/success",

    "declined": "https://example.com/fail",

    "cancelled": "https://example.com/cancel"

  },

  "notificationUrl": "https://example.com/txn_result?123",

  "storeCard": true,

  "clientType": "internet",

  "methods": ["card"],

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/api/v1/transactions/0000000c01159507",

      "rel": "transaction",

      "method": "GET"

    }

  ],

  "transactions": [

    {

      "id": "0000000c01159507",

      "username": "TestUser",

      "authorised": true,

      "reCo": "00",

      "responseText": "APPROVED",

      "authCode": "001543",

      "type": "purchase",

      "method": "card",

      "localTimeZone": "NZT",

      "dateTimeUtc": "2020-05-08T03:06:27Z",

      "dateTimeLocal": "2020-05-08T15:06:27+12:00",

      "settlementDate": "2020-05-08",

      "amount": "1.00",

      "balanceAmount": "0.00",

      "currency": "NZD",

      "currencyNumeric": 554,

      "clientType": "internet",

      "merchantReference": "1234ABC",

      "card": {

        "id": "0000120001291154",

        "cardHolderName": "JOHN T DOE",

        "cardNumber": "411111........11",

        "dateExpiryMonth": "05",

        "dateExpiryYear": "23",

        "type": "visa"

      },

      "cvc2ResultCode": "U",

      "storedCardIndicator": "single",

      "notificationUrl": "https://example.com/txn_result?123",

      "sessionId": "00001200030240010c9e7ceadd26a6d8",

      "isSurcharge": false,

      "liabilityIndicator": "standard",

      "links": [

        {

          "href": "https://sec.windcave.com/api/v1/transactions/0000000c01159507",

          "rel": "self",

          "method": "GET"

        },

        {

          "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

          "rel": "session",

          "method": "GET"

        },

        {

          "href": "https://sec.windcave.com/api/v1/transactions",

          "rel": "refund",

          "method": "POST"

        }

      ]

    }

  ]

}


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


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.


Form Post


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:


Endpoint:

POST   https://sec.windcave.com/api/v1/sessions


Headers:

Content-Type:application/json

Authorization: Basic ABC123


Request Body:

{

  "type": "purchase",

  "amount": "1.00",

  "currency": "NZD",

  "merchantReference": "1234ABC",

  "language": "en",

  "methods": ["card"],

  "callbackUrls": {

    "approved": "https://example.com/success",

    "declined": "https://example.com/fail",

    "cancelled": "https://example.com/cancel"

  },

  "notificationUrl": "https://example.com/txn_result?123"

}


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 :


HTTP Response Code:

202 Accepted


Response Body:

{

  "id": "00001200030240010c9e7ceadd26a6d8",

  "state": "init",

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/pxmi3/E494B52F483B328E3B259646A63FAF64AAC05E252FF87EB6A623D2C5817CA0B3C75B8B9176333D6EA",

      "rel": "submitCard",

      "method": "FORM_POST"

    }

  ]

}

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:


<form method="post" enctype="multipart/form-data" action=" INSERT HREF VALUE HERE ">

<input type="text" name="CardNumber" minlength="14" maxlength="16" />

<input type="text" name="CardHolderName" maxlength="64"/>

<input type="text" name="ExpiryMonth" minlength="2" maxlength="2" />

<input type="text" name="ExpiryYear" minlength="2" maxlength="2" />

<input type="text" name="Cvc2" minlength="3" maxlength="4" />

<input type="submit" value="Submit" />

</form>


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.


https://example.com/success?sessionId=00001200030240010c9e7ceadd26a6d8


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:


Endpoint:

GET   https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8


Headers:

Content-Type:application/json

Authorization: Basic ABC123


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:


HTTP Response Code:

200 OK


Response Body:

{

  "id": "00001200030240010c9e7ceadd26a6d8",

  "state": "complete",

  "type": "purchase",

  "amount": "1.00",

  "currency": "NZD",

  "currencyNumeric": 554,

  "merchantReference": "1234ABC",

  "expires": "2020-05-11T03:06:07Z",

  "storedCardIndicator": "single",

  "callbackUrls": {

    "approved": "https://example.com/success",

    "declined": "https://example.com/fail",

    "cancelled": "https://example.com/cancel"

  },

  "notificationUrl": "https://example.com/txn_result?123",

  "storeCard": true,

  "clientType": "internet",

  "methods": ["card"],

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/api/v1/transactions/0000000c01159507",

      "rel": "transaction",

      "method": "GET"

    }

  ],

  "transactions": [

    {

      "id": "0000000c01159507",

      "username": "TestUser",

      "authorised": true,

      "reCo": "00",

      "responseText": "APPROVED",

      "authCode": "001543",

      "type": "purchase",

      "method": "card",

      "localTimeZone": "NZT",

      "dateTimeUtc": "2020-05-08T03:06:27Z",

      "dateTimeLocal": "2020-05-08T15:06:27+12:00",

      "settlementDate": "2020-05-08",

      "amount": "1.00",

      "balanceAmount": "0.00",

      "currency": "NZD",

      "currencyNumeric": 554,

      "clientType": "internet",

      "merchantReference": "1234ABC",

      "card": {

        "id": "0000120001291154",

        "cardHolderName": "JOHN T DOE",

        "cardNumber": "411111........11",

        "dateExpiryMonth": "05",

        "dateExpiryYear": "23",

        "type": "visa"

      },

      "cvc2ResultCode": "U",

      "storedCardIndicator": "single",

      "notificationUrl": "https://example.com/txn_result?123",

      "sessionId": "00001200030240010c9e7ceadd26a6d8",

      "isSurcharge": false,

      "liabilityIndicator": "standard",

      "links": [

        {

          "href": "https://sec.windcave.com/api/v1/transactions/0000000c01159507",

          "rel": "self",

          "method": "GET"

        },

        {

          "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

          "rel": "session",

          "method": "GET"

        },

        {

          "href": "https://sec.windcave.com/api/v1/transactions",

          "rel": "refund",

          "method": "POST"

        }

      ]

    }

  ]

}


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


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.

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

For merchants to be able to securely post their users sensitive payment 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 AJAX Post transaction flow from start to finish, more in-depth information for each stage of the flow is detailed in the next section.

Form Post


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:


Endpoint:

POST   https://sec.windcave.com/api/v1/sessions


Headers:

Content-Type:application/json

Authorization: Basic ABC123


Request Body:

{

  "type": "purchase",

  "amount": "1.00",

  "currency": "NZD",

  "merchantReference": "1234ABC",

  "language": "en",

  "methods": ["card"],

  "callbackUrls": {

    "approved": "https://example.com/success",

    "declined": "https://example.com/fail",

    "cancelled": "https://example.com/cancel"

  },

  "notificationUrl": "https://example.com/txn_result?123"

}


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 “ajaxSubmitCard” from the create session response. Below is an example of a simple create session response body and the “rel” as “ajaxSubmitCard” containing the URL :


HTTP Response Code:

202 Accepted


Response Body:

{

  "id": "00001200030240010c9e7ceadd26a6d8",

  "state": "init",

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/mh/E1D1D31611F02E8BC13676A3B745A14FC850CB6CE344120667D8A6C095D1A395F8D05253B14C4C4EC",

      "rel": "ajaxSubmitCard",

      "method": "AJAX_POST"

    }

  ]

}


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 Payment Page, this is where customers can securely enter their payment details.

How the form is rendered is the responsibility of the merchant webserver, however the data from the form is to be submitted as JSON data in the same format as the API card object. See the Post Form Data section for further details about submitting the data.

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 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 merchant webserver to post the data directly to Windcave.

The merchant webserver submits using an alternative link utilizing the AJAX method, each of the payment fields submitted are JSON data in the same format as the API card object per below example:


Endpoint:

POST   https://sec.windcave.com/mh/E1D1D31611F02E8BC13676A3B745A14FC850CB6CE344120667D8A6C095D1A395F8D05253B14C4C4EC


Headers:

Content-Type:application/json


Request Body:

{

  "card": {

    "cardHolderName": "JOHN T DOE",

    "cardNumber": "4111111111111111",

    "dateExpiryMonth": "01",

    "dateExpiryYear": "18",

    "cvc2": "111"

  }

}


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

Please note the sensitive payment data must come from the browser directly and restful credentials MUST NOT be used.


Redirecting the Customer

Once the transaction has been processed a response will be sent to the merchant webserver, the body of the response containing “rel” as “done” and a URL. This indicates the customer needs to be redirected by the merchant webserver to the URL returned. Below is an example of this response:


HTTP Response Code:

200 OK


Response Body:

{

  "id": "00001200036244160cd3eed722903bc5",

  "links": [

    {

      "href": "https://example.com/success?sessionId=00001200036244160cd3eed722903bc5",

      "rel": "done",

      "method": "REDIRECT"

    }

  ]

}


Appended to the URL will be the session id, the merchant webserver will capture this session id before proceeding to the next stage.


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:


Endpoint:

GET   https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8


Headers:

Content-Type:application/json

Authorization: Basic ABC123


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:


HTTP Response Code:

200 OK


Response Body:

{

  "id": "00001200030240010c9e7ceadd26a6d8",

  "state": "complete",

  "type": "purchase",

  "amount": "1.00",

  "currency": "NZD",

  "currencyNumeric": 554,

  "merchantReference": "1234ABC",

  "expires": "2020-05-11T03:06:07Z",

  "storedCardIndicator": "single",

  "callbackUrls": {

    "approved": "https://example.com/success",

    "declined": "https://example.com/fail",

    "cancelled": "https://example.com/cancel"

  },

  "notificationUrl": "https://example.com/txn_result?123",

  "storeCard": true,

  "clientType": "internet",

  "methods": ["card"],

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/api/v1/transactions/0000000c01159507",

      "rel": "transaction",

      "method": "GET"

    }

  ],

  "transactions": [

    {

      "id": "0000000c01159507",

      "username": "TestUser",

      "authorised": true,

      "reCo": "00",

      "responseText": "APPROVED",

      "authCode": "001543",

      "type": "purchase",

      "method": "card",

      "localTimeZone": "NZT",

      "dateTimeUtc": "2020-05-08T03:06:27Z",

      "dateTimeLocal": "2020-05-08T15:06:27+12:00",

      "settlementDate": "2020-05-08",

      "amount": "1.00",

      "balanceAmount": "0.00",

      "currency": "NZD",

      "currencyNumeric": 554,

      "clientType": "internet",

      "merchantReference": "1234ABC",

      "card": {

        "id": "0000120001291154",

        "cardHolderName": "JOHN T DOE",

        "cardNumber": "411111........11",

        "dateExpiryMonth": "01",

        "dateExpiryYear": "23",

        "type": "visa"

      },

      "cvc2ResultCode": "U",

      "storedCardIndicator": "single",

      "notificationUrl": "https://example.com/txn_result?123",

      "sessionId": "00001200030240010c9e7ceadd26a6d8",

      "liabilityIndicator": "standard",

      "links": [

        {

          "href": "https://sec.windcave.com/api/v1/transactions/0000000c01159507",

          "rel": "self",

          "method": "GET"

        },

        {

          "href": "https://sec.windcave.com/api/v1/sessions/00001200030240010c9e7ceadd26a6d8",

          "rel": "session",

          "method": "GET"

        },

        {

          "href": "https://sec.windcave.com/api/v1/transactions",

          "rel": "refund",

          "method": "POST"

        }

      ]

    }

  ]

}


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


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.


Server Side Post


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:


Endpoint:

POST   https://sec.windcave.com/api/v1/transactions


Headers:

Content-Type:application/json

Authorization: Basic ABC123


Request Body:

{

  "type": "purchase",

  "amount": "12.34",

  "currency": "NZD",

  "merchantReference": "1234ABC",

  "card": {

    "cardHolderName": "JOHN T DOE",

    "cardNumber": "4111111111111111",

    "dateExpiryMonth": "01",

    "dateExpiryYear": "22",

    "cvc2": "111"

  }

}


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:


HTTP Response Code:

201 Created


Response Body:

{

  "id": "0000000c01541fe6",

  "username": "TestUser",

  "authorised": true,

  "allowRetry": false,

  "reCo": "00",

  "responseText": "APPROVED",

  "authCode": "011744",

  "type": "purchase",

  "method": "card",

  "localTimeZone": "NZT",

  "dateTimeUtc": "2020-07-02T02:18:26Z",

  "dateTimeLocal": "2020-07-02T14:18:26+12:00",

  "settlementDate": "2020-07-02",

  "amount": "12.34",

  "currency": "NZD",

  "currencyNumeric": 554,

  "clientType": "internet",

  "merchantReference": "1234ABC",

  "card": {

    "cardHolderName": "JOHN T DOE",

    "cardNumber": "411111........11",

    "dateExpiryMonth": "01",

    "dateExpiryYear": "22",

    "type": "visa"

  },

  "cvc2ResultCode": "U",

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/transactions/0000000c01541fe6",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/api/v1/transactions",

      "rel": "refund",

      "method": "POST"

    }

  ]

}


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:


HTTP Response Code:

202 Accepted


Response Body:

{

  "id": "0000000c015257e1",

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/transactions/0000000c015257e1",

      "rel": "self",

      "method": "GET"

    }

  ]

}


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:


HTTP Response Code:

200 OK


Response Body:

{

  "id": "0000000c01541fe6",

  "username": "TestUser",

  "authorised": true,

  "allowRetry": false,

  "reCo": "00",

  "responseText": "APPROVED",

  "authCode": "011744",

  "type": "purchase",

  "method": "card",

  "localTimeZone": "NZT",

  "dateTimeUtc": "2020-07-02T02:18:26Z",

  "dateTimeLocal": "2020-07-02T14:18:26+12:00",

  "settlementDate": "2020-07-02",

  "amount": "12.34",

  "currency": "NZD",

  "currencyNumeric": 554,

  "clientType": "internet",

  "merchantReference": "1234ABC",

  "card": {

    "cardHolderName": "JOHN T DOE",

    "cardNumber": "411111........11",

    "dateExpiryMonth": "01",

    "dateExpiryYear": "22",

    "type": "visa"

  },

  "cvc2ResultCode": "U",

  "links": [

    {

      "href": "https://sec.windcave.com/api/v1/transactions/0000000c01541fe6",

      "rel": "self",

      "method": "GET"

    },

    {

      "href": "https://sec.windcave.com/api/v1/transactions",

      "rel": "refund",

      "method": "POST"

    }

  ]

}


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.



contact us