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
Name | Details | Required | Description |
---|---|---|---|
amount | Type: string Min length: 3 Max length: 13 Min Example: 0.01 Max Example: 9999999999.99 | Yes | The transaction amount. |
tipAmount | Type: string Min length: 3 Max length: 13 Min Example: 0.01 Max Example: 9999999999.99 | No | An 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 |
externalTransactionId | 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. |
uniqueTransId | Type: string Max length: 65 | Yes | The uniqueTransId from a previous transaction. This is the token that is used to run additional transactions or voids. |
billingName | Type: string Max length: 75 | No | The customers' billing name. |
billingAddress | Type: string | No | The customers' street address. |
billingPostalCode | Type: string | No | The customers' zip code. |
transactionReference | Type: string Min length: 3 Max length: 65 | No | The order id associated with the transaction. |
cashierId | Type: string Max length: 150 | No | The name of the cashier that ran the transaction. |
taxAmount | 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.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 . |
level2 | Type: object | No | The 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. |