PayForm & AccountForm Integrations

Where to use PayForm and AccountForm

PayForm and AccountForm are intended to be used in an access-controlled merchant-facing application such as point-of- sale or back-office software.

PayForm is intended to be used as an interface for a merchant to manually process card payments or for launching transactions on a connected point-of-sale terminal. AccountForm is intended to be used as an interface for a merchant to manually store a customer's payment credentials using the Account Vault tokenization service.

Please do not use PayForm or AccountForm in a public-facing application where a customer makes their own payment, because it is not suitable for this purpose. If you are developing an application that takes payments from customers directly, please use the Hosted Payments Page.

Overview

Here you can learn how to create Account Vaults and Transactions using our AccountForm and PayForm widgets, which will keep you out of scope for PCI as the form code is being generated and hosted by us, another key part of staying out of scope for PCI Compliance.

The PayForm widget can be used for running sale, authonly, or refund transactions. Any void, authincrement, or authcomplete transactions are done as PUT transactions using the id returned from the /v2/payform endpoint. PUT transactions do not require account_number and exp_date fields to be submitted, therefore need to be done on the /v2/transactions endpoint. 

Whether you are attempting to use Payform or Accountform, the process for generating either form is very similar.

1. Prepare a data variable as a JSON string.
2. Hex the data variable and use with hash-key, developer-id, user-id, and timestamp to create the URL to retrieve the form.
3. The URL can be used as an iframe source to embed within another application, or can be accessed directly. 
   1. The URL will return an HTML form with the necessary fields to gather the appropriate information.
      Note: The client software from the ISV will be either an installed application or a website loading an iFrame/payment form.
4. The user will then complete and submit the form back to the server for processing.
5. Depending on additional parameters that the developer can supply, the iframe may close the window it appears in automatically or redirect to another URL.

1. Preparing data for the request

Below you will see examples of a data JSON object for both AccountForm and PayForm.  These requests are for demonstrative purposes only and there are additional fields that can be provided that are outline below.

{
    "transaction":{
        // Required fields
        "payment_method": "{cc or ach}",
        "action": "sale",
        "transaction_amount": "13.00",
        "transaction_api_id": "111111111111111111111111",
        // Optional fields for the transactions endpoint
        "location_id": "1111111111111111111111111",
        "billing_street": "43155 novi",
        "billing_zip": "12342",
        "tip_amount": "12",
        "surcharge_amount": "0",
        "product_transaction_id": "1111111111111111",
        "order_num": "1234567890",
        "contact_id": "222222222222222",
        // Optional field for controling iframe behavior
        "stylesheet_url": "{full URL - i.e. https://third.party.domain/css/styles.css}",
        "parent_close": true,
        "parent_close_delay": 5,
        "display_close_button": false,
        "redirect_url_on_approval":"https://www.mysite.com",
        "redirect_url_on_decline":"https://www.mysite.com",
        "redirect_url_delay": 5,
        "require_zip": 1,
        "require_street": 1,
        "show_street": 1,
        "show_zip": 1,
        "hide_entry_type":false
    }
}

{
    "transaction":{
        // Required fields
        "payment_method": "{cc or ach}",
        "action": "sale",
        "transaction_amount": "13.00",
        // Optional field for controling iframe behavior
        "stylesheet_url": "{full URL - i.e. https://third.party.domain/css/styles.css}",
        [...] // Other Optional Fields
    }
}

{
    "accountvault": {
        // Required fields
        "payment_method": "{cc or ach}", 
        "location_id": "1111111111111111111111111",
        "account_vault_api_id": "1111111111111111111111111",
        // Optional fields for accountvaults endpoint 
        "contact_id": "1111111111111111111111111",
        "title": "Account_vault",
        "account_holder_name": "john smith",
        // Optional Fields used to control iframe behavior
        "show_account_holder_name": true,
        "show_street": true,
        "show_zip": true,
        "stylesheet_url": "{full URL - i.e. https://third.party.domain/css/styles.css}",
        // Optional Fields used to control iframe after completion
        "display_close_button": true,
        "parent_close": true,
        "parent_close_delay": 3,
        "parent_origin": null,
        "redirect_url_on_approval": "https://www.google.com",
        "redirect_url_delay": 10,
        "hide_entry_type":false
    }
}

