Tokenized payment

Running Synchronous Tokenized Transactions

Getting results

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

Tokenized Payment

This sample code shows how to run a tokenized
payment using a CIP token.
//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 uniqueTransId before trying to run the tokenized payment.
emergepay.tokenizedPaymentTransaction({
    uniqueTransId: "your_unique_trans_id",
    externalTransactionId: emergepay.getExternalTransactionId(),
    amount: "0.01",
    // Optional
    cashierId: "",
    billingName: "",
    billingAddress: "",
    billingPostalCode: "",
    tipAmount: "",
    transactionReference: "",
    // Only applicable to level 2 transactions
    taxAmount: "",
    level2: {
        isTaxExempt: false,
        purchaseId: "", // required
        purchaseOrderNumber: "", // required
        customerTaxId: "",
        destinationPostalCode: "",
        productDescription: ""
    },
  	// Only applicable for pfac
  	funding: {
	  splitsWith: [
		{ oid: "1111111111", amount: "0.50" }
	]
  }
})
.then(function(response) {
    var data = 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 uniqueTransId before trying to run the tokenized payment.
emergePay.tokenizedPaymentTransaction({
    uniqueTransId: "your_unique_trans_id",
    externalTransactionId: emergePay.getExternalTransactionId(),
    amount: "0.01",
    // Optional
    cashierId: "",
    billingName: "",
    billingAddress: "",
    billingPostalCode: "",
    tipAmount: "",
    transactionReference: "",
    // Only applicable to level 2 transactions
    taxAmount: "",
    level2: {
        isTaxExempt: false,
        purchaseId: "", // required
        purchaseOrderNumber: "", // required
        customerTaxId: "",
        destinationPostalCode: "",
        productDescription: ""
    },
  	// Only applicable for pfac
  	funding: {
	  splitsWith: [
		{ oid: "1111111111", amount: "0.50" }
	]
  }
})
.then(response => {
  const data = response.data;
})
.catch(error => {
  throw error;
});
<?php

//Configure your oid and authToken. These are supplied by Gravity Payments.
$oid = 'your_oid';
$authToken = 'your_authToken';
$environmentUrl = 'environment_url';

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

//Set the uniqueTransId you want to use to run the tokenized payment
$uniqueTransId = 'your_unique_trans_id';

//Configure the request body.
//uniqueTransId, externalTransactionId, and amount are all required.
$body = [
  'transactionData' => [
    'uniqueTransId' => $uniqueTransId,
    'externalTransactionId' => GUID(),
    'amount' => '0.01',
    // Optional
    'cashierId' => '',
    'billingName' => '',
    'billingAddress' => '',
    'billingPostalCode' => '',
    'tipAmount' => '',
    'transactionReference' => '',
    // Only applicable to level 2 transactions
    'taxAmount' => '',
    'level2' => [
        'isTaxExempt' => false,
        'purchaseId' => '', // required
        'purchaseOrderNumber' => '', // required
        'customerTaxId' => '',
        'destinationPostalCode' => '',
        'productDescription' => ''
    ],
    // Only applicable for pfac
  	'funding' => [
	  'splitsWith' => [
		[ 'oid' => '1111111111', 'amount' => '0.50' ]
	  ]
  	]
  ]
];

$payload = json_encode($body);

//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', 'Content-Length: ' . strlen($payload), 'Authorization: Bearer ' . $authToken));
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($request, CURLOPT_POSTFIELDS, $payload);

$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 TokenizedPaymentAsync()
{
  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/tokenizedPayment";

  //Ensure that you supply a valid uniqueTransId before trying to run the tokenized payment.
  string uniqueTransId = "your_unique_trans_id";
  
  var contents = new
  {
    transactionData = new
    {
      uniqueTransId = uniqueTransId,
      externalTransactionId = Guid.NewGuid().ToString(),
      amount = "0.01",
      // Optional
      cashierId = "",
      billingName = "",
      billingAddress = "",
      billingPostalCode = "",
      tipAmount = "",
      transactionReference = "",
      // Only applicable to level 2 transactions
      taxAmount = "",
      level2 = new
      {
          isTaxExempt = false,
          purchaseId = "", // required
          purchaseOrderNumber = "", // required
          customerTaxId = "",
          destinationPostalCode = "",
          productDescription = ""
      },
	  // Only applicable for pfac
	  funding = new
      {
		splitsWith = new[]
          {
        	new { oid = "1111111111", amount = "1.00" },
      	  }
      }
    }
  };

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

      HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Put, 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

NameDetailsRequiredDescription
amountType: string
Min length: 3
Max length: 13
Min Example: 0.01
Max Example: 9999999999.99
YesThe transaction amount.
tipAmountType: string
Min length: 3
Max length: 13
Min Example: 0.01
Max Example: 9999999999.99
NoAn optional tip amount that can be added at the time of the sale. The total amount of the sale will be equal to tipAmount + amount
externalTransactionIdType: v4 uuidYesA 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.
uniqueTransIdType: string
Max length: 65
YesThe uniqueTransId from a previous transaction. This is the token that is used to run additional transactions or voids.
billingNameType: string
Max length: 75
NoThe customers' billing name.
billingAddressType: stringNoThe customers' street address.
billingPostalCodeType: stringNoThe customers' zip code.
transactionReferenceType: string
Min length: 3
Max length: 65
NoThe order id associated with the transaction.
cashierIdType: string
Max length: 150
NoThe name of the cashier that ran the transaction.
taxAmountType: string
Min length: 4
Max length: 13
Min Example: 0.00
Max Example: 9999999999.99
NoThe tax amount for a level 2 transaction. This field is required for level 2 transactions. If level2.isTaxExempt is true, then the value of this field must be 0.00. The total amount of the sale will be equal to taxAmount + amount.
level2Type: objectNoThe level 2 details for the transaction request. Only applicable to level 2 transactions. See the Level 2 section below for more information.

Level 2

Name Details Required Description
isTaxExempt Type: boolean No Indicates whether the level 2 transaction is tax exempt. Defaults to false.
purchaseId Type: string
Max length: 25
Yes This field is the merchant’s internal identifier for the transaction. This field is required for level 2 transactions.
purchaseOrderNumber Type: string
Max length: 17
Yes The customer supplied order number.
customerTaxId Type: string
Max length: 15
No The customer’s tax identifier.
destinationPostalCode Type: string
Max length: 9
No The customer’s zip code
productDescription Type: string
Max length: 40
No The description for the order.