All API variables broken into parts.

Owned by Vitaly Zaharovs (Unlicensed)
Last updated: Jan 22, 2013Version comment
General overview of the API

Part 0 - Test Requests

Field Name

Required

Description

x_test_request

NO

Value: TRUE, FALSE, YES, NO,

If YES/TRUE, requests made will not be settled


Part 1 - Merchant Info

(Always Required to send transaction requests, no matter what kind)

Field Name

Required

Description

x_login

X

Value: The merchant’s unique Login ID
Format: Up to 20 character
Provided by the NaviGate gateway.

The Login ID and Transaction Key together are required to be able to send requests to the gateway API.

x_tran_key

X

Value: The merchant’s unique Transaction Key
Format: 16 character

This key is generated by NaviGate in Profile & Settings » Security » Transaction Key

 

Part 2 - AIM Head

(Not really required but is considered good practice and is preferred to include in the API request call)

Field Name

Required

Description

x_version

X

Value: 3.1 (constant/static)

Not required but is considered good practice and the system prefers to see it

x_delim_data

X

Value: TRUE/FALSE

Based on the value (TRUE/FALSE) the response is going to be either delimited or not.

x_delim_char

X

Value: any character that is normally used for delimiting data

Possible variants: comma (,); semicolon (;); pipe (|); etc

x_relay_response

X

Value: FALSE (constant/static) 

Not required but is considered good practice and the system prefers to see it

 

Part 3 – Transaction Info

(Different requirements, depending on the transaction type. Default is AUTH_CAPTURE)

 

Field Name

Required

Description

x_Method

X

Value: The Method of credit card transaction
Format: CC; (SVP – not fully functional » ?) 

If this field is not submitted or the value is blank, the payment gateway will generate an error "x_Method cannot be left blank".

x_type

X

Type

Definition

 

AUTH_CAPTURE

Authorize and Capture – reserves and amount and charges the account.

 

AUTH_ONLY

Authorization – reserves an amount but does not charge. Charging an account occurs later

 

CREDIT

Issue a credit – refund amount previously charged

 

PRIOR_AUTH_CAPTURE

Capture – charges an account that was previously Authorized

 

VOID

Voids transaction – Cancels Auth & Capture and Authorization

 

If the value submitted does not match a supported value, the transaction is rejected. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_type cannot be left blank".

x_amount

X

Value: The amount of the transaction
Format: Up to 15 digits (no dollar symbol or cents separators).

For example, “1020” would mean $10.20 and “110” would mean $1.10

This is the total amount and must include tax, shipping, and any other charges. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_amount cannot be left blank".

x_card_num

X

Value: The customer’s credit card number
Format: Between 13 and 16 digits without spaces. 

This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_card_num cannot be left blank".

x_card_code

X

Value: The customer’s credit card security code.
Format: 3 or 4 digit code depending on the issuer 

The security code is located on the card in different places, depending on the issuer.

Take a look at the image below which shows usual locations for the code. 

x_exp_date

X

Value: The customer’s credit card expiration date.
Format: MMYY 

This is sensitive cardholder information and must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_exp_date cannot be left blank".

x_trans_id

Depends

Value: The payment gateway-assigned ID that links the current authorization request to the original authorization request.
Format: Numeric 

This value applies only to partial authorization transactions, and is returned in the reply message from the original authorization request. If this field is not submitted or the value is blank, the payment gateway will generate an error "x_trans_id cannot be left blank".

 

Part 4 – Order Info

(Not required, but preferred for initial transactions; AUTH_CAPTURE and AUTH_ONLY)

Field Name

Required

Description

x_invoice_num

No

Value: This is a merchant supplied number that they want to be able to track the sales by in NaviGate.
Format: string (any characters)

x_description

No

Value: This is a merchant supplied description of the sale that was made.
Format: string (any characters)


Part 5 – Customer Info    

(Information about the person making the payment)

Field Name

Required

Description

x_first_name

 

Value: Self-explanatory.
Format: string

x_last_name

 

Value: Self-explanatory.
Format: string

x_company

 

Value: Self-explanatory.
Format: string

x_address

 

Value: Self-explanatory.
Format: string

x_city

 

Value: Self-explanatory.
Format: string

x_state

 

Value: Self-explanatory.
Format: string

Example: NY (New York)

x_zip

 

Value: Self-explanatory.
Format: string

x_country

No

Value: Self-explanatory.

Format: string

Example: USA (United State of America)

