Getting Started

Step 1: Start transaction

Merchant server only

The code samples below show how you can start a checkout transaction from your merchant server and generate a transaction token that will be used on the client-side to continue the transaction flow.

Input fields

These fields are the fields sent in the transactionData object found in the request body.

NameDetailsRequiredDescription
transactionTypeType: string

Possible values:
- CreditSale
- CreditReturn
- CreditAuth
- CreditSaveCard
- AchSale
- AchReturn
YesThe transaction type for the transaction request
methodType: string

Possible values:
- hostedFields
YesThe integration method. The only applicable value for checkout integrations is hostedFields
submissionTypeType: string

Possible values:
- manual
YesThe submissionType indicates that we're only using the form fields to collect the sensitive customer data and plan on submitting the other transaction details in a later request.

Step 2: Present payment form

Client-side only

After setting up a way to get a transaction token on your server, you will now need to retrieve that transaction token client-side and use it to load the emergepay form fields.

Parent Domain

You must supply Gravity Payments with a valid parent domain. Connect with an Integration Specialist for more information.

Basic flow of Checkout

The form fields work by appending iframe elements to container elements, such as divs, on your site. The iframes display input fields hosted from our servers that will collect sensitive customer data. The type of form fields appended to your site will depend on the transaction type supplied in step 1.

For card-specific transaction types, the available form fields are:

  • Credit card number
  • Expiration date
  • Card security code

For ACH-specific transaction types, the available form fields are:

  • Account number
  • Routing number
  • Account holder name

Here are the steps:

  1. Your page loads with <div> elements in your checkout form that will serve as containers for the form fields. For example,
    <div id="cardNumberContainer"></div> would act as a container for the iframe that contains the credit card form field.
  2. Your page includes a reference to the form fields assets javascript file in a script tag:
    <script src="assets_url/cip-hosted-fields.js"></script>
    When this assets file loads, it will expose a window.emergepayFormFields object.
  3. Take a look at the sample code below to configure the emergepay form fields. This process will include fetching a transaction token from your server and initializing the form fields with a supplied configuration object. This will let emergepay know where to append the fields to your site, how to style them, and what action should occur when the field values are submitted successfully.
  4. Attach a listener to the submit event on your checkout form that calls hosted.process() when the form submits. This will
    initiate the process of sending the values of each form field to our backend and then indicate to you that the transaction is ready to be processed by calling the onUserAuthorized callback that you supplied in the emergepayFormFields.init() configuration object.

 

Field styling

Styling form fields can be done in your merchant configuration or on a per-field per-transaction basis.

An example of per-field styling can be seen in the code sample below in the styles object under each field in fieldSetUp. Any CSS property applicable to the input element is valid. A reference for the available CSS properties can be found here.

Note: if any styles are set via merchant configuration, the styles set in the styles object under each field will override them.

<!-- These are the elements that the fields will be appended to -->
<div>
  <!-- Elements that fields will be appended to for credit card transactions -->
  <div id="cardNumberContainer"></div>
  <div id="expirationDateContainer"></div>
  <div id="securityCodeContainer"></div>
  <!-- Elements that fields will be appended to for ACH transactions -->
  <div id="accountNumberContainer"></div>
  <div id="routingNumberContainer"></div>
  <div id="accountHolderNameContainer"></div>
  <button id="payBtn">Pay</button>
</div>


<!-- 
Load emergepay fields javascript file. 
NOTE: make sure you replace assets_url with the correct url for the environment you're working in. 
-->

<script src="assets_url/cip-hosted-fields.js"></script>

<!-- 
    After the script has loaded you will have access to the `window.emergepayFormFields` object. 
    This object has two public methods: `init()` and `process()`.
-->

