Capturing cards using our iframe is the most secure process to capture and store cards thereby limiting your PCI exposure (PCI-DSS is a Payment Card Industry Data Security Standard for managing credit cards so they do not get leaked into the wrong hands). Using the iframe ensures credit card information is captured and stored directly in our secure PCI compliant Card Data Environment.
Pay Advantage hosts a Javascript library which simplifies the consumption of the Pay Advantage Credit Card iframe.
To integrate the iframe into your checkout page follow the below steps:
Step 1: Prepare your page
Add the following resources to your page.
<link rel="stylesheet" type="text/css"
href="https://api.payadvantage.com.au/v3/creditcardcapture.css" />
<script src="https://api.payadvantage.com.au/v3/creditcardcapture.js" />
Create an iframe using the code below. The class in the example is used by the CSS resource to control the height and width of the iframe so that it doesn’t show borders or scroll bars.
<iframe class="pay-advantage-credit-card-capture" src="" >
</iframe>
Step 2: Get a Unique Url
This documentation is deprecated
Please refer to the updated documentation https://docs.payadvantage.com.au/reference/credit_card_iframes_post-1
Using the Pay Advantage API, make a call to obtain an iframe Url to be consumed by your page. This Url will contain single-use nonce that verifies you have given permission for this iframe to be used on your account.
This creates a URL that initialises the Credit Card Capture IFrame for use. This URL is short lived and should be used to initialise the PayAdvantageCreditCardCapture once it is available.
POST: v3/credit_card_iframes
Parameter Name | Description |
Customer |
The customer who owns the credit card. |
Amount |
The amount of the payment. Set this to 0.00 to tokenise a card without charging it. |
Description |
The description of the payment. When the amount is 0.00, this field is ignored. |
OnchargeFees |
[Optional] Boolean. The desired intent of the payment and if the fee amount should be on charged. Default is: false |
ExternalID |
Your identifier for the payment. |
POST: https://api.payadvantage.com.au/v3/credit_card_iframes
{
"amount": 100.00,
"customer": {"code": "ABCDEF"},
"description": "Joining fee",
"externalID": "7871882773"
}
Response
Content-Type: application/json
{
"IFrameUrl":".../index.html?nonce=XXXX&nonce_type=credit_card_iframe"
}
Make the IFrameUrl property of the response available to your page.
This step will typically be achieved by making a call to your own backend service from your page or injected into the page from your server. This ensures that you keep your app and API credentials secure. It is not safe to handle this API request using the browser.
Step 3: Create an Instance of PayAdvantageCreditCardCapture
On your page, create an instance of PayAdvantageCreditCardCapture for controlling your iframe.
var captureIframe = document.querySelector('.pay-advantage-credit-card-capture');
var creditCardCapture = new PayAdvantageCreditCardCapture();
creditCardCapture
.initialise(captureIframe, yourUniqueUrl, cardHolderDetails)
.then(function(result) {
// Any logic goes here related to the iframe loading.
})
.catch(function(error) {
console.log(error);
});
Note: Creating an instance of PayAdvantageCreditCardCapture attaches handlers to the window object. You should dispose of the PayAdvantageCreditCardCapture instance when no longer required to release the handlers.
creditCardCapture.dispose();
References
initialise
Attaches an iframe and registers the iframe message listeners with the window. Once initialised, the iframe is valid for 30 minutes. After that time, its security will have expired and it will need to be reloaded.
PayAdvantageCreditCardCapture.initialise(
iframeElement: HTMLIFrameElement,
url: string,
options: {
showCard: true
},
cardHolderDetails?: {
firstName?: string,
lastName?: string,
email?: string,
address?: {
addressLine1?: string,
city?: string,
country?: string,
postcode?: string,
state?: string,
}
}
): Promise
Parameter Name | Description |
iframeElement | The iframe to attach this instance to. |
url |
The IFrameUrl that was returned by a successful call to https://api.payadvantage.com.au/v3/credit_card_iframes |
cardHolderDetails |
Pre-fills the card holders details when payer authentication is used. All of the values are optional, and the system will prompt the user to complete them when necessary.
|
addEventListener
PayAdvantageCreditCardCapture.addEventListener(
eventName: string,
listener: EventListenerOrEventListenerObject
): void
Parameter Name | Description |
eventName |
The name of the event. Currently supported options are: "change"- When a field on the form has been changed. "show-loader" – When a loading / busy overlay needs to be displayed and action buttons need to be disabled. "hide-loader" – When a loading / busy overlay can be removed and action buttons can be restored. "resize" – When the iframe changes size due to 3D Secure. "fee-calculated" - If on charge fee is true for the payment, this event will return the calculated fee with the following structure. Use totalAmount to show to the customer so they are aware of the incurred fees. { "fee-calculating" - If on charge fee is true for the payment, this will return true when the iframe is determining the fee for the charge "fee-calculate-error" - If on charge fee is true for the payment. This will return the error that has been produced when trying to determine the fee has failed. The payment can still be completed if the fee calculation has errors, but you should inform your customer that this payment will incur fees |
listener |
The listener to call when the event is triggered. |
removeEventListener
Removes an event listener that was added with addEventListener.
PayAdvantageCreditCardCapture.removeEventListener(
eventName: string,
listener: EventListenerOrEventListenerObject
): void
Parameter Name | Description |
eventName |
The name of the event. Currently supported options are "change", "show-loader", "hide-loader", "fee-calculating", "fee-calculate-error", "fee-calculated" and "resize". |
listener |
The listener to call when the event is triggered. |
dispose
Cleans up the object and releases event listeners.
PayAdvantageCreditCardCapture.dispose(): void
Step 4: Capturing the Card Details
The capture process will capture the card details and store it as a Customer Payment Account for that customer.
if (!creditCardCapture.checkValidity()) {
return false;
}
creditCardCapture
.authorize()
.then(function(result) {
// Save the credit card code for later use,
// Or use it to charge a card.
})
.catch(function(error) {
console.log(error);
});
References
checkValidity
Determines if all credit card fields are complete and valid (ready to capture).
PayAdvantageCreditCardCapture.checkValidity(): boolean
authorize
Attempts to store the card details entered into the iframe and returns the response.
PayAdvantageCreditCardCapture.authorize(): Promise
Response Example for a payment
{
"code": "Y7D7SA",
"externalID": null,
"description": "Invoice 123",
"createdBy": "An Awesome App",
"dateCaptured": "2022-10-07T08:40:26.027+11:00",
"dateCreated": "2022-10-07T08:40:25.963+11:00",
"amountCaptured": 100,
"amountCapturedIncFees": 100,
"payment": {
"dateFailed": null,
"failReason": null,
"failCode": null,
"code": "Z7D7SA"
},
"dateFailed": null,
"failReason": null,
"failCode": null,
"cvnCheckResponse": "matched",
"isProcessing": false,
"customerPaymentAccount": {
"code": "D7D7SA",
"dateFailed": null
},
"isUndetermined": false
}
Response Example for tokensing a card
{
"code": "UTY7SA",
"externalID": null,
"description": "store card",
"createdBy": "An Awesome App",
"dateCaptured": null,
"dateCreated": "2022-10-07T08:58:40.387+11:00",
"amountCaptured": null,
"amountCapturedIncFees": null,
"payment": null,
"dateFailed": null,
"failReason": null,
"failCode": null,
"cvnCheckResponse": "matched",
"isProcessing": false,
"customerPaymentAccount": {
"code": "D7D7SA",
"dateFailed": null
},
"isUndetermined": false
}
Comments
0 comments
Please sign in to leave a comment.