x_phone

No

Value: Self-explanatory.
Format: numeric (no dashes)

x_fax

No

Value: This is a merchant supplied description of the sale that was made.
Format: numeric (no dashes)

x_Email

 

Value: Self-explanatory.
Format: string

x_cust_id

No

Value: Customer ID, provided by the merchant.
Format: string

Example: This ID is supplied by the merchant at the time of sale to track individual customers purchasing patterns.

x_customer_ip

 

Value: This is the IP address of the location where the transaction came from.
Format: string


Part 6 – Shipping Info

Field Name
Description
x_ship_to_first_name

Optional

Value: The first name associated with the customer’s shipping address

Format: Up to 50 characters (no symbols)

x_ship_to_last_name

Optional

Value: The last name associated with the customer’s shipping address

Format: Up to 50 characters (no symbols)

x_ship_to_company

Optional

Value: The company associated with the customer’s shipping address

Format: Up to 50 characters (no symbols)

x_ship_to_address

Optional

Value: The customer’s shipping address

Format: Up to 60 characters (no symbols)

x_ship_to_city

Optional

Value: The city of the customer’s shipping address

Format: Up to 40 characters (no symbols)

x_ship_to_state

Optional

Value: The state of the customer’s shipping address

Format: Up to 40 characters (no symbols) or a valid two-character state code

x_ship_to_zip

Optional

Value: The ZIP code of the customer’s shipping address

Format: Up to 20 characters (no symbols)

x_ship_to_country

Optional

Value: The country of the customer’s shipping address

Format: Up to 60 characters (no symbols)

 

Part 7 – Tax Info

Field Name

Description

x_tax

This optional field can contain either the valid tax amount or the delimited tax information. When submitting delimited tax information, values must be delimited by a bracketed pipe <|> in the order shown below. The total amount of the transaction in x_amount must include this amount.

The delimited tax information elements are:

  • tax item name<|>
  • tax description<|>
  • tax amount: The dollar sign ($) is not allowed when submitting delimited information.

The total amount of the transaction in x_amount must include this amount.

Example: x_tax=Tax1<|>state tax<|>0.09&

Format: string

x_tax_exempt

This optional field can contain the tax exempt status of the order.
The values of this field can include: TRUE, FALSE, T, F, YES, NO, Y, N, 1, 0

Format: string


Part 8 – Email Notifications

Field Name

Description

x_email_customer

Value: TRUE/FALSE
If True, then the customer will receive an email notifying them about the transaction.

Format: BOOL

x_email_merchant

Value: TRUE/FALSE
If True, then the merchant will receive an email notifying them about the transaction.

Format: BOOL

x_merchant_email

Value: email address
This is the email address that the merchant uses to receive notifications about transaction update to.

Example: newsale@somedomain.com

Format: string


Part 9 – Recurring Billing

Field Name

Description

x_recurring_billing

Value: YES/NO

If Yes, then the customer will be charged automatically for the same amount as is set in x_amount.

How often the person is charged is defined in x_recurring_frequencyType.
The number of iteration is set in x_recurring_frequency

Format: BOOL

x_recurring_frequencyType

Value: Daily, Weekly, Monthly, etc

This variable defines the frequency or period on the basis of which the person gets charged.

Format: string

x_recurring_frequency

Value:

This variable sets the max amount of iterations (or number of periods)

Example: If the one period is a week and the number of periods is 15, then the person will be charged for 15 weeks on a weekly basis and then the recurring charges will stop.

Format: numeric

x_Token_Flag

Value: YES/NO

Format: BOOL


Specific transactions requirements

NaviGate supports the following unique requests:

AUTH_CAPTURE

  • Authorize and Capture – reserves and amount and charges the account.

AUTH_ONLY

  • Authorization – reserves an amount but does not charge. Charging an account occurs later

CREDIT

  • Issue a credit – refund amount previously charged

PRIOR_AUTH_CAPTURE

  • Capture – charges an account that was previously Authorized

VOID

  • Voids transaction – Cancels Auth & Capture and Authorization

 

AUTH_CAPTURE & AUTH_ONLY

These 2 require that you send the majority of the variables to the API.

The following parts are required:

Parts 1, 2, and 3.

In part 3, set x_type equal to either AUTH_CAPTURE or AUTH_ONLY depending on what is being done and how...

You also need to provide customer information (part 5)

The rest of the parts can be provided, but are not required.

