Hosted Fields API Documentation

What Does the Iframe Do?

The iframe provided by PayArc allows merchants to securely collect credit card information directly on their website while maintaining the site’s look and feel. It ensures that sensitive card data is handled by PayArc’s secure infrastructure, reducing the merchant's PCI compliance responsibilities.

By seamlessly integrating with the merchant’s payment flow, the iframe generates a token that can be used for transaction processing without storing sensitive information on the merchant's servers. This improves security, simplifies compliance, and provides a seamless experience for customers.

Business Description

PayArc provides a token that can be used later to justify a financial movement. The token is obtained by providing credit card information. To blend into the merchant’s site and maintain the look and feel of the merchant’s portal, PayArc provides access to iframes that must be embedded in the site.

Technical Integration

Overview

In order for PayArc to get credit card data input from a merchant’s site, several steps must be completed:

Set constants for the merchant’s PayArc API key, names of the containers, and target endpoint.
Define the callback for PayArc’s interaction.
Manage the look and feel by updating styles provided by PayArc.
Place input components in the body of the page.

PayArc uses iframes to provide HTML containers for customers to input credit card data. It expects to get information from containers with predefined names.

Constants

The following JavaScript constants must be set:

PAYARC_API_KEY: The merchant’s specific ID obtained from the Merchant's dashboard API section.

PAYARC_INITIAL_VALUES: Allows you to override predefined container names.
- FORM_STATUS: Identifier of the container.
- INITIATE_PAYMENT: Name of the HTML object (button) ID that triggers token generation.
- FIELDS_CONTAINER: Name of the card iframe elements container.
- TOKEN_CALLBACK: Name of the function for the JavaScript callback.
- walletPayment: Object (only required if you want to enable your customers to use wallet payments)
```
// Code Example
const walletPayment = {
    amount: 5000, // Transaction amount in cents ($50.00)
    onTokenReceived: function(token) {
        console.log("Card Token:", token);
        // Perform further actions with the token here
    },
    onWindowOpened: function() {
        console.log("Payment window opened.");
        // You can prompt the user to continue in the opened payment window
    },
    onWindowClosed: function() {
        console.log("Payment window closed.");
        // Handle cleanup or retry logic here
    },
    windowWidth: 400,
    windowHeight: 300,
    html: "<div id='google-pay-placeholder'></div><div id='apple-pay-placeholder'></div>",
    css: "div { text-align: center; }"
};
```
  - amount*: integer *value in cents
    - The amount parameter specifies the transaction amount to be processed for wallet payments (e.g., Apple Pay or Google Pay). It is a required field within the walletPayment object.
  - onTokenReceived: function(token)
    - The onTokenReceived callback is an optional parameter used specifically when enabling wallet payments (e.g., Apple Pay or Google Pay). When passed as part of the walletPayment object, this callback function will handle tokens generated from wallet payments instead of using the default TOKEN_CALLBACK function.
  - onWindowOpened: function()
    - The onWindowOpened callback is an optional parameter that signals when a payment window has been successfully opened. This allows you to perform additional actions on your website, such as displaying a loading animation or prompting the user to continue the checkout process.
  - onWindowClosed: function()
    - The onWindowClosed callback will only trigger when the window closes without generating a token. If a token is successfully generated, the onTokenReceived function will handle that action. This callback allows you to handle scenarios where the user exits the payment flow, enabling you to perform cleanup actions, reset the UI, or prompt the user to retry the process.
  - windowWidth: integer(400)
    - The windowWidth is an optional parameter with a default value of 400(px).
  - windowHeight: integer(300)
    - The windowHeight is an optional parameter with a default value of 300(px).
  - html: string
    - The html string is an optional parameter containing custom html code that will be rendered within the payment window.
    - Placeholders within the code:
      - These placeholders will indicate where the buttons for the wallet payments will get injected into the DOM tree. You can style the width, height and position of those placeholders, the buttons will fill them in order to achieve the desired UI result.
      - Google Pay
        
        <div id='google-pay-placeholder'></div>
      - Apple Pay
        
        <div id='apple-pay-placeholder'></div>
    - This code will get sanitized on our side to prevent any malicious actions.
      - Allowed html tags:
        
        div, span, section, article, header, footer, aside, main, nav, p, h1, h2, h3, h4, h5, h6, strong, em, b, i, ul, ol, li, small, abbr, img, label, button, hr, br
      - Allowed html attributes:
        
        id, class, style, title, src, alt, width, height, type, aria-* (all accessibility attributes)
    - Due to Content Security Policy restrictions, you can not link external sources. If you would like to include images, you can do that by providing a base64 string in the src attribute.
  - css: string
    - The css string is an optional parameter containing custom css code that will be used to style the provided html.
    - This code will get sanitized on our side to prevent any malicious actions. We recommend keeping it as simple as possible to avoid issues. If your css is not getting applied, check the javascript console of the payment window to see why your css is rejected and correct it.
      - Forbidden language constructs:
        
        @import
        
        @namespace
        
        @charset
        
        javascript:
        
        behavior:
        
        moz-binding:
        
        vbscript:
        
        content:
        
        expression()
        
        url()
        
        eval()
        
        data:text

