Accept CARD payments through own payment page (JavaScript)

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.

Lastly, processing a real-time card transaction.

Tokenised real-time card transaction
Tokenised real-time card transaction with payment details saved to record
OR simply save card details to a payer record to charge payer at a later time/date.

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

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:

HTML

<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):

HTML

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

HTML

<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.

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.

HTML

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

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:

HTML

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

HTML

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

HTML

<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):

HTML

<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.

HTML

<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.

HTML

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

HTML

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

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.

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

POST Make a live tokenized card transaction

Minimum property requirements:

‘processType’
‘reference’
‘amount’
‘cardtoken’

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

JSON

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

Example Request

JSON

{
    "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

JSON

{
    "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

JSON

{
    "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

JSON

{
  "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
}

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.

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

JSON

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

JSON

{
    "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

JSON

{
    "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

JSON

{
  "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
}

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.

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

JSON

{{url}}/businesses/{{business-id}}/payers/{{payer-reference}}/accounts/card/token

JSON

{
	"CardToken": "ebf672b8090e49cc815a140fc24b1e74",
    "Audit": {
      "Username": "Example-User",
      "UserIP": "1.2.3.4"
    }
}

Example Response

JSON

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

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

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.