Tokenized force

Forcing an authorization

  • The uniqueTransId for a force transaction must be a uniqueTransId from an authorization transaction.
  • An authorization can only be forced one time.
  • The force transaction will move the funds that were secured on the customer’s card when the authorization was processed into the merchant’s bank account.
  • A force transaction cannot be adjusted or voided. If there is a need to reverse a force transaction, a void must be run on the authorization transaction. (This action will, in effect, void the force).
This sample code shows how to run a tokenized
force 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 force.
emergepay.forceTransaction({
    uniqueTransId: "your_unique_trans_id",
    externalTransactionId: emergepay.getExternalTransactionId(),
    // Optional values
    amount: "0.01",
    tipAmount: "0.01",
    cashierId: "",    
    transactionReference: "",
    // Only applicable to level 2 transactions
    taxAmount: "",
  	// 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 force.
emergepay.forceTransaction({
    uniqueTransId: "your_unique_trans_id",
    externalTransactionId: emergepay.getExternalTransactionId(),    
    // Optional values
    amount: "0.01",
    tipAmount: "0.01",
    cashierId: "",    
    transactionReference: "",
    // Only applicable to level 2 transactions
    taxAmount: "",
  	// 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/tokenizedForce';

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

//Configure the request body.
//uniqueTransId, externalTransactionId, and amount are all required.
$body = [
  'transactionData' => [
    'uniqueTransId' => $uniqueTransId,
    'externalTransactionId' => GUID(),    
    // Optional values
    'amount' => '0.01',
    'tipAmount' => '0.01',
    'cashierId' => '',    
    'transactionReference' => '',
    // Only applicable to level 2 transactions
    'taxAmount' => '',
    // Only applicable to 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 TokenizedForceAsync()
{
  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/tokenizedForce";

  //Ensure that you supply a valid uniqueTransId before trying to run the tokenized force.
  string uniqueTransId = "your_unique_trans_id";
  
  var contents = new
  {
    transactionData = new
    {
      uniqueTransId = uniqueTransId,
      externalTransactionId = Guid.NewGuid().ToString(),
      // Optional values
      amount = "0.01",
      tipAmount = "0.01",
      cashierId = "",     
      transactionReference = "",
      // Only applicable to level 2 transactions
      taxAmount = "",
	  // 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
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 an authorization transaction. The force transaction will finalize the authorization and move the authorized funds from the customer's card to the merchant's bank account.
amountType: string
Min length: 4
Max length: 13
Min Example: 0.01
Max Example: 9999999999.99
NoThe base amount of the transaction. If this parameter is omitted, the current base amount of the authorization will be applied.
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.
tipAmountType: string
Min length: 4
Max length: 13
Min Example: 0.00
Max Example: 9999999999.99
NoAn optional tip amount that can be added at the time of the force transaction. If this parameter is omitted, the current tip amount of the authorization will be applied.
taxAmountType: string
Min length: 4
Max length: 13
Min Example: 0.00
Max Example: 9999999999.99
NoThe tax amount for a level 2 transaction. Note that this field is only valid when the original authorization also contained level 2 fields in the request.