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" text="text/css"
href="https://api.payadvantage.com.au/v3/creditcardcapture.css" />
<script src="https://api.payadvantage.com.au/v3/creditcardcapture.js" />

Step 2: Create an iframe placeholder on your web application.

The CSS class in the iframe code block below is used by the CSS script resource imported above 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 3: Get a Unique iframe Url

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 token that verifies you have given permission for this iframe to be used on your account.

This step must be completed by your backend server. You will need to create an API call from your front end to the back end to return the iframe URL. This is because the URL /credit_card_iframe endpoint requires your Pay Advantage bearer token which should always be kept safe in your backend. It is not safe to handle this API request directly using the browser.

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.

Make the IFrameUrl property of the response available to your page.

API CALL POST: v3/credit_card_iframes

Example with no pre-filled card:

POST: <https://api.payadvantage.com.au/v3/credit_card_iframes>  
{  
 	"Customer:{
 		"Code":"ABC123" 
 	},
 	"Amount": 9000.00,
 	"OnChargeFees: true,  
 	"Description": "Joining fee",  
 	"ExternalID": "7871882773"  
}  
Response

Content-Type: application/json  
{  
  "IFrameUrl":".../index.html?nonce=XXXX&nonce_type=credit_card_iframe"  
}

Example with pre-tokenized card:

POST: <https://api.payadvantage.com.au/v3/credit_card_iframes>  
{  
 	"Customer:{
 		"Code":"ABC123" 
 	},
 	"Amount": 9000.00,
 	"OnChargeFees: true,  
 	"Description": "Joining fee",  
 	"ExternalID": "7871882773",
  "CustomerPaymentAccount":{
  	"Code":"ABC123",
    "CanChange":true
  }
}  
Response

Content-Type: application/json  
{  
  "IFrameUrl":".../index.html?nonce=XXXX&nonce_type=credit_card_iframe"  
}

Step 4: 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, IFrameUrl, options, 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

📘

Initialise - Attaches an iframe and registers the iframe message listeners with the window object. 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

addEventListener

PayAdvantageCreditCardCapture.addEventListener(  
  eventName: string,  
  listener: EventListenerOrEventListenerObject  
): void

removeEventListener

Removes an event listener that was added with addEventListener.

PayAdvantageCreditCardCapture.removeEventListener(  
  eventName: string,  
  listener: EventListenerOrEventListenerObject  
): void

dispose

Cleans up the object and releases all event listeners. This should be called to clean up the iframe set up once it is no longer needed.

PayAdvantageCreditCardCapture.dispose(): void

Step 5: 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

Example of 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": {  
    //store this code to charge this card later using the charge API
    "code": "D7D7SA",  
    "dateFailed": null  
  },  
  "isUndetermined": false  
}

Example of Tokenisation

{  
  "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": {  
    //store this code to charge this card later using the charge API
    "code": "D7D7SA",  
    "dateFailed": null  
  },  
  "isUndetermined": false  
}

You will need to store the customerPaymentAccount.code so that you can charge
the card later using Charge a Stored/Tokenised Card.

JSDoc Documentation

For further documentation of the iframe objects, ultilise the JSDoc information provided in the creditcardcapture.js file located here: https://api.payadvantage.com.au/v3/creditcardcapture.js