Guides
Start typing to search…

Steps

Step 1: GetAPIKey

Send GetAPIKey

  • TERMID: Terminal ID of the merchant. This should be 8 alphanumeric characters, e.g., TEST0058.
  • PASS: Password for the Terminal ID, e.g., zX3Ht5va.
  • TYPE: Transaction type. Will be Z for Administrative (meaning, not a type of transaction).
  • SUBTYPE: Will be TA.
  • AMOUNT (Optional - will return USERFEE): Transaction amount in dollars and cents (e.g., one dollar is 1.00)
  • PLATFEE (Optional - can be used in conjunction with passing AMOUNT to get User Fee amount calculated and passed back. Do not need to include this field if you are not passing a Platform Fee): Platform Fee amount in dollars and cents (e.g., one dollar is 1.00)

Example Request:

{
  "TYPE": "Z",
  "ACTION": "GETAPIKEY",
  "SUBTYPE": "TA",
  "TERMID": "TERM1234",
  "PASS": "PASS1234",
  "AMT": "15.00"
}

Response to GetAPIKey

  • CODE: Response code (0000 for success).
  • TEXT: "KEY GENERATED", or the error message.
  • APIKEY: APIKey for your browser to use
  • HOST: Host name to load the Javascript and to pass to the Tokenize
  • USERFEE (if AMT was sent in Request): The calculated Customer Pay processing fee for that transaction; Returned in dollars and cents with a decimal (i.e. 1.50)
  • DATE: Date of the request
  • TIME: Time of the request
  • DUR: Amount of time the gateway required to process the request

Example Response:

{
  "TEXT": "KEYGENERATED",
  "CODE": "0000",
  "APIKEY": "@E1C51941FD4204F70F36A7AFBB21BDAF969E682CA6620E7C3C1E487965EC9779",
  "HOST": "https://testgate.interpaypos.com/api/payment",
  "USERFEE": "3.25",
  "DATE": "2024-10-14",
  "TIME": "10:00:00"
 	"DUR"= "0.383"
}

Step 2: Complete Interpay.Validate (Optional)

You can choose to use the validation function to validate each input as the cardholder is entering the information. Alternatively, you can skip to Step 3 - Complete Interpay.Tokenize to retrieve the OTT (One-Time Token) simultaneous to validating the card data.

Complete this function using the APIKEY from Step 1 and the user inputted cardData.

cardData

cardData is a Javascript object with the following fields:

Required Fields:

  • CARDNUM: Credit card number; numeric; no spaces or dashes.
  • CARDEXPMM: Expiration Month; Must be 2 numeric characters (i.e. 02 for February, 12 for December)
  • CARDEXPYYYY: Expiration Year; Must be 4 numeric characters (i.e. 2027)
  • CARDCVV: Card Verification Value; Must be 3 or 4 numeric characters (i.e. 123 or 7890)

Example Call

var interpay = new InterPay();
var respValidate = interpay.validate(apiKey, cardData);
if(respValidate.datavalid){
		//call tokenize here
}else {
		//failed logic here
}

True Response:

{"tokenized":false,"text":"","datavalid":true,"apikey":{"isvalid":true,"message":""},"cardnum":{"isvalid":true,"message":""},"cardexp":{"isvalid":true,"message":""},"cardcvv":{"isvalid":true,"message":""}}

False Response:

{"tokenized":false,"text":"","datavalid":false,"apikey":{"isvalid":true,"message":""},"cardnum":{"isvalid":true,"message":""},"cardexp":{"isvalid":true,"message":""},"cardcvv":{"isvalid":false,"message":"Invalid card cvv"}}

Step 3: Complete Interpay.Tokenize

Complete this function using the HOST and APIKEY from Step 1 in order to obtain a OTT (One-Time Token) to perform a Host-Based Transaction.

You will load the JS Library to <HOST>/assets/interpay_embed_test.min.js

Example: https://testgate.interpaypos.com/assets/interpay_embed_test.min.js

🚧

The Javascript library file name will be different in production


Request with Callback

var interpay = new InterPay();
//when validated
await interpay.tokenize(host, apiKey, cardData, displayResult);

Request without Callback

var interpay = new InterPay();
//when validated
var respData = await interpay.tokenize(host, apiKey, cardData);
console.log(respData);

True Response:

{"tokenized":true,"text":"TOKEN OK","datavalid":true,"apikey":{"isvalid":true,"message":""},"cardnum":{"isvalid":true,"message":""},"cardexp":{"isvalid":true,"message":""},"cardcvv":{"isvalid":true,"message":""},"ott":"4200HDETSHGT0042"}

False Response:

{"tokenized":false,"text":"INVALID APIKEY","datavalid":true,"apikey":{"isvalid":true,"message":""},"cardnum":{"isvalid":true,"message":""},"cardexp":{"isvalid":true,"message":""},"cardcvv":{"isvalid":true,"message":""},"ott":""}

If the result object has “datavalid:false”, then check each data (APIKEY, CARDNUM, CARDEXPMM, CARDEXPYYYY, CARDCVV) for a “isvalid:false” message so that you can retrieve the validation error text to display to the user.

If the result object has “tokenized:false”, the gateway rejected the request. Refer to the message in the “text” field.


Step 4: Use OTT to Complete Direct Payment Transaction

You can now use the OTT (One-Time Token) as the Card Data to complete any Direct Payment Transaction such as Sale, Void, Refund, or Tokenize.

This must be completed within 10 minutes of your webserver obtaining the OTT.

📘

All Host Based Transactions include a "permanent" TOKEN in the response which you can use to save to the users profile as a means to save the card to their profile. Alternatively, you can use your OTT to complete a Tokenize Host-Based Transaction to just obtain a TOKEN.

Updated about 1 year ago