Sample AUTH_CAPTURE and AUTH_ONLY request
	// Merchant Info
	'x_login'			=> $login,
	'x_tran_key'		=> $transactionKey,
	// TEST TRANSACTION
	'x_test_request'	=> '', // True or False
	
	// AIM Head
	'x_version'			=> '3.1',
	// TRUE Means that the Response is going to be delimited
	'x_delim_data'		=> 'TRUE',
	'x_delim_char'		=> '|',
	'x_relay_response'	=> 'FALSE',
	
	// Transaction Info
	'x_method'          => 'CC',
	'x_type'            => 'AUTH_CAPTURE',
	'x_amount'          => '1.00',
	
	// Test Card
	'x_card_num'        => '5431111111111111',
	'x_exp_date'        => '1215',
	'x_card_code'       => '123',
	'x_trans_id'        => '',
	
	// Order Info
	'x_invoice_num'     => 'inv123456',
	'x_description'     => 'Vit - test',
	
	// Customer Info
	'x_first_name'      => 'John',
	'x_last_name'       => 'DoAble',
	'x_company'         => 'MerchantPlus',
	'x_address'         => '29 Broadway',
	'x_city'            => 'New York',
	'x_state'           => 'NY',
	'x_zip'             => '10006',
	'x_country'         => 'USA',
	'x_phone'           => '2121225050',
	'x_fax'             => '2121225050',
	'x_Email'           => 'vitaly@merchantplus.com',
	'x_cust_id'         => 'c_123456789', // Optional - Provided by merchant at the time of sale...
	'x_customer_ip'     => '',
	
	// shipping info
	'x_ship_to_first_name'  => '',
	'x_ship_to_last_name'   => '',
	'x_ship_to_company'     => '',
	'x_ship_to_address'     => '',
	'x_ship_to_city'        => '',
	'x_ship_to_state'       => '',
	'x_ship_to_zip'         => '',
	'x_ship_to_country'     => '',
	
	// Additional Fields
	'x_email_customer'  	=> 'TRUE', // If True will send a notification of transaction to customers email
	'x_email_merchant'		=> 'TRUE',
	'x_merchant_email'		=> 'vitaly@merchantplus.com',
/*
	// Tax Info & Shipping Costs
	'x_tax'					=> '',
	'x_tax_exempt'			=> '',
	'x_freight'				=> '',
	'x_duty'				=> '',
			
	// Recurring Transactions
	'x_recurring_billing'=> 'YES',
	'x_Recurring_FrequencyType'=>'Daily',
	'x_Recurring_Frequency'=> 4,
	'x_Token_Flag'		=>'NO'
*/

 

CREDIT

This method requires the following:

Complete parts 1 and 2 and additional 3 variables:

x_type = CREDIT,

x_card_num = credit card number to credit

x_trans_id = of the initial transaction that was settled

Sample CREDIT request
// Merchant Info
	'x_login'			=> $login,
	'x_tran_key'		=> $transactionKey,
	'x_test_request'	=> '', // TEST TRANSACTION
	
// AIM Head
	'x_version'			=> '3.1',
	'x_delim_data'		=> 'TRUE', // Means that the Response is going to be delimited
	'x_delim_char'		=> '|',
	'x_relay_response'	=> 'FALSE',
	
// Transaction Info
	'x_method'          => 'CC',
	'x_type'            => 'CREDIT',
	'x_trans_id'        => 'find the number', // find the transaction # in NaviGate you want to issue a refund for
	'x_card_num'        => 'corresponding CC#', // reference card# that was used for the above mentioned transaction #

 

VOID

This method requires the following:

Complete parts 1 and 2 and additional 2 variables:

x_type = VOID,

x_trans_id = of the initial transaction that was settled

Sample VOID request
// Merchant Info
	'x_login'			=> $login,
	'x_tran_key'		=> $transactionKey,
	'x_test_request'	=> '', // TEST TRANSACTION
	
// AIM Head
	'x_version'			=> '3.1',
	'x_delim_data'		=> 'TRUE', // Means that the Response is going to be delimited
	'x_delim_char'		=> '|',
	'x_relay_response'	=> 'FALSE',
	
// Transaction Info
	'x_method'          => 'CC',
	'x_type'            => 'VOID',
	'x_trans_id'        => 'find the number', // find the transaction # in NaviGate you want to cancel


PRIOR_AUTH_CAPTURE

This method requires the following:

Complete parts 1 and 2 and additional # variables: