emergepay Simple Form (Modal) · Gravity Payments Documentation

Step 1: Start Transaction

Merchant server only

Environment & Asset URLs

Sandbox Account

URL Type	URL
environment	https://api.emergepay-sandbox.chargeitpro.com/virtualterminal/v1
assets	https://assets.emergepay-sandbox.chargeitpro.com

Production Account

URL Type	URL
environment	https://api.emergepay.chargeitpro.com/virtualterminal/v1
assets	https://assets.emergepay.chargeitpro.com

These code samples show how you can start a transaction from your merchant server and generate a transaction token that you can then use in the client-side sdk to continue the transaction flow.

CreditSale

A CreditSale [transactionType: “CreditSale”] is a sale transaction processed exclusively on a credit or debit card.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", function (req, res) {
    var amount = "0.01";
    var config = {
        transactionType: sdk.TransactionType.CreditSale,
        method: "modal",
        fields: [
            {
                id: "base_amount",
                value: amount
            },
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", (req, res) => {
    const amount = "0.01";
    const config: any = {
        transactionType: TransactionType.CreditSale,
        method: "modal",
        fields: [
            {
                id : "base_amount",
                value : amount
            },
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            }
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

<?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//base_amount and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'CreditSale',
    'method' => 'modal',
    'fields' => [
      ['id' => 'base_amount', 'value' => '0.01'],
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "CreditSale",
      method = "modal",
      fields = new[]
      {
        new { id = "base_amount",           value = config.Amount },
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() },
        new { id = "billing_name",          value = config.BillingName },
        new { id = "billing_address",       value = config.BillingAddress },
        new { id = "billing_postal_code",   value = config.BillingPostalCode },
        new { id = "transaction_reference", value = config.TransactionReference },
        new { id = "cashier_id",            value = config.CashierId }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for CreditSale

These fields are sent in via the fields property of the start transaction request data

Name	Details	Required	Description
base_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.01 Max Example: 9999999999.99	Yes	The transaction amount.
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_name	Type: string Max length: 75	No	The customers' billing name.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.
tip_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.00 Max Example: 9999999999.99	No	An optional tip amount that can be added at the time of sale. The total amount of the sale will be equal to `tip_amount` + `base_amount`.
level2.tax_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.00 Max Example: 9999999999.99	No	The tax amount for a level 2 transaction. This field is required for level 2 transactions. If `level2.is_tax_exempt` is `true`, then the value of this field must be `0.00`. The total amount of the sale will be equal to `level2.tax_amount` + `base_amount`.
level2.is_tax_exempt	Type: boolean	No	Indicates whether the level 2 transaction is tax exempt. Defaults to false. This field is only applicable to level 2 transactions.
level2.purchase_id	Type: string Max length: 25	Conditionally	This field is the merchant's internal identifier for the transaction. This field is required for level 2 transactions.
level2.purchase_order_number	Type: string Max length: 17	Conditionally	This field is the customer supplied order number. This field is required for level 2 transactions.
level2.customer_tax_id	Type: string Max length: 15	No	The customer's tax identifier. This field is only applicable to level 2 transactions.
level2.destination_postal_code	Type: string Max length: 9	No	The destination postal code of the transaction. This field is only applicable to level 2 transactions.
level2.product_description	Type: string Max length: 40	No	The description for the order. This field is only applicable to level 2 transactions.
funding.splits_with	Type: array of objects	No	An array of objects that will act as funding instructions. See Funding object below

Funding

Name	Details	Required	Description
oid	Type: string	Yes	The oid that will receive funding
amount	Type: string	Yes	The amount of funding the oid will receive

Note

funding.splits_with is not available with all configurations. Contact your Integration Specialist before use.

CreditReturn

A CreditReturn [transactionType: “CreditReturn”] is a return transaction that is processed exclusively on a credit or debit card.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request 
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", function (req, res) {
    var amount = "0.01";
    var config = {
        transactionType: sdk.TransactionType.CreditReturn,
        method: "modal",
        fields: [
            {
                id: "base_amount",
                value: amount
            },
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            },
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request 
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", (req, res) => {
    const amount = "0.01";
    const config: any = {
        transactionType: TransactionType.CreditReturn,
        method: "modal",
        fields: [
            {
                id : "base_amount",
                value : amount
            },
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            },
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

 <?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//base_amount and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'CreditReturn',
    'method' => 'modal',
    'fields' => [
      ['id' => 'base_amount', 'value' => '0.01'],
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "CreditReturn",
      method = "modal",
      fields = new[]
      {
        new { id = "base_amount",           value = config.Amount },
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() },
        new { id = "billing_name",          value = config.BillingName },
        new { id = "billing_address",       value = config.BillingAddress },
        new { id = "billing_postal_code",   value = config.BillingPostalCode },
        new { id = "transaction_reference", value = config.TransactionReference },
        new { id = "cashier_id",            value = config.CashierId }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for CreditReturn

These fields are sent in via the fields property of the start transaction request data

Name	Details	Required	Description
base_amount	Type: string Min length: 4 Max length: 13 Min Ex: 0.01 Max Ex: 9999999999.99	Yes	The transaction amount.
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_name	Type: string Max length: 75	No	The customers' billing name.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.
funding.splits_with	Type: array of objects	No	An array of objects that will act as funding instructions. See Funding object below

Funding

Name	Details	Required	Description
oid	Type: string	Yes	The oid that will receive funding
amount	Type: string	Yes	The amount of funding the oid will receive

Note

funding.splits_with is not available with all configurations. Contact your Integration Specialist before use.

CreditAuth

A CreditAuth [transactionType: “CreditAuth”] is an authorization that is placed on a credit card that allows the merchant the ability to verify and hold available funds without finalizing the transaction.

Capturing a CreditAuth

CreditAuths allow you to put a hold on funds in someone’s account and charge or release them at a later date—commonly used for things like rental deposits.

Once the card is Authorized, you must close out the sale using a Tokenized Force if the total amount hasn’t been changed or an Adjust if it has—you can also Void to remove the authorization without charging it. Authorizations not captured will not fund to your account.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", function (req, res) {
    var amount = "0.01";
    var config = {
        transactionType: sdk.TransactionType.CreditAuth,
        method: "modal",
        fields: [
            {
                id: "base_amount",
                value: amount
            },
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", (req, res) => {
    const amount = "0.01";
    const config: any = {
        transactionType: TransactionType.CreditAuth,
        method: "modal",
        fields: [
            {
                id : "base_amount",
                value : amount
            },
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            }
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

 <?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//base_amount and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'CreditAuth',
    'method' => 'modal',
    'fields' => [
      ['id' => 'base_amount', 'value' => '0.01'],
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "CreditAuth",
      method = "modal",
      fields = new[]
      {
        new { id = "base_amount",           value = config.Amount },
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() },
        new { id = "billing_name",          value = config.BillingName },
        new { id = "billing_address",       value = config.BillingAddress },
        new { id = "billing_postal_code",   value = config.BillingPostalCode },
        new { id = "transaction_reference", value = config.TransactionReference },
        new { id = "cashier_id",            value = config.CashierId }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for CreditAuth

These fields are sent in via the fields property of the start transaction request data

Name	Details	Required	Description
base_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.01 Max Example: 9999999999.99	Yes	The transaction amount.
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_name	Type: string Max length: 75	No	The customers' billing name.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.
tip_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.00 Max Example: 9999999999.99	No	An optional tip amount that can be added at the time of authorization. The total amount of the authorization will be equal to `tip_amount` + `base_amount`.
level2.tax_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.00 Max Example: 9999999999.99	No	The tax amount for a level 2 transaction. This field is required for level 2 transactions. If `level2.is_tax_exempt` is `true`, then the value of this field must be `0.00`. The total amount of the authorization will be equal to `level2.tax_amount` + `base_amount`.
level2.is_tax_exempt	Type: boolean	No	Indicates whether the level 2 transaction is tax exempt. Defaults to false. This field is only applicable to level 2 transactions.
level2.purchase_id	Type: string Max length: 25	Conditionally	This field is the merchant's internal identifier for the transaction. This field is required for level 2 transactions.
level2.purchase_order_number	Type: string Max length: 17	Conditionally	This field is the customer supplied order number. This field is required for level 2 transactions.
level2.customer_tax_id	Type: string Max length: 15	No	The customer's tax identifier. This field is only applicable to level 2 transactions.
level2.destination_postal_code	Type: string Max length: 9	No	The destination postal code of the transaction. This field is only applicable to level 2 transactions.
level2.product_description	Type: string Max length: 40	No	The description for the order. This field is only applicable to level 2 transactions.

CreditSaveCard

A CreditSaveCard [transactionType: “CreditSaveCard”] generates a unique token to save a card on file for a customer to use when running a future transaction.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request 
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//external_tran_id is required in the fields array for CreditSaveCard.
app.post("/start-transaction", function (req, res) {
    var config = {
        transactionType: sdk.TransactionType.CreditSaveCard,
        method: "modal",
        fields: [
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request 
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//external_tran_id is required in the fields array for CreditSaveCard.
app.post("/start-transaction", (req, res) => {
    const config: any = {
        transactionType: TransactionType.CreditSaveCard,
        method: "modal",
        fields: [
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            },
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

<?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//base_amount and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'CreditSaveCard',
    'method' => 'modal',
    'fields' => [
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "CreditSaveCard",
      method = "modal",
      //external_tran_id is required in the fields array for CreditSaveCard.
      fields = new[] 
      {
        new { id = "external_tran_id", value = Guid.NewGuid().ToString() }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for CreditSaveCard

Name	Details	Required	Description
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_name	Type: string Max length: 75	No	The customers' billing name.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 75	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.
device_name	Type: string Max length: 50	No	The name of the device to use for the transaction. Case sensitive and generally provided by Gravity. NOTE: Only supported for Clover Flex and Mini

AchSale

An AchSale [transactionType: “AchSale”] is a sale transaction processed via cashier check or ACH.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", function (req, res) {
    var amount = "0.01";
    var config = {
        transactionType: sdk.TransactionType.AchSale,
        method: "modal",
        fields: [
            {
                id: "base_amount",
                value: amount
            },
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", (req, res) => {
    const amount = "0.01";
    const config: any = {
        transactionType: TransactionType.AchSale,
        method: "modal",
        fields: [
            {
                id : "base_amount",
                value : amount
            },
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            }
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

<?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//base_amount and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'AchSale',
    'method' => 'modal',
    'fields' => [
      ['id' => 'base_amount', 'value' => '0.01'],
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "AchSale",
      method = "modal",
      fields = new[]
      {
        new { id = "base_amount",           value = config.Amount },
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() },
        new { id = "billing_address",       value = config.BillingAddress },
        new { id = "billing_postal_code",   value = config.BillingPostalCode },
        new { id = "transaction_reference", value = config.TransactionReference },
        new { id = "cashier_id",            value = config.CashierId }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for AchSale

Name	Details	Required	Description
base_amount	Type: string Min length: 4 Max length: 13 Min Example: 0.01 Max Example: 9999999999.99	Yes	The transaction amount.
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.

AchReturn

An AchReturn [transactionType: “AchReturn”] is a return transaction processed via cashier check or ACH.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", function (req, res) {
    var amount = "0.01";
    var config = {
        transactionType: sdk.TransactionType.AchReturn,
        method: "modal",
        fields: [
            {
                id: "base_amount",
                value: amount
            },
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//base_amount and external_tran_id are required in the fields array.
app.post("/start-transaction", (req, res) => {
    const amount = "0.01";
    const config: any = {
        transactionType: TransactionType.AchReturn,
        method: "modal",
        fields: [
            {
                id : "base_amount",
                value : amount
            },
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            }
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

<?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//base_amount and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'AchReturn',
    'method' => 'modal',
    'fields' => [
      ['id' => 'base_amount', 'value' => '0.01'],
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "AchReturn",
      method = "modal",
      fields = new[]
      {
        new { id = "base_amount",           value = config.Amount },
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() },
        new { id = "billing_address",       value = config.BillingAddress },
        new { id = "billing_postal_code",   value = config.BillingPostalCode },
        new { id = "transaction_reference", value = config.TransactionReference },
        new { id = "cashier_id",            value = config.CashierId }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for AchReturn

Name	Details	Required	Description
base_amount	Type: string Min length: 4 Max length: 13 Min Ex: 0.01 Max Ex: 9999999999.99	Yes	The transaction amount.
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.

AchSaveAccount

An AchSaveAccount [transactionType: “AchSaveAccount”] generates a unique token to save a bank account on file for a customer to use when running a future transaction.

//install the modules below with the following command:
//npm install express cors emergepay-sdk
var express = require("express");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//external_tran_id is required in the fields array.
app.post("/start-transaction", function (req, res) {    
    var config = {
        transactionType: sdk.TransactionType.AchSaveAccount,
        method: "modal",
        fields: [           
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install express cors emergepay-sdk
import * as express from "express";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(express.json());
app.use(express.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//external_tran_id is required in the fields array.
app.post("/start-transaction", (req, res) => {
    const config: any = {
        transactionType: TransactionType.AchSaveAccount,
        method: "modal",
        fields: [
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            }
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

<?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//external_tran_id is required in the fields array.
$body = [
  'transactionData' => [
    'transactionType' => 'AchSaveAccount',
    'method' => 'modal',
    'fields' => [
      ['id' => 'external_tran_id', 'value' => GUID()]
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public static async Task<object> StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "AchSaveAccount",
      method = "modal",
      fields = new[]
      {
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Input Fields for AchSaveAccount

Name	Details	Required	Description
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
billing_address	Type: string	No	The customers' street address.
billing_postal_code	Type: string	No	The customers' zip code.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.

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 token client-side and use it to load the emergepay form.

Note

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

<!-- 
Load emergepay modal 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-modal.js"></script>

<!--
After the script has loaded you will have access to the `window.emergepay` object. 
This object has three public methods: `open()`, `close()`, and `init()`.
-->

<!-- Use emergepay library -->


<script>
    window.onload = function() {
        // Initialize emergepay modal (not required, but makes things load faster)
        emergepay.init();

        // Set up event listener on Pay With Card button
        document.getElementById('cip-pay-btn').addEventListener('click', function(e) {
            e.preventDefault();
            
            // Get a transactionToken serverside
            getToken()
            .then(function(transactionToken) {
                // Set up and open the payment modal
                emergepay.open({
                    // (required) Used to set up the modal
                    transactionToken: transactionToken,
                    // (optional) Callback function that gets called after a successful transaction
                    onTransactionSuccess: function(approvalData) {
                        console.log("Approval Data", approvalData);
                        emergepay.close();
                        location = "https://gravitypayments.com";
                    },
                    // (optional) Callback function that gets called after a failure occurs during the transaction (such as a declined card)
                    onTransactionFailure: function(failureData) {
                        console.log("Failure Data", failureData);
                    },
                    // (optional) Callback function that gets called after a user clicks the close button on the modal
                    onTransactionCancel: function () {
                        console.log("transaction cancelled!");
                    }
                });
            });
        });
    };

    // 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: Transaction Results

Merchant server only

We strongly recommend using postback or server-side results retrieval from your application unless your application will be used exclusively by trusted users, such as cashiers.

Results Options

Postback – when a transaction completes, Gravity Payments will POST the results back to a URL you’ve pre-defined with your integration specialist.
Polling (aka retrieval) – Your app will query Gravity Payments using a unique externalTransactionId that your application created at the start of the transaction.

Postback

HMAC Signature Validation

Post-back results should be verified using the HMAC signature found in the request header.

one-way SHA-512 message digest
encrypted using a secret passphrase you setup with your integration specialist and is then base64 encoded
digest is included in the request header as hmac-signature

Verify HMAC signature

Encrypt the request body using the SHA512 hash algorithm and your secret key
Base64 encode the result
Compare the resulting value with the hmac-signature header value

What's a 'secret passphrase'?

Similar to the OID and authToken, the secret passphrase is a unique variable that is tied to each individual merchant account.

This is the recommended way to retrieve transaction results.

var express = require("express");
var cors    = require("cors");
var crypto  = require("crypto");

var app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

app.post("/PostBackListener", (req, res) => {
    var hmacSignature = req.header("hmac-signature");
    var rawData = req.body;
    var jsonData = JSON.stringify(rawData);

    var signatureMatched = false;

    if (hmacSignature) {
        signatureMatched = verifyHmacSignature(hmacSignature, jsonData);
    }

    //if the hmac signature matched, the response body data is valid
    if (signatureMatched) {
        //do something with the transaction result
    }

    res.sendStatus(200);
});

function verifyHmacSignature(hmacSignature, data) {
    //this is the secret pass phrase you supplied to Gravity Payments
    var secretKey = "cipDemoListenerKey";

    var hmac = crypto.createHmac("sha512", secretKey);
    hmac.update(data);
    return hmac.digest("base64") === hmacSignature;
}

console.log("listening on port 5555");
app.listen(5555);

import * as express from 'express';
import * as cors from 'cors';
import * as crypto from 'crypto';

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());

app.post("/PostBackListener", (req, res) => {
    const hmacSignature = req.header("hmac-signature");
    const rawData = req.body;
    const jsonData = JSON.stringify(rawData);

    let signatureMatched = false;

    if (hmacSignature) {
        signatureMatched = verifyHmacSignature(hmacSignature, jsonData);
    }

    //if the hmac signature matched, the response body data is valid
    if (signatureMatched) {
        //do something with the transaction result
    }

    res.sendStatus(200);
});

function verifyHmacSignature(hmacSignature: string, data: string): boolean {
    //this is the secret pass phrase you supplied to Gravity Payments
    const secretKey = "cipDemoListenerKey";

    const hmac = crypto.createHmac("sha512", secretKey);
    hmac.update(data);
    return hmac.digest("base64") === hmacSignature;
}

console.log("listening on port 5555");
app.listen(5555);

$headers = getallheaders();
$body = file_get_contents("php://input");
$jsonData = json_encode(json_decode($body));

$signatureMatched = false;

if (array_key_exists("hmac-signature", $headers)) {
    $hmacSignature = $headers["hmac-signature"];

    $signatureMatched = verifyHmacSignature($hmacSignature, $jsonData);
}

// if the hmac signature matched, the response body data is valid
if ($signatureMatched) {
    // do something with the transaction result
}

function verifyHmacSignature(string $hmacSignature, string $data) {
    // this is the secret pass phrase you supplied to Gravity Payments
    $secretKey = "yourSecretPassPhrase";

    $hmac = hash_hmac("sha512", $data, $secretKey, true);

    return base64_encode($hmac) == $hmacSignature;
}

[HttpPost]
public void PostBackListener()
{
  var reader = new StreamReader(Request.Body);
  var bodyContents = reader.ReadToEnd();
  var transactionResult = JsonConvert.DeserializeObject(bodyContents);
  var rawData = JsonConvert.DeserializeObject(bodyContents);
  var jsonData = JsonConvert.SerializeObject(rawData);

  //verify the hmac signature with our secret pass phrase
  bool hmacSignatureExists = Request.Headers.TryGetValue("hmac-signature", out var hmacSignature);
  bool signatureMatched = false;

  if (hmacSignatureExists)
  {
    string signature = hmacSignature.ToString();
    byte[] data = Encoding.UTF8.GetBytes(jsonData);
    signatureMatched = VerifyHmacSignature(signature, data);
  }

  //if the hmac signature matched, the response body data is valid
  if (signatureMatched)
  {
        //do something with the transaction result
  }
}

private bool VerifyHmacSignature(string hmacSignature, byte[] data)
{
  //this is the secret pass phrase you supplied to Gravity Payments
  const string secretKey = "yourSecretPassPhrase";

  using (HMACSHA512 hmac = new HMACSHA512(Encoding.UTF8.GetBytes(secretKey)))
  {
    byte[] computedHash = hmac.ComputeHash(data);
    string computedSignature = Convert.ToBase64String(computedHash);
    return hmacSignature == computedSignature;
  }
}

Retrieval

This sample code can be used to implement a polling model for fetching results.

This sample code can be used to implement a polling model for fetching results.

//install the module below with the following command:
//npm install emergepay-sdk
var emergepaySdk = require('emergepay-sdk').emergepaySdk;

//Ensure that you replace these with valid values before trying to issue a request
var oid = 'your_oid';
var authToken = 'your_authToken';
var environmentUrl = 'environment_url';

var emergepay = new emergepaySdk({oid: oid, authToken: authToken, environmentUrl: environmentUrl});

//Ensure that you supply a valid external transaction id before trying to run the retrieval function.
emergepay.retrieveTransaction("your_external_transaction_id")
.then(function(response) {
    var transactionResponse = response.data;
})
.catch(function(error) {
    throw error;
});

//install the module below with the following command:
//npm install emergepay-sdk
import {emergepaySdk} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

//Ensure that you supply a valid external transaction id before trying to run the retrieval function.
emergepay.retrieveTransaction("your_external_transaction_id")
.then(response => {
    const transactionResponse = response.data;
})
.catch(error => {
    throw error;
});

//Configure your oid and auth token. These are supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';

//Set the external transaction id of the transaction you want to retrieve from Gravity Payments.
//Note: Make sure you set this before attempting to retrieve transaction results.
$externalTransactionId = '';

//Configure the environmentUrl. This is supplied by Gravity Payments.
$environmentUrl = 'environment_url';
$url = $environmentUrl . '/orgs/' . $oid . '/transactions/' . $externalTransactionId;

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));

//Issue the request and get the result
$response = curl_exec($request);
curl_close($request);

echo $response;

public static async Task RetrieveTransaction()
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  //Ensure the externalTransactionId is set to the transaction you want to look up.
  string externalTransactionId = "your_external_transaction_id";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/{externalTransactionId}";

  try
  {
    using (var client = new HttpClient())
    {
      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

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

Each tab shows an example response from the respective retrieval method.

{"accountCardType":"VS","accountEntryMethod":"Keyed","accountExpiryDate":"1027","amount":"0.01","amountBalance":"","amountProcessed":"0.01","amountTaxed":"0.00","amountTipped":"0.00","approvalNumberResult":"256171","avsResponseCode":"Y","avsResponseText":"Address: Match & 5 Digit Zip: Match","batchNumber":"0","billingName":"","cashier":"","createdOn":"2022-04-18T20:52:50.370Z","cvvResponseCode":"P","cvvResponseText":"Not Processed","externalTransactionId":"4b07fa33-c03e-48c0-ba3c-0e02d98f5fb3","isPartialApproval":false,"maskedAccount":"************1111","resultMessage":"Approved","resultStatus":"true","transactionReference":"","transactionType":"CreditSale","uniqueTransId":"aec21bf6779544f4be812c29beba7024-a5300e56fb6b40ea9ee28b6c14e6e3ed"}

{"transactionResponse":{"accountCardType":"VS","accountEntryMethod":"Keyed","accountExpiryDate":"1027","amount":"0.01","amountBalance":"","amountProcessed":"0.01","amountTaxed":"0.00","amountTipped":"0.00","approvalNumberResult":"256171","avsResponseCode":"Y","avsResponseText":"Address: Match & 5 Digit Zip: Match","batchNumber":"0","billingName":"","cashier":"","createdOn":"2022-04-18T20:52:50.370Z","cvvResponseCode":"P","cvvResponseText":"Not Processed","externalTransactionId":"4b07fa33-c03e-48c0-ba3c-0e02d98f5fb3","isPartialApproval":false,"maskedAccount":"************1111","resultMessage":"Approved","resultStatus":"true","transactionReference":"","transactionType":"CreditSale","uniqueTransId":"aec21bf6779544f4be812c29beba7024-a5300e56fb6b40ea9ee28b6c14e6e3ed"}}

{"accountCardType":"VS","accountEntryMethod":"Keyed","accountExpiryDate":"1027","amount":"0.01","amountBalance":"","amountProcessed":"0.01","amountTaxed":"0.00","amountTipped":"0.00","approvalNumberResult":"256171","avsResponseCode":"Y","avsResponseText":"Address: Match & 5 Digit Zip: Match","batchNumber":"0","billingName":"","cashier":"","createdOn":"2022-04-18T20:52:50.370Z","cvvResponseCode":"P","cvvResponseText":"Not Processed","externalTransactionId":"4b07fa33-c03e-48c0-ba3c-0e02d98f5fb3","isPartialApproval":false,"maskedAccount":"************1111","resultMessage":"Approved","resultStatus":"true","transactionReference":"","transactionType":"CreditSale","uniqueTransId":"aec21bf6779544f4be812c29beba7024-a5300e56fb6b40ea9ee28b6c14e6e3ed"}

Print or Email Receipt

Your application should now analyze the results and asks for another form of payment when the card is partially approved or declined. If approved, your application should print\email a receipt.

Step 4: Transaction Acknowledgment

Merchant server only

What is the purpose of Transaction Acknowledgment?

The purpose of the transaction acknowledgement endpoint is to close the communication loop for a transaction and signal to emergepay that you’ve received the transaction response.

Here are some details about the endpoint:

emergepay will reply with a 200 success status when the acknowledgment is received.
No specific error message will be returned in the event of an error and the only action you should take when an error does occur is retry.

Best Practices

Ensure that the transaction acknowledgment is sent after the transaction response is received
Ensure that the transaction acknowledgment, after receiving back a successful 200 status, is not sent again
Use a backoff/retry algorithm when an error is received from the endpoint

Examples of transaction acknowledgement

//install the module below with the following command:
//npm install emergepay-sdk
var emergepaySdk = require('emergepay-sdk').emergepaySdk;

//Ensure that you replace these with valid values before trying to issue a request
var oid = 'your_oid';
var authToken = 'your_authToken';
var environmentUrl = 'environment_url';

var emergepay = new emergepaySdk({oid: oid, authToken: authToken, environmentUrl: environmentUrl});

//Ensure that you supply a valid external transaction id before trying to run the acknowledge function.
emergepay.acknowledge("your_external_transaction_id")
    .catch(function(error) {
        console.log("need to retry");
    });

//install the module below with the following command:
//npm install emergepay-sdk
import {emergepaySdk} from "emergepay-sdk";

const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";

const emergepay: emergepaySdk = new emergepaySdk({ oid, authToken, environmentUrl });

emergepay.acknowledge("your_external_transaction_id")
    .catch(error => {
        console.log("need to retry");
    });

//Configure your oid and auth token. These are supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';

//Set the external transaction id of the transaction you want to retrieve from Gravity Payments.
//Note: Make sure you set this before attempting to retrieve transaction results.
$externalTransactionId = 'your_external_transaction_id';

//Configure the environmentUrl. This is provided by Gravity Payments.
$environmentUrl = 'environment_url';
$url = $environmentUrl . '/orgs/' . $oid . '/transactions/acknowledgements/' . $externalTransactionId;

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));


//Issue the request and get the result
$response = curl_exec($request);

if (curl_getinfo($request)['http_code'] !== 200) {
    echo 'need to retry';
}

curl_close($request);

public static async Task AcknowledgeAsync()
{
    //Ensure these are set before trying to issue the request.
    //Please contact Gravity Payments to get these values.
    const string OID = "your_oid";
    const string AUTH_TOKEN = "your_authToken";
    const string ENDPOINT_URL = "environment_url";

    //Ensure that you supply a valid external transaction id before trying to run this function.
    string externalTransactionId = "your_external_transaction_id";

    string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/acknowledgements/{externalTransactionId}";

    try
    {
        using (var client = new HttpClient())
        {
            HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Put, url);
            request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");

            var httpResponse = await client.SendAsync(request);

            if (httpResponse.StatusCode != System.Net.HttpStatusCode.OK)
            {
                Console.WriteLine("need to retry");
            }
        }
    }
    catch (Exception exc)
    {
        Console.WriteLine("need to retry");
    }
}

Transaction acknowledgement path parameter requirements

Name	Details	Required	Description
oid	string	Yes	The merchant identifier of the merchant that ran the transaction to acknowledge
externalTransactionId	Type: v4 uuid	Yes	A reference to the transaction to acknowledge. This value must be the Version-4 UUID that was generated by you in the creation of the transaction.

Step 5: Are you using a payment device?

Emergepay makes it easy to add a payment device to your integration. Take a look at our supported payment devices. Additionally, since emergepay is platform and OS agnostic, we are able to process transactions from any platform and OS.

Our card-present solution uses the same endpoints as our card not present solution, only requiring a few extra fields and methods, please review them below.

Available Transaction Types

CreditSale
CreditReturn
CreditAuth
- Does not support the tip_amount or prompt_tip fields in the start transaction request
RequestSignature
CreditSaveCard
- Only supported for Clover Flex and Mini devices

Transaction Types Not Available

ACHSale
ACHReturn

Additional transaction input fields required

Name	Details	Required	Description
device_name	Type: string Max length: 50	Yes	The name of the device to use for the transaction. Case sensitive and generally provided by Gravity.
prompt_tip	Type: string Enum: "true" \| "false"	No	An optional parameter that, when set to "true", will cause the device to prompt the customer to enter a tip amount. The tip amount entered by the customer on the device will be added to the value of "base_amount" to calculate the transaction total. If "prompt_tip" is set to "true", "tip_amount" must be omitted or set to "0.00". The fields cannot work in tandem.
signature_capture	Type: string Enum: "true" \| "false"	No	Default: "false". An optional parameter for controlling the signature prompt on capable devices. If set to "true", the device will prompt the user to draw their signature on the device screen after they enter their card. The results will be available in the "signature" section of the transaction results as a Base64 encoded image.
signature_required	Type: string Enum: "true" \| "false"	No	Default: "false". Determines whether entering a signature is required. Requires "signature_capture" to be set to "true.

Testing Without a Physical Device

Want to test device-based transactions without a physical device? Our simulated device is a great way to do quick device-based testing with your integration. To use it, simply supply SimulatedDevice in the device_name field.

When the emergepay modal opens from Step 2, a link to open the simulated device will display just below the transaction details. Clicking the link will open our simulated device in a new browser tab, where you can click through the transaction options that you want to simulate for the transaction type supplied in Step 1. After confirming the transaction options to simulate, you will see a transaction result screen on the simulated device. You can then navigate back to the browser tab that the emergepay modal is open in to see the transaction result screen on the emergepay UI to proceed with your testing.

Partial Approval Support

Card brand regulations require the support of partial approvals when using a payment device; a partial approval occurs when a user has insufficient funds on a debit or gift card, but the device accepts the payment for the amount on the card anyway.

For example, you initiate a sale for $100.00, but the customer only has $75 on their card—the system will approve the transaction for $75.00, and inform you that a partial approval was processed, you’ll then need to initiate a new sale for the remaining $25.00
The amountProcessed and isPartialApproval fields in our results can all be used to check for a partial approval

Tipping Support

The “tip_amount” and “prompt_tip” fields cannot both hold positive values, as they are alternative ways to process a tip. For instance, if “prompt_tip” is set to “true”, then the “tip_amount” parameter must be excluded from the request or set to “0.00”.

Input fields for RequestSignature

Request signature allows you to request a signature outside of a payment transaction.

Device Support

This feature is only available on the following devices:

Clover Flex
Clover Mini

Name	Details	Required	Description
external_tran_id	Type: v4 uuid	Yes	A unique transaction identifier (must be a Version-4 UUID) for each transaction. This value is used to look up transaction results as well as confirm to the merchant and emergepay that a transaction was completed.
device_name	Type: string Max length: 50	Yes	The name of the device to use for the transaction.
cashier_id	Type: string Max length: 150	No	The name of the cashier that ran the transaction.
transaction_reference	Type: string Min length: 3 Max length: 65	No	The order id associated with the transaction. Accepted characters are "a" to "z", "A" to "Z", "0" to "9", ".", "_", "-", and space characters.
confirmation_text	Type: string Min length: 3 Max length: 200	No	Text to display on the screen above the signature prompt.

This code demonstrates how to initiate a RequestSignature.
The transaction token retrieved here should be used on the 
client side to initiate the device's requestSignature screen

//install the modules below with the following command:
//npm install -D express body-parser cors emergepay-sdk
var express = require("express");
var bodyParser = require("body-parser");
var cors = require("cors");
var sdk = require("emergepay-sdk");

//Ensure that you replace these with valid values before trying to issue a request
var oid = "your_oid";
var authToken = "your_authToken";
var environmentUrl = "environment_url";
var emergepay = new sdk.emergepaySdk({ oid: oid, authToken: authToken, environmentUrl: environmentUrl });

var app = express();
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//device_name and external_tran_id are required in the fields array.
app.post("/start-transaction", function (req, res) {
    var amount = "0.01";
    var config = {
        transactionType: sdk.TransactionType.RequestSignature,
        method: "modal",
        fields: [
            {
                id: "external_tran_id",
                value: emergepay.getExternalTransactionId()
            },
            {
                id: "device_name", 
                value: "{your_device_name}"
            }
        ]
    };
  
    emergepay.startTransaction(config)
    .then(function (transactionToken) {
        res.send({
            transactionToken: transactionToken
        });
    })
    .catch(function (err) {
        res.send(err.message);
    });
});

console.log("listening on port 5555");
app.listen(5555);

//install the modules below with the following command:
//npm install -D express body-parser cors emergepay-sdk
import * as express from "express";
import * as bodyParser from "body-parser";
import * as cors from "cors";
import {emergepaySdk, TransactionType} from "emergepay-sdk";

//Ensure that you replace these with valid values before trying to issue a request
const oid: string = "your_oid";
const authToken: string = "your_authToken";
const environmentUrl: string = "environment_url";
const emergepay: emergepaySdk = new emergepaySdk({oid, authToken, environmentUrl});

const app: any = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({extended:true}));
app.use(cors());

//The client side can hit this endpoint by issuing a POST request to
//localhost:5555/start-transaction
//device_name and external_tran_id are required in the fields array.
app.post("/start-transaction", (req, res) => {
    const amount = "0.01";
    const config: any = {
        transactionType: TransactionType.RequestSignature,
        method: "modal",
        fields: [
            {
                id : "external_tran_id",
                value : emergepay.getExternalTransactionId()
            },
            {
                id : "device_name",
                value : "{your_device_name}"
            }
        ]
    };

    emergepay.startTransaction(config)
        .then(transactionToken => {
            res.send({
                transactionToken: transactionToken
            });
        })
        .catch(err => {
            res.send(err.message);
        });
});

console.log("listening on port 5555");
app.listen(5555);

<?php

//Configure your oid, authToken, and environmentUrl.
//These are required and supplied by Gravity Payments.
//Note: Make sure you set these before attempting to retrieve transaction results.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

$url = $environmentUrl . '/orgs/' . $oid . '/transactions/start';

//Set up the request body.
//device_name and external_tran_id are required in the fields array. 
$body = [
  'transactionData' => [
    'transactionType' => 'RequestSignature',
    'method' => 'modal',
    'fields' => [
      ['id' => 'external_tran_id', 'value' => GUID()],
      ['id' => 'device_name', 'value' => '{your_device_name}']
    ]
  ]
];

//Configure the request
$request = curl_init($url);
curl_setopt($request, CURLOPT_HEADER, false);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_HTTPHEADER, array('Content-Type: application/json', 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, json_encode($body));

//Issue the request and get the response
$response = curl_exec($request);
curl_close($request);

echo $response;

//Helper function used to generate a GUID/UUID
//source: http://php.net/manual/en/function.com-create-guid.php#99425
function GUID()
{
    if (function_exists('com_create_guid') === true)
    {
        return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
}

public async Task StartTransactionAsync(StartTransactionModel config)
{
  var response = new object();

  //Ensure these are set before trying to issue the request.
  //Please contact Gravity Payments to get these values.
  const string OID = "your_oid";
  const string AUTH_TOKEN = "your_authToken";
  const string ENDPOINT_URL = "environment_url";

  string url = $"{ENDPOINT_URL}/orgs/{OID}/transactions/start";

  //all of the values in fields are strings
  var contents = new
  {
    transactionData = new
    {
      transactionType = "RequestSignature",
      method = "modal",
      fields = new[] {
        new { id = "external_tran_id",      value = Guid.NewGuid().ToString() },
        new { id = "device_name",           value = config.DeviceName }
      }
    }
  };

  try
  {
    using (var client = new HttpClient())
    {
      var transactionJson = JsonConvert.SerializeObject(contents);

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, url);
      request.Headers.Add("Authorization", $"Bearer {AUTH_TOKEN}");
      request.Content = new StringContent(transactionJson, Encoding.UTF8, "application/json");

      var httpResponse = await client.SendAsync(request);
      var data = await httpResponse.Content.ReadAsStringAsync();
      response = JsonConvert.DeserializeObject(data);
    }
  }
  catch (Exception exc)
  {
    throw exc;
  }

  return response;
}

Step 1: Start Transaction

Merchant server only

Environment & Asset URLs

Available Transaction Types

CreditSale

Input Fields for CreditSale

Funding

Note

CreditReturn

Input Fields for CreditReturn

Funding

Note

CreditAuth

Capturing a CreditAuth

Input Fields for CreditAuth

CreditSaveCard

Input Fields for CreditSaveCard

AchSale

Input Fields for AchSale

AchReturn

Input Fields for AchReturn

AchSaveAccount

Input Fields for AchSaveAccount

Step 2: Present Payment Form

Client-side only

Note

Step 3: Transaction Results

Merchant server only

Results Options

Postback

HMAC Signature Validation

Verify HMAC signature

What's a 'secret passphrase'?

Retrieval

Account Card Type Values

Example transaction result responses

Print or Email Receipt

Step 4: Transaction Acknowledgment

Merchant server only

What is the purpose of Transaction Acknowledgment?

Best Practices

Transaction acknowledgement path parameter requirements

Step 5: Are you using a payment device?

Available Transaction Types

Transaction Types Not Available

Additional transaction input fields required

Testing Without a Physical Device

Partial Approval Support

Tipping Support

Input fields for RequestSignature

Device Support

Provide your information for follow-up (Optional)