{
    "accountvault": {
        // Required fields
        "payment_method": "{cc or ach}", 
        "location_id": "1111111111111111111111111",
        "account_vault_api_id": "1111111111111111111111111",
        // Optional Fields used to control iframe behavior
        "stylesheet_url": "{full URL - i.e. https://third.party.domain/css/styles.css}",
        [...] // Other optional fields
    }
}

2. Build the URL to retrieve the form

In the following code example you will see the steps necessary to generate the URL that can be used for retrieving the desired form.

1. Generate the secure hash.
2. Convert the data to hex.
3. Build the URL to retrieve the form.

<?php
// [1] Generate the secure hash
$user_hash_key = 'my_user_hash_key'; // secret hash key used for hashing the variables
$user_id = 'my_user_id'; //  variables for generating the required hash
$timestamp = time(); // variables for generating the required hash
$salt = $user_id . $timestamp; //$user_id and $timestamp need to be in this order
$hash_key = hash_hmac('sha256', $salt, $user_hash_key);

// [2] Convert the data to hex
// In this example, data is for a transaction
$data = implode(unpack("H*", '{"transaction":{...}}'));

// [3] Build the URL to retreive the form
$domain = "https://api.sandbox.domain.com";
$endpoint = "payform"; // could also be "accountform"
$url = sprintf("%s/v2/%s?developer-id=%s&hash-key=%s&user-id=%s&timestamp=%s&data=%s",
    $domain,
    $endpoint,
    $developer_id,
    $hash_key,
    $user_id,
    $timestamp,
    $data
);

// Function needed to convert string to hex
function asctohex(asc) {
  var hex = '';
  for (var i = 0; i < asc.length; i++) {
    hex += ('0' + asc.charCodeAt(i).toString(16)).slice(-2);
  }
  return hex;
}

// JS Object holding all of the required parameters
var params = {
    "developer-id": "{api_developer_id}",
    "hash-key": "",
    "user-id": "{my_user_id}",
    "timestamp": Math.floor((Math.floor(Date.now()) - (1*60000))/1000),
    "data": {
        "transaction": {
            "payment_method": "cc",
            "action": "sale",
            "transaction_amount": "12.00",
            "location_id": "{location_id}",
            "transaction_api_id": "{transaction_api_id}",
            "show_cvv": "1",
            "tax": "3"
        }
    }
};

// [1] Generate the secure hash
params['hash-key'] = CryptoJS.HmacSHA256(params['user-id'] + params['timestamp'], "{my_user_hash_key}");

// [2] Convert the data to hex
params['data'] = asctohex(JSON.stringify(params['data']));

// [3] Build the URL to retreive the form
var url = "https://api.sandbox.domain.com/v2/payform?";// could also be "accountform"
Object.keys(params).forEach(function (key) {
    url += key + '=' + params[key] + '&';
});

Required Parameters

There are 5 required parameters for making the request. The following table describes those parameters as well as where they can be passed:

HMAC Authentication

The user-id and timestamp which are passed in the request to the API, will generate another HMAC using user’s user_hash_key. This will check against what was submitted in the hash-key parameter. If they don’t match, you will see a validation message as “Hash key is invalid”

There are 3 parameters that are required to generate a signature hash.

• User ID: Provided when a User is setup
• Timestamp: The current time when the page has been generated. it has an expire period of 15 minutes
• User Hash Key: This is the users hash key provided that is used to generate the signature hash. This key is secret and should not be shared with anyone.

The hash is generated using the user id and timestamp, in that specific order. The generated HMAC will be good for 15 minutes. Here is sample code of how to generate the signature:

3. Using the URL to retrieve the form

After following the steps outlined above, you should have a URL that can be used to embed the form into another website or application.  That URL should look similar to the following:

https://api.sandbox.domain.com/v2/payform?developer-id=b1111111&hash-key=c7fbcad5d892de8d16d94545216cb29c0951b8ae4eec35af7e7674cd25454c01f&user-id=11e7e1b2531a187a87647ed8&timestamp=1513362490&data=7b227472616e73616374696f6e22...

If you embed that iframe or attempt to access the URL directly, you should see something similar to the following images:

4. User completes and submits the form

When the user submits this form, the form data will then be submitted back to the API for processing.

5. Process is complete

Once the process is complete, the iframe may either automatically close the window it appears in or the user may be redirected to a different URL.  It is also possible to have the results from the form submission posted back to the parent window that the iframe was embedded within.  For more information about how to capture the response from the iframe submission, take a look at Using PostMessage.