%20(1).png)
Accept card (no 3DS) payments - Partner software managed payment page
Introduction
This developer guide will allow you to incorporate our JavaScript library to your application to accept card payments within your application. The JavaScript will tokenise the data on the page and can be used to submit an eCommerce card transaction or update the card details stored on file.
Finally you can then submit a transaction request for an eCommerce guest checkout type payment or an eCommerce subscription type for ongoing future payments via the POST Make a live tokenized card transaction.
Flowchart to accept card through Partner software managed page
JavaScript steps - building your webpage
Including the JavaScript
In the <head> element of your webpage, add a <script> tag to include the JavaScript that is used to tokenise payment card details. For the following, replace {{api-url}} with either the sandbox (test) or production (live) URL for the REST API, as appropriate:
<head>
<script src="https://code.jquery.com/jquery-3.2.1.min.js" integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4=" crossorigin="anonymous"></script>
<script src="{{api-url}}/js/tokenize-card"></script>
</head>Adding the <form> element
In the <body> element of your webpage, add a <form> tag to contain the elements used to accept payment card details from payers. The <form> tag must include a data-integrapay attribute with a value of PaymentForm to allow the imported JavaScript to identify this element.
After the JavaScript has tokenised the payment card details, the <form> will be submitted automatically. This can be used to trigger further actions; for example, causing the payer's web browser to navigate to the URL specified for the action attribute (for the following, replace {{action-url}} with your own URL):
<body>
<form data-integrapay="PaymentForm" method="POST" action="{{action-url}}">
</form>
</body>As well as tokenising the payment card details, the JavaScript will clear the elements used to accept the card number and security code (CCV/CVV) values. This helps to reduce your PCI compliance obligations by ensuring that your web server does not receive confidential information about payment cards.
Adding your business key
In the <form> element, add a hidden <input> tag to specify the BusinessKey of the organisation for which the payment card details are to be tokenised. The business key is a "public" identifier that allows the tokenisation to occur without prior authentication; the tokenised details can only be accessed with authentication and authorisation.
The <input> tag must include a data-integrapay attribute with a value of BusinessKey to allow the imported JavaScript to identify this element. For the following, replace {{business-key}} with the business key for the organisation:
<input data-integrapay="BusinessKey" type="hidden" value="{{business-key}}" />
Please note the BusinessKey aka BusinessGUID can be obtained using the Check your business details call. This will change when changed over to the Live system.
Adding a token placeholder
In the <form> element, add a hidden <input> tag as a placeholder for the token that is created when the JavaScript tokenises the payment card details. The <input> tag must include a data-integrapay attribute with a value of CardToken to allow the imported JavaScript to identify this element.
After the JavaScript has tokenised the payment card details, the value attribute of the <input> tag will contain the token for the card. To access the token, either specify an id attribute for the <input> tag and read it using your own JavaScript, or specify a name attribute to include the token as a parameter when the <form> is submitted, as follows:
<input data-integrapay="CardToken" name="CardToken" type="hidden" />Adding elements for card details
In the <form> element, add text <input> tags to accept cardholder name, card number and security code (CCV/CVV) values, and <select> tags to accept card expiry month and year values. For each of the <input> tags, include an autocomplete attribute with a value of off to help avoid the accidental storage of confidential information about payment cards, which in turn helps to reduce your PCI compliance obligations.
The <input> and <select> tags must include a data-integrapay attribute to allow the imported JavaScript to identify them, as follows:
Card Detail | Element Type | Attribute Value |
|---|---|---|
cardholder name | <input> | CardName |
card number | <input> | CardNumber |
card expiry month | <select> | CardExpiryMonth |
card expiry year | <select> | CardExpiryYear |
security code | <input> | CardCcv *Only for Real-Time Transactions |
After the JavaScript has tokenised the payment card details, it will clear the elements used to accept the card number and security code values. To access the values of the other elements, either specify an id attribute for the tags and read them using your own JavaScript, or specify a name attribute for the tags to include them as parameters when the <form> is submitted, as follows:
<input data-integrapay="CardName" name="CardName" type="text" autocomplete="off" />
<input data-integrapay="CardNumber" type="text" autocomplete="off" />
<select data-integrapay="CardExpiryMonth" name="CardExpiryMonth">
<!-- card expiry month options -->
</select>
<select data-integrapay="CardExpiryYear" name="CardExpiryYear">
<!-- card expiry year options -->
</select>
<input data-integrapay="CardCcv" type="text" autocomplete="off" />In the <select> element for the card expiry month, add an <option> tag for each calendar month that includes a <value> attribute with a value of the month number as two digits left-padded with zero, from 01 for January to 12 for December. The display text for each <option> is your choice, but we recommend using either the two-digit month number, as appears on payment cards, or an abbreviated month name, as follows:
<select data-integrapay="CardExpiryMonth" name="CardExpiryMonth">
<option value="01">Jan</option>
<option value="02">Feb</option>
<option value="03">Mar</option>
<option value="04">Apr</option>
<option value="05">May</option>
<option value="06">Jun</option>
<option value="07">Jul</option>
<option value="08">Aug</option>
<option value="09">Sep</option>
<option value="10">Oct</option>
<option value="11">Nov</option>
<option value="12">Dec</option>
</select>In the <select> element for card expiry year, add an <option> tag for each of the next five or more years, starting with the current year, that includes a value attribute of the year as four digits. The display text for each <option> is your choice, but we recommend using the four-digit year, as follows (at the time of writing, the year was 2018):
<select data-integrapay="CardExpiryYear" name="CardExpiryYear">
<option value="2018">2018</option>
<option value="2019">2019</option>
<option value="2020">2020</option>
<option value="2021">2021</option>
<option value="2022">2022</option>
</select>Adding the error indicator
In the <form> element, add a <div> tag to contain the error indicator that is used to notify the payer if any problems occur while the JavaScript tokenises the payment card details. The <div> tag must include a data-integrapay attribute with a value of Errors to allow the imported JavaScript to identify this element.
Note that if payers are notified about problems that occurred during the tokenisation process, then the <form> is not submitted automatically by the JavaScript. This allows payers a chance the fix the problem and try again.
<div data-integrapay="Errors"></div>
Adding the progress indicator
In the <form> element, add a <div> tag to contain the progress indicator that is displayed while the JavaScript tokenises the payment card details. The <div> tag must include a data-integrapay attribute with a value of Processing to allow the imported JavaScript to identify this element.
The process of tokenising the payment card details includes asynchronous communication between the payer's web browser and IntegraPay web services. This can take a few moments to complete, so a progress indicator is displayed automatically to let payers know that your webpage is busy, not broken.
<div data-integrapay="Processing"></div>
Adding the submit button
In the <form> element, add a <button> tag to allow payers to submit their credit card details for tokenisation. The <button> tag must include a data-integrapay attribute with a value of SubmitButton to allow the imported JavaScript to identify this element.
To allow the JavaScript to tokenise the credit card details before the <form> is submitted, the <button> tag must include a type attribute with a value of button; not a value of submit. If the wrong value is specified, then tokenisation will not occur and your web server will receive confidential information about payment cards, raising your PCI compliance obligations.
The display text for the <button> is your choice, but should be chosen to indicate the purpose for which the tokenised payment card details will be used. For example, if the next action taken by your website is to process a payment using the tokenised details, then we suggest using Process Payment for the display text, as follows:
<button data-integrapay="SubmitButton" type="button">Process Payment</button>API steps to accept eCommerce guest checkout
The process to accept eCommerce guest checkout can be implemented through the below steps:
Allow up to 5 - 10 seconds to retrieve response and result of transaction request
Result returned
If successful, transaction statuscode: S - Successful
Payment flow complete - Funds to be settled as per business rules
If unsuccessful, transaction statuscode: F - Failed
Payment flow complete - Application to manage collection of failed attempt
If the intitial transaction has failed, you can simply re-direct your end user to the beginning of your checkout page to re-attempt the payment. You will need to supply a unique transaction reference for each transaction attempt.
API steps to accept eCommerce subscription checkout for ongoing payments
The beginning steps are the same as a guest checkout and will require extra steps to submit ongoing payment requests:
POST Make a live tokenized card transaction
Set property ProcessType = COMPLETE to submit a $ value amount payment
Set property ProcessType = VERIFY to submit a Zero-Dollar Authentication if you do not wish to take a $ value amount payment at the time or you a simply updating card details on file.
Allow up to 5 - 10 seconds to retrieve response and result of transaction request
Result returned
If successful, transaction statuscode: S - Successful
Payment flow complete - Funds to be settled as per business rules
If unsuccessful, transaction statuscode: F - Failed
Payment flow complete - Application to manage collection of failed attempt
Most software services already contain the information regarding the Payer and when they are to be charged. In this case it is much simpler for the software to manage the schedule and send a request on the day required. You have 2 options:
POST Process a transaction using saved card details
Real-time payment request submission
Real-time transaction result
Following the initial successful transaction of the first HPP, your application will have the authority to charge the account holder as and when required by the business via the POST Process a transaction using saved card details
Schedule a single payment
Processed and debited via banking system
2 business day result time
Schedule single or multiple payments:
Determine result of scheduled debit - GET Search for transaction status change
Remove transaction from data set - POST Acknowledge transaction status change
Test Card details
Within the Sandbox environment, you can test card transactions using the card examples below:
CVC = Any 3 digit number
Expiry Date = Any future date
Card Type | Test Card Numbers |
|---|---|
| 4111111111111111 |
| 5353535353535351 |
| 378282246310005 |
How to simulate failed transactions?
When using the test API, the transaction amount gives you the ability to test both successful and failed payments. When the transaction amount has zero cents or a number of cents other than the ones listed below, the test transaction will always be successful. If you provide one of the following numbers for the number of cents you will receive a transaction failed response with the corresponding reason:
31 = Invalid Account
54 = Expired card - Card Only
51 = Declined
61 = Insufficient Funds
96 = Technical failure - Card Only
Compliance requirements
When accepting card or bank account payments through a non-worldpay hosted payment page, the PCI and banking compliance regulations fall under your softwares responsbility. As you may be aware, every organisation that handles card payments must comply with the Payment Card Industry Data Security Standard (PCI DSS). Annual compliance is mandated by the payment card schemes and banks. Due to this there are certain requirements that need to be met when building a Payment Page. Refer to our Risk and Compliance guide to assist you through the payment page requirements and eDDR requirements.