Callback

To get the token, trigger an action (e.g., click a button). The response is handled in the JavaScript TOKEN_CALLBACK function. You must manage positive cases when the token is generated successfully, as well as handle errors from the server.

In case of success, the response will be in JSON format and can be parsed to extract information such as the token and the first six and last four digits of the credit card number.

Manage Look and Feel

To blend the input components into your site's design, PayArc provides a list of styles. Use the following containers and customize them as needed:

payarc-all: Container of all elements.
payarc-input: Data input field.
payarc-label: Common style for all component labels.
payarc-input:hover: Style for when the mouse passes over components.
payarc-container: Container for each component.
payarc-label-container: Container for each label.
payarc-input-container: Container for each input field.
payarc-row:after: Clears floats after rows.

Error Codes

200: Success
403: Wrong Client ID (Forbidden).
422: Data validation error (Empty fields, wrong CVV, wrong expiry date).
408: User session expired.
419: User session expired.
409: Wrong response from Payment Gateway (e.g., wrong card number).

Questions and Answers

Q: Can I hide the labels of input fields?
A: Yes, use display: none; in the .payarc-label style.

Q: What is payarcInitiatePaymentObject?
A: It's an internal object to accept the values entered by the customer.

Q: Do I need to define a container to group those card fields?
A: Yes. The default name is payarc-card-token-container, but it can be overridden in PAYARC_INITIAL_VALUES.

Demo

The code below can be put on your server with minimal customizations to test token generation:

<!DOCTYPE html>
<html>
<head>
    <title>PayArc Payment Token - Demo</title>
    <link href="css/style.css" rel="stylesheet">
    <meta charset="UTF-8"/>
    <script>
        const PAYARC_API_KEY = "place Client id key here";
        const PAYARC_TOKEN_CALLBACK = {
            success: (obj) => {
                const response = JSON.parse(obj.response);
                const responseTag = document.getElementById('card-token');
                if (responseTag) {
                    responseTag.textContent = response.token;
                    responseTag.hidden = false;
                }
                console.log(response.card);
                showStatus('SUCCESS! Token is available.', 'status-success');
            },
            error: (obj) => {
                const statusResponse = `ERROR! ${obj.status} ${obj.statusText}`;
                showStatus(statusResponse, 'status-error');
                if (obj.status !== 422) {
                    alert('There is an error from the payment gateway. Correct it and try again.');
                    initPayArcTokenizer(PAYARC_API_KEY, PAYARC_INITIAL_VALUES);
                }
            }
        };
        const PAYARC_INITIAL_VALUES = {
            FORM_STATUS: 'form-status',
            INITIATE_PAYMENT: 'initiate-payment',
            FIELDS_CONTAINER: 'card-token-container',
            TOKEN_CALLBACK: PAYARC_TOKEN_CALLBACK
        }
    </script>
    <script src="https://testportal.payarc.net/js/iframeprocess.js" defer></script>
</head>
<body>
    <button id="myBtn">Open Modal</button>
    <div id="myModal" class="modal">
        <div class="modal-content">
            <div class="modal-header">
                <h2>PayArc Demo Form Modal</h2>
            </div>
            <div class="modal-body">
                <table id="card-token-container">
                    <tr>
                        <td colspan="2">
                            <div id="credit-card-number" data-payarc="CARD_NUMBER" data-placeholder="Card Number"></div>
                        </td>
                    </tr>
                    <tr>
                        <td>
                            <div id="credit-card-exp" data-payarc="EXP" data-placeholder="MM/YY"></div>
                        </td>
                        <td>
                            <div id="credit-card-cvv" data-payarc="CVV" data-placeholder="CVV"></div>
                        </td>
                    </tr>
                </table>
                <button id="initiate-payment" onclick="getPayarcToken(this)">Generate Token</button>
                <div id="form-status"></div>
                <div id="card-token" hidden></div>
            </div>
        </div>
    </div>
</body>
</html>