<!-- Use the emergepay library -->
<script>
    $(document).ready(function () {
        getToken().then(function(transactionToken) {
            // Initialize the hosted fields
            var hosted = emergepayFormFields.init({
                // (required) Used to set up each field
                transactionToken: transactionToken,
                // (required) The type of transaction to run
                transactionType: "CreditSale",
                // (optional) Configure which fields to use and the id's of the elements to append each field to
                fieldSetUp: {
                    // These fields are valid for credit card transactions
                    cardNumber: {
                        appendToSelector: "cardNumberContainer",
                        useField: true,
                        // optional, see styles section above for more information
                        styles: { "background-color": "blue" }
                    },
                    cardExpirationDate: {
                        appendToSelector: "expirationDateContainer",
                        useField: true,
                        // optional, see styles section above for more information
                        styles: { "border": "1px solid red" }
                    },
                    cardSecurityCode: {
                        appendToSelector: "securityCodeContainer",
                        useField: true,
                        // optional, see styles section above for more information
                        styles: {}
                    },
                    // These fields are valid for ACH transactions
                    accountNumber: {
                        appendToSelector: "accountNumberContainer",
                        useField: true,
                        // optional, see styles section above for more information
                        styles: {}
                    },
                    routingNumber: {
                        appendToSelector: "routingNumberContainer",
                        useField: true,
                        // optional, see styles section above for more information
                        styles: {}
                    },
                    accountHolderName: {
                        appendToSelector: "accountHolderNameContainer",
                        useField: true,
                        // optional, see styles section above for more information
                        styles: {}
                    },
                    // These fields are valid for all transaction types
                    totalAmount: {
                        appendToSelector: "amountContainer",
                        useField: false,
                        // optional, see styles section above for more information
                        styles: {}
                    },
                    externalTranId: { 
                        useField: false,
                        // optional, see styles section above for more information
                        styles: {}
                    }
                },
                // (optional) If there is a validation error for a field, the styles set in this object will be applied to the field
                fieldErrorStyles: {
                    "border": "none",
                    "box-shadow": "0px 0px 4px 1px red"
                },
                // (optional) This callback function will be called when there is a validation error for a field.
                onFieldError: function (data) {
                    console.log(data);
                },
                // (optional) This callback function will be called when a field validation error has been cleared.
                onFieldErrorCleared: function (data) {
                    console.log(data);
                },
                // (required) Callback function that gets called after user successfully enters their information into the form fields and triggers the execution of the `process` function
                onUserAuthorized: function (transactionToken) {
                    console.log('transactionToken', transactionToken);
                  
                    var details = {
                        transactionToken,
                      // any other transaction details you may need to send to your server
                    };
                  
                    $.ajax({
                        url: 'http://localhost:5555/submit',
                        type: 'POST',
                        dataType: 'json',
                        contentType: 'application/json',
                        data: JSON.stringify(details)
                    })
                    .done(function(data) {
                      // your server successfully ran the transaction
                      location = 'https://www.gravitypayments.com';
                    })
                    .fail(function(error) {
                      console.error(error);
                    });
                },
            });

            $('#payBtn').on("click", function (event) {
                event.preventDefault();
                // run the transaction if all fields are valid
                hosted.process();
            });
        });
    });

    // This function makes a call to your server to get a transaction token
    function getToken() {
        return new Promise(function (resolve, reject) {
            $.ajax({
                url: 'http://localhost:5555/start-transaction',
                type: 'POST',
                dataType: 'json',
                contentType: 'application/json'
            })
            .done(function(data) {
                if (data.transactionToken) resolve(data.transactionToken);
                else reject('Error getting transaction token');
            })
            .fail(function(err) {
                reject(err);
            });
        });
    }
</script>

Step 3: Process the transaction

Merchant server only

When the onUserAuthorized callback is triggered as part of Step Two, the customer’s sensitive card or ACH account info is temporarily retained in memory in emergepay’s backend until the session either expires or the transaction is processed.

To process the transaction, you will need to send a transaction request to emergepay’s checkout endpoint, which will merge the customer’s sensitive card or ACH account info with the transaction details you supply in the request. The type of transaction being run will be fetched from the session and will have the same value as supplied in Step One.

Getting results

Checkout transactions will always return the transaction results directly; you will not get a postback and there should be no need to make any additional calls to retrieve the results.

Account Card Type Values

Card Brand Response Code
Mastercard MC
Diners Club DN
Visa VS
JCB JC
American Express AX
Discover DC

Example Transaction Result Responses

{
    "uniqueTransId": "77c87064222c4bf88c27f0865d176cf0-0e7453dc741e4233ad571d6ca8d73587",
    "batchNumber": "115",
    "resultMessage": "Approved",
    "resultStatus": "true",
    "approvalNumberResult": "039275",
    "amountProcessed": "0.01",
    "amount": "0.01",
    "amountBalance": "",
    "transactionReference": "",
    "avsResponseCode": "Y",
    "avsResponseText": "Address: Match & 5 Digit Zip: Match",
    "cvvResponseCode": "P",
    "cvvResponseText": "Not Processed",
    "accountCardType": "AX",
    "accountExpiryDate": "0123",
    "transactionType": "CreditSale",
    "billingName": "",
    "maskedAccount": "***********1111",
    "accountEntryMethod": "Keyed",
    "externalTransactionId": "cad8d603-0c51-478a-b410-c5ffa7425be1"
}