Versions Compared

Old Version 3

changes.mady.by.user Joseph De Jesus IV

Saved on

compared with

New Version 4

changes.mady.by.user Joseph De Jesus IV

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This guide will allow you to incorporate the Payrix JavaScript library to your application to accept payments via Card. The JavaScript will tokenise the data on the page and can be used to either add the card details entered to an existing payer or it can be used to make a live (real-time) card transaction against the card details.

  1. Including the JavaScript

  2. Adding the <form> element

  3. Adding your business key

  4. Adding a token placeholder

  5. Adding elements for card details

  6. Adding the error indicator

  7. Adding the progress indicator

  8. Adding the submit button

Lastly, processing a real-time card transaction.

If you have now saved the card data against the payer record you can process ongoing/recurring payments via the 2 methods below:

JavaScript steps - building your webpage

Anchor
Including-the-JavaScript
Including-the-JavaScript
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:

Code Block
languagehtml
<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>

Anchor
form-element
form-element
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):

Code Block
languagehtml
<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.

Anchor
business-key
business-key
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:

Code Block
languagehtml
<input data-integrapay="BusinessKey" type="hidden" value="{{business-key}}" />
Info

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.

PLEASE NOTE CCV cannot be captured for recurring payments. You can use the code below to hide the CCV input filed. CCV is still required for Live or “Real-Time” transactions, therefore you may need two input fields.

Code Block
languagehtml
<input id="cardCvv" type="hidden" value="000" data-integrapay="CardCcv" />

Anchor
token-placeholder
token-placeholder
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:

Code Block
languagehtml
<input data-integrapay="CardToken" name="CardToken" type="hidden" />

Anchor
elements-for-card-details
elements-for-card-details
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:

Code Block
languagehtml
<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:

Code Block
languagehtml
<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):

Code Block
languagehtml
<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>

Anchor
error-indicator
error-indicator
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.

Info

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.

Code Block
languagehtml
<div data-integrapay="Errors"></div>

Anchor
progress-indicator
progress-indicator
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.

Code Block
languagehtml
<div data-integrapay="Processing"></div>

Anchor
submit-button
submit-button
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:

Code Block
languagehtml
<button data-integrapay="SubmitButton" type="button">Process Payment</button>

Anchor
single-live-tokenised-card-transaction
single-live-tokenised-card-transaction
Making a single live tokenised card transaction

This function submits a single credit card payment to the bank and returns a result in real-time. The payment can be a complete payment that will be processed and the funds settled to the business, or it can be a pre-authorisation that will hold the funds until you Process a pre authorised card transaction or the pre-authorisation expires.

This call requires a token generated from the Tokenize Card endpoint. For more details on how to tokenize the card, click here.

Info

Usually transactions will be processed by the bank and a result returned to you within a couple of seconds, however delays in the bank networks can occur from time to time so you should ideally enable your system to be able to wait up to 90 seconds to get a transaction result.

API

...

Sample

POST Make a live tokenized card transaction

Minimum property requirements:

  • ‘processType’

  • ‘reference’

  • ‘amount’

  • ‘cardtoken’

Info

Refer to Tokenized Card Transaction Model for more information around the API properties.

Depending on the workflow of your application, the tokenised card payment can still be allocated to a Payer Reference only if a Payer Record has been created previously:

  • If a Payer record has been created, you can still allocate the payment to the payer by sending the ‘UniqueReference’ in the API Payer body with ‘SavePayer’ parameter set to ‘false’. This will still allow you to allocate the payment to the specific payer record for single one-off payments but is not required.

  • If there is no Payer record in the database, and you attempt to allocate the payment to a uniqueReference that does not exist, it will prompt an error at the completion of the payment page.

    • To Create a Payer Record

      • POST Add a New Payer

        • Minimum fields in Payer Property:

          • ‘UniqueReference'

          • ‘FamilyorBusinessName’

          • ‘GivenName’

          • ‘Email’

Sample

Example Request

Code Block
languagejson
{{url}}/businesses/{{business-id}}/transactions/card-payments/token

Example Request

Code Block
languagejson
{
    "ProcessType": "COMPLETE",
    "Reference": "REAL-TIME-TXN-003",
    "Description": "This is an example real-time transaction",
    "Amount": 20.00,
    "CardToken": "6040ac298a41417bb19f263158043918",
    "Payer": null,
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

Example Request with allocation to Payer Record

Code Block
languagejson
{
    "ProcessType": "COMPLETE",
    "Reference": "REAL-TIME-TXN-100",
    "Description": "This is an example real-time transaction",
    "Amount": 100.25,
    "CurrencyCode": "AUD",
    "CardToken": "cbd86c35289249eb86759453cea4025b",
    "ServiceDate": "2024-04-04T10:00:00+10:00",
    "Payer": {
    	"uniqueReference": "JavaScript UR-P1",
    	"groupReference":"JavaScript GR-P1",
    	"familyOrBusinessName":"Surname",
    	"givenName":"First Name",    	
    	"email":"test@test.com",
    	"savePayer":"false"
    },
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

Example Response for successful transaction

Code Block
languagejson
{
    "transactionId": "RT1055931",
    "reference": "REAL-TIME-TXN-100",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": null,
    "processedAmount": 100.25,
    "cardType": "Visa",
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}

Example Response for failed/rejected transaction

Code Block
languagejson
{
  "transactionId": "59583",
  "reference": "REAL-TIME-TXN-101",
  "statusCode": "F",
  "subStatusCode": "R1",
  "statusDescription": "Insufficient Funds",
  "processedAmount": 20.61,
  "cardType": "Visa",
  "redirectId": null,
  "redirectUrl": null,
  "cardAuthorizationReference": null
}

Anchor
live-tokenised-card-transaction-+-Save-Payer-Data
live-tokenised-card-transaction-+-Save-Payer-Data
Making a live tokenised card transaction + Save Payer Data

Same as above, this function submits a single credit card payment to the bank and returns a result in real-time, however the SavePayer property allows the payers payment data to be saved in the secure Payrix Vault to allow for ongoing/recurring payments.

Info

If you intend to SavePayer you will need to supply and have a DDR (Direct Debit Request) agreement in place with the payer. Refer to the eDDR and Payment Page Requirement to assist in compliance and we will support you through the compliance requirements.

API

...

POST Make a live tokenized card transaction

Minimum property requirements:

  • ‘processType’

  • ‘reference’

  • ‘amount’

  • ‘cardtoken’

  • ‘Payer’

    • Minimum fields in Payer Property:

      • ‘UniqueReference'

      • ‘FamilyorBusinessName’

      • ‘GivenName’

      • ‘Email’

    • Set ‘SavePayer’ parameter = ‘true’

Sample

Example Request

Code Block
languagejson
{{url}}/businesses/{{business-id}}/transactions/card-payments/token
Code Block
languagejson
{
    "ProcessType": "COMPLETE",
    "Reference": "REAL-TIME-TXN-100",
    "Description": "This is an example real-time transaction",
    "Amount": 100.25,
    "CurrencyCode": "AUD",
    "CardToken": "cbd86c35289249eb86759453cea4025b",
    "ServiceDate": "2024-04-01T10:00:00+10:00",
    "Payer": {
        "uniqueReference": "JavaScript UR-P1",
    	"groupReference":"JavaScript GR-P1",
    	"familyOrBusinessName":"Surname",
    	"givenName":"First Name",
    	"email":"test@test.com",
    	"savePayer":"true"
    },
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
  }

Example Response for successful transaction

Code Block
languagejson
{
    "transactionId": "RT1055931",
    "reference": "REAL-TIME-TXN-100",
    "statusCode": "S",
    "subStatusCode": null,
    "statusDescription": null,
    "processedAmount": 100.25,
    "cardType": "Visa",
    "redirectId": null,
    "redirectUrl": null,
    "cardAuthorizationReference": null
}

Example Response for failed/rejected transaction

Code Block
languagejson
{
  "transactionId": "59583",
  "reference": "REAL-TIME-TXN-101",
  "statusCode": "F",
  "subStatusCode": "R1",
  "statusDescription": "Insufficient Funds",
  "processedAmount": 20.61,
  "cardType": "Visa",
  "redirectId": null,
  "redirectUrl": null,
  "cardAuthorizationReference": null
}

Anchor
Add-or-update-a-Payers-card-details-via-token
Add-or-update-a-Payers-card-details-via-token
Add or update a Payers card details via token

This function will give you the ability to attach a card to one of your existing payers without the sensitive card information passing through your servers, which frees you from a significant portion of the PCI Compliance obligations. To use this function simply send through the Token you receive when the payment details form that you have wired-up with our JavaScript library is posted-back to your server.

Info

A payer can only have one payment method account - calling this function will replace any existing bank account or card attached to this payer with the new card.

API

...

POST Add or update a Payers card details via token

To add or update a payers card details via token, a payer record must initially be created:

  • To Create a Payer Record

    • POST Add a New Payer

      • Minimum fields in Payer Property:

        • ‘UniqueReference'

        • ‘FamilyorBusinessName’

        • ‘GivenName’

        • ‘Email’

Once a payer record has been created, you can add or update their card details via token.

Sample

Example Request

Code Block
languagejson
{{url}}/businesses/{{business-id}}/payers/{{payer-reference}}/accounts/card/token
Code Block
languagejson
{
	"CardToken": "ebf672b8090e49cc815a140fc24b1e74",
    "Audit": {
      "Username": "Example-User",
      "UserIP": "1.2.3.4"
    }
}

Example Response

Code Block
languagejson
{
  "accountId": "139842-3",
  "type": "CARD",
  "card": {
    "cardNumber": "411111xxxxxx1111",
    "cardholderName": "TEST CARD",
    "cardExpires": "2027-11-01T00:00:00",
    "cardType": "Visa"
  },
  "bankAccount": null
}

Anchor
Recurring-Payment-solutions-after-Saving-Payer-Payment
Recurring-Payment-solutions-after-Saving-Payer-Payment
Implement Recurring Payment solutions after Saving Payer Payment Data

Once a payers card payment data has been saved to the Payrix Vault via the payment solutions above, to collect future payments, the Payrix platform offers 3 solutions:

  • Process a transaction using saved card details / charge stored card

    • Processes a real-time card transaction on the card account registered to the payers account

  • Schedule a single payment

    • A non real-time card transaction allowing you to schedule a payment to be processed on the current or future date

  • Schedule multiple future payments

    • A non real-time card transaction allowing you to schedule multiple future payments to be processed on the current and future date

Info

Should your application intend to utilise the scheduling API, refer to the Scheduling API guide here for steps to initiate a scheduled debit.

Refer to the links to implement a recurring payment solution after saving payer data:

This concludes the API workflow of implementing the Payrix JavaScript and ongoing payments to your application. Refer to our other methods available for accepting payments.