Syntch Gateway API

CreateTransactionRequest

Transaction Processing (V1)

**Requires Authentication**
Required role:	Merchant

The following routes are available for this service:
POST	/transactions	Run a transaction with a card or check	Transactions may be processed using all supported payment types including Credit, Debit, Check, Cash, Gift and Loyalty. Tokens may also be used for processing against a stored payment method.

**CreateTransactionRequest** Parameters:
Name	Parameter	Data Type	Required	Description
TransactionType	model	TransactionTypes	Yes	Identifies the type of transaction to process. Allowable Values Authorization Sale Return Void Force Capture CaptureAll RepeatSale Adjustment Activate Deactivate Redeem Inquire Reload
CardData	model	CardData	No	Properties of the card/account used as payment for this transaction, if the payment type is card.
CheckData	model	CheckData	No	Properties of the check/checking account used as payment for this transaction, if the payment type is check.
DeviceData	model	DeviceData	No	Properties of the terminal/reader used in the transaction.
Fsa	model	Fsa	No	Optional detail amount fields used in the processing of FSA/HSA processing.
SoftDescriptor	model	SoftDescriptor	No	Fields necessary to submit alternate merchant information for this transaction, when supported by the processor.
ForceDuplicate	model	boolean	No	This is an indicator that specifies - if this transaction is flagged as a duplicate of a previous transaction - whether or not this transaction will be processed.
Register	model	string	No	Identifies the physical or virtual register where the transaction is run, for reporting.
InvoiceData	model	Invoice	Yes	Tracking/reporting fields used for identifying the transaction and associating it with a customer invoice.
OriginalTransaction	model	OriginalTransaction	No	Properties of the original transaction, when necessary for processing the current transaction (such as refunds, voids, reversals).
CustomFields	model	CustomField[]	No	Merchant-configured fields used to store data per transaction outside the system fields.
SignatureData	model	SignatureData	No	Used to accept and store image data for receipts captured on an external device.
Level2Data	model	Level2Data	No	Required to qualify transactions for level 2 processing.
Level3Data	model	Level3Data	No
AuthCode	model	string	No	Original authorization/approval code, required for Force transactions.
UseInterchangeDefaults	model	bool?	No	Whether or not to provide the default values as specified for the applicable merchant in the interchange optimization configuration.
CaptureType	model	CaptureTypes	No	Required for capture/capture all transactions. Indicates what type of payment to capture. Allowable Values Credit Debit Check EBT

**TransactionTypes** Enum:
Name	Value
Authorization	1
Sale	2
Return	3
Void	4
Force	5
Capture	6
RepeatSale	7
CaptureAll	8
Adjustment	9
Activate	10
Deactivate	11
Redeem	12
Inquire	13
Reload	14

**CardData** Parameters:
Name	Parameter	Data Type	Required	Description
CardNumber	model	string	No	Credit card number used to uniquely identify the card owner’s account.
ExpirationDate	model	string	No	Credit card date of expiration in MMYY format.
Cvv	model	int?	No	Card verification number. Note: This parameter may be required depending on the merchant’s setup.
NameOnCard	model	string	No	Name of the cardholder, as displayed on the card
Pin	model	string	No	The encrypted PIN-block returned by the PIN pad. The transaction will fail if an unencrypted PIN is used. Note: This information is not required for PIN-less debit transactions.
KeySerialNumber	model	string	No	PIN pad serial number used in managing DUKPT PIN pads. This is required for all transactions where a pin is present
Token	model	string	No	A value generated by the gateway for payment data which has been previously stored. The format of the value depends on the format selected when the payment method was originally stored.
EmvData	model	string	No	The TLV (tag-length-value) string provided by the certified, emv-capable terminal. This value should not be modified before transmission.
TrackData	model	string	No	The magnetic stripe/track data read from a swiped transaction. If the card reader is capable of reading both track 1 and track 2, only track 2 should be provided.
EncryptedTrack1Data	model	string	No	The encrypted magnetic stripe/track 1 data read from a secure reader
EncryptedTrack2Data	model	string	No	The encrypted magnetic stripe/track 2 data read from a secure reader
EncryptedTrack3Data	model	string	No	The encrypted magnetic stripe/track 3 data read from a secure reader
IIN	model	string	No	The card IIN when using an encrypted magnetic stripe/track data read from a secure reader
ARQC	model	string	No	The encrypted ARQC generated from a secure reader chip-based transaction
EntryMode	model	EntryModes	No	The method in which card data was collected. This is used in conjunction with other properties of the transaction to determine the correct values for card and cardholder presence to send to the processor. Allowable Values Manual Swipe ICC Proximity
CvPresence	model	CVPresence	No	The presence/status of the card verification number on the card and in the transaction Allowable Values None NotSubmitted Submitted Illegible NotPresent
Street	model	string	No	The billing address of the card. Used for AVS (address verification) if it is enabled for the merchant
ZipCode	model	string	No	The billing zip code of the card. Used for AVS (address verification) if it is enabled for the merchant
Phone	model	string	No	Card owner's phone number.
Email	model	string	No	Card owner's email address.

**EntryModes** Enum:
unknown
notApplicable
manual
unencryptedCardReaderSwipe
encryptedCardReaderSwipe
icc
proximity
fallback

**CVPresence** Enum:
none
notSubmitted
submitted
illegible
notPresent

**CheckData** Parameters:
Name	Parameter	Data Type	Required	Description
NameOnCheck	model	string	Yes	Name of the check owner
RoutingNumber	model	string	Yes	Uniquely identifies the bank holding funds.
AccountNumber	model	string	Yes	Uniquely identifies the check owner’s bank account.
CheckNumber	model	string	No	Uniquely identifies an individual’s check.
MICR	model	string	No	Magnetic Ink Character Recognition. Note: This input is required for processing check-present and consumer-present transactions.
DriversLicense	model	string	No	Check owner’s driver’s license number.
State	model	string	No	Check owner’s two-character state code.
SSN	model	string	No	Check owner's social security number.
DateOfBirth	model	string	No	Check owner's date of birth.
CheckType	model	CheckType	No	Identifies the type of check used in the transaction.
AccountType	model	CheckAccountType	No	Identifies the type of account used as a source of funds.
RawMICR	model	string	No	Raw Magnetic Ink Check Reader data line from the check reader.
BranchCity	model	string	No	City of the check owner's bank branch.
EmailAddress	model	string	No	Check owner's email address.
TelephoneNumber	model	string	No	Check owner's phone number.
Token	model	string	No	A value generated by the gateway for payment data which has been previously stored. The format of the value depends on the format selected when the payment method was originally stored.
Address	model	Address	No	Address data on the check holder.
SECCode	model	string	No	Sets the Standard Entry Class code for the transaction. Allowable Values CCD PPD WEB ARC TEL

**CheckType** Enum:
Name	Value
Personal	1
Business	2

**CheckAccountType** Enum:
Name	Value
Checking	1
Savings	2

**Address** Parameters:
Name	Parameter	Data Type	Required	Description
StreetAddress1	model	string	Yes	The street address, max 50 chars
StreetAddress2	model	string	No	The street address 2, max 50 chars
StreetAddress3	model	string	No	The street address 3, max 50 chars
City	model	string	No	The city, max 50 chars
StateOrProvinceCode	model	string	Yes	The CHAR-2 USA state and CAN province codes Allowable Values AK AL AR AZ CA CO CT DC DE FL GA HI IA ID IL IN KS KY LA MA MD ME MI MN MO MS MT NC ND NE NH NJ NM NV NY OH OK OR PA RI SC SD TN TX UT VA VT WA WI WV WY AB BC MB NB NL NS NT NU ON PE QC SK YT
PostalCode	model	string	Yes	The postal code, max 30 chars
CountryCode	model	string	Yes	The ISO Alpha-3 USA or CAN country codes Allowable Values USA CAN

**DeviceData** Parameters:
Name	Parameter	Data Type	Required	Description
SdkVersion	form	string	No	The SDK version of the device
SerialNumber	form	string	No	The serial number of the device
BatteryLevel	form	int?	No	The current battery level of the device
IsEncrypted	form	bool	No	Indicates whether or not transaction data sent from the device is encrypted
EncryptionType	form	string	No	Type of encryption used when transaction data is encrypted

**Fsa** Parameters:
Name	Parameter	Data Type	Required	Description
partialAuthSupport	model	bool	No	Enables/disables partial authorizations for FSA transactions
qhpAmount	model	float	No	Identifies the total Healthcare amount. When additional FSA amounts are supported by a merchant, this amount includes those totals.
rxAmount	model	float	No	Total amount of prescriptions used to gain access to Rxonly purses. This amount is included in the Total QHP Amount.
visionAmount	model	float	No	Total amount of vision care purchases. This amount is included in Total QHP Amount.
dentalAmount	model	float	No	Total amount of dental services. This amount is included in Total QHP Amount.
clinicalAmount	model	float	No	Total amount of clinic or other medical services. This amount is included in Total QHP Amount.
copayAmount	model	float	No	Total amount for co-payments
transitAmount	model	float	No	Total amount for transit purchases; mass transit passes, for example

**SoftDescriptor** Parameters:
Name	Parameter	Data Type	Required	Description
AltMerchantName	model	string	No	Contains the merchant name/product/service to be used in lieu of the DBA name on file.
AltMerchantAddress	model	string	No	Contains the merchant address to be used in lieu of the merchant address on file.
AltMerchantCity	model	string	No	Contains the merchant city to be used in lieu of the merchant city on file.
AltMerchantState	model	string	No	Contains the merchant state to be used in lieu of the merchant state on file.
AltMerchantZip	model	string	No	Contains the merchant zip to be used in lieu of the merchant zip on file.

**Invoice** Parameters:
Name	Parameter	Data Type	Required	Description
customerId	model	string	No	Unique identifier for the customer/cardholder
totalAmount	model	float	Yes	Total amount of the transaction
tipAmount	model	float	No	Amount charged at the cardholder's discretion for tip/gratuity
taxAmount	model	float?	No	Amount charged by a merchant for state/local sales tax
shippingAmount	model	float	No	Amount charged by a merchant for shipping physical goods
convenienceAmount	model	float	No	Allows the merchant to add a flat fee to the total transaction. This function may be used by utility companies, government agencies, and schools.
convenienceAmountPercentage	model	float	No	Allows the merchant to add a percentage of the total amount as a fee to the total transaction (ex 10.5 would add a 10.5% fee). This function may be used by utility companies, government agencies, and schools.
surchargeAmount	model	float	No	Amount charged by a merchant in exchange for processing a specific transaction
cashbackAmount	model	float	No	Amount requested by the card holder in cash back for an eligible transaction
isEstimatedAmount	model	bool	No	Set this to True when the amount sent in the initial transaction is an estimate. Visa transactions only.
isTaxExempt	model	bool	No	Set this to True if this purchase is exempt from sales tax.

**OriginalTransaction** Parameters:
Name	Parameter	Data Type	Required	Description
pnRef	model	int	No	Unique payment reference number used to identify a single transaction within the system. The payment reference number (PNRef) is assigned by the payment server at the time the transaction is created.
authCode	model	string	No	Original authorization/approval code

**CustomField** Parameters:
Name	Parameter	Data Type	Required	Description
Key	model	int?	No	Gateway key for the custom field
Name	model	string	No	Name of the custom field as set by the merchant
Value	model	string	No	Value (if applicable) to store in the custom field

**SignatureData** Parameters:
Name	Parameter	Data Type	Required	Description
signatureType	model	SignatureTypes	No	Identifies the format of the signature data being provided
data	model	string	No	This parameter holds the data string containing the signature data. If SignatureType = Signature4, the SignatureData will contain a string value of vector coordinates, delimited with a ^ character in the following format: x1,y1^x2,y2^xN,yN^~ Where ^ is the coordinate delimiter, ~ is the ending delimiter, and a comma (,) is the vector delimiter. If there is a pen up event, use the coordinate 0,65535 to signal a break in the line. If SignatureType = Receipt1, you must compress and Base64 encode the image data.

**SignatureTypes** Enum:
signature1
signature2
signature3
signature4
hypercomLegacy
hypercomEnhanced
receipt1

**Level2Data** Parameters:
Name	Parameter	Data Type	Required	Description
poNumber	model	string	No	A merchant-assigned number to identify the customer or the purchase order
transactionDate	model	DateTime	No	The date the transaction occurs. May be today's date, or a past/future date depending on the type of transaction and goods delivered.
merchantZip	model	string	No	Zip code of the merchant's location
taxAmount	model	float?	No	Portion of the transaction representing sales tax.

**Level3Data** Parameters:
Name	Parameter	Data Type	Required	Description
shipFromZip	model	string	No	The source zip code, if goods are shipped
destinationZip	model	string	No	The destination/delivery zip code, if goods are shipped
invoiceNumber	model	string	No	The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice
orderNumber	model	string	No	A merchant-assigned identifier to describe the entire order
lineItems	model	Level3LineItem[]	No	Individual line items for the order/invoice

**Level3LineItem** Parameters:
Name	Parameter	Data Type	Required	Description
productCode	model	string	No	The product code, which may be the same as the UPC
commodityCode	model	string	No	Derived from international tariff codes and describes the items included in the purchase
description	model	string	No	Description/details of the product(s)
upc	model	string	No	UPC code for the product
invoiceNumber	model	string	No	The invoice ID is assigned by the merchant. This identifier can be used to locate a specific transaction or multiple transactions grouped under a single invoice
taxType	model	string	No	Describes the type of tax charged for the transaction
quantity	model	float	No	Number of units purchased
unitPrice	model	decimal	No	Price per unit
discountAmount	model	float	No	Amount of applied discount, if any
totalAmount	model	float	No	Total line item amount
taxAmount	model	float	No	Represents the amount of tax
taxRate	model	float	No	Percentage of the transaction to charge in tax
extendedAmount	model	float	No	Individual item amount that is normally calculated as price multiplied by quantity.
freightAmount	model	float	No	Represents the amount for freight/shipping
dutyAmount	model	float	No	Represents the amount for duty, if applicable
taxIncluded	model	bool	No	Whether or not the total amounts include tax (gross vs net)

**CaptureTypes** Enum:
Name	Value
Credit	1
Debit	2
Check	3
EBT	4

**Transaction** Parameters:
Name	Parameter	Data Type	Required	Description
amountData	model	AmountData	No	Amounts associated with the transaction.
InvoiceData	model	Invoice	No	Tracking/reporting fields used for identifying the transaction and associating it with a customer invoice.
hostCode	model	string	No	Optional host code/transaction id.
authCode	model	string	No	Authorization code.
merchantKey	model	int	No	System-generated unique identifier of the merchant.
resultCode	model	int	No	Gateway code indicating the result of the transaction or error. Allowable Values -100:Transaction NOT Processed; Generic Host Error 0:Approved 1:User Authentication Failed 2:Invalid Transaction 3:Invalid Transaction Type 4:Invalid Amount 5:Invalid Merchant Information 7:Field Format Error 8:Not a Transaction Server 9:Invalid Parameter Stream 10:Too Many Line Items 11:Client Timeout Waiting for Response 12:Decline 13:Referral 14:Transaction Type Not Supported in This Version 19:Original Transaction ID Not Found 20:Customer Reference Number Not Found 22:Invalid ABA Number 23:Invalid Account Number 24:Invalid Expiration Date 25:Transaction Type Not Supported by Host 26:Invalid Reference Number 27:Invalid Receipt Information 28:Invalid Check Holder Name 29:Invalid Check Number 30:Check DL Verification Requires DL State 40:Transaction did not connect 50:Insufficient Funds Available 99:General Error 100:Invalid Transaction Returned from Host 101:Timeout Value too Small or Invalid Time Out Value 102:Processor Not Available 103:Error Reading Response from Host 104:Timeout waiting for Processor Response 105:Credit Error 106:Host Not Available 107:Duplicate Suppression Timeout 108:Void Error 109:Timeout Waiting for Host Response 110:Duplicate Transaction 111:Capture Error 112:Failed AVS Check 113:Cannot Exceed Sales Cap 1000:Generic Host Error 1001:Invalid Login 1002:Insufficient Privilege or Invalid Amount 1003:Invalid Login Blocked 1004:Invalid Login Deactivated 1005:Transaction Type Not Allowed 1006:Unsupported Processor 1007:Invalid Request Message 1008:Invalid Version 1010:Payment Type Not Supported 1011:Error Starting Transaction 1012:Error Finishing Transaction 1013:Error Checking Duplicate 1014:No Records to Settle 1015:No Records to Process
resultText	model	string	No	Short description of the transaction result.
pnRef	model	int	No	Gateway transaction ID/reference number.
message	model	string	No	Text description of the transaction result or error.
message1	model	string	No	Text description of the transaction result or error.
message2	model	string	No	Text description of the transaction result or error.
binData	model	BinData	No	Data returned from a BIN lookup on the card.
validationData	model	CardValidationData	No	AVS/CVV response data.
customFields	model	CustomField[]	No	Any merchant-defined custom fields and their associated values.
token	model	string	No	A token for this transaction.
rawEMVResponse	model	string	No	Raw EMV response from the processor (if any).

**AmountData** Parameters:
Name	Parameter	Data Type	Required	Description
AuthorizedAmount	form	decimal?	No	The amount authorized at the processor for the transaction. When partial authorization is disabled/not-supported this amount will be the same as the totalAmount. If partial authorization is allowed and a transaction receives a partial approval, this will be the amount authorized.
TotalAmount	form	decimal?	No	The total amount of the transaction. This may be greater than the authorized amount if partial authorizations are enabled.
RemainingBalance	form	decimal?	No	For pre-paid, gift, and EBT cards this will show the balance remaining on the card when the processor returns the necessary balance data.

**BinData** Parameters:
Name	Parameter	Data Type	Required	Description
Bin	form	long	No	The BIN/first 6 digits of the card
CardBrand	form	string	No	The card brand (VISA, MasterCard, American Express, etc
IssuingOrg	form	string	No	The organization/bank that issued the card
CardType	form	string	No	Typically debit or credit
CardCategory	form	string	No	The category indicating special types of card such as corporate, purchasing, and prepaid
IssuingCountry	form	string	No	The country where the card was issued
IssuingCountryCodeA2	form	string	No	The A2 country code
IssuingCountryCodeA3	form	string	No	The A3 country code
IssuingCountryNumber	form	int?	No	The issuing country number
IssuingPhone	form	string	No	Phone number, if available, of the issuing organization
IssuingWebsite	form	string	No	Web site, if available, of the issuing organization
PanLength	form	int?	No	The length of credit card number
IssuedEntity	form	string	No	Defines if the BIN is PERSONAL or COMMERCIAL
IsRegulated	form	bool	No	Indicates if the card is regulated
IsCommercial	form	bool	No	True if the IssuedEntity is equal to 'COMMERCIAL'

**CardValidationData** Parameters:
Name	Parameter	Data Type	Required	Description
avsResponse	model	string	No	Address verification response code
cvResponse	model	string	No	Card verification response code
avsResponseText	model	string	No	Text representation of the AVS response
cvResultText	model	string	No	Text representation of the CVV response
streetMatchText	model	string	No	Additional detail on the AVS street match
zipMatchText	model	string	No	Additional detail on the AVS zip match

To override the Content-type in your clients, use the HTTP Accept Header, append the .jsv suffix or ?format=jsv

HTTP + JSV

The following are sample HTTP requests and responses. The placeholders shown need to be replaced with actual values.

POST /transactions HTTP/1.1 
Host: syntch.simpay.net 
Accept: text/jsv
Content-Type: text/jsv
Content-Length: length

{
	TransactionType: Authorization,
	CardData: 
	{
		CardNumber: String,
		ExpirationDate: String,
		Cvv: 0,
		NameOnCard: String,
		Pin: String,
		KeySerialNumber: String,
		Token: String,
		EmvData: String,
		TrackData: String,
		EncryptedTrack1Data: String,
		EncryptedTrack2Data: String,
		EncryptedTrack3Data: String,
		IIN: String,
		ARQC: String,
		EntryMode: unknown,
		CvPresence: none,
		Street: String,
		ZipCode: String,
		Phone: String,
		Email: String
	},
	CheckData: 
	{
		NameOnCheck: String,
		RoutingNumber: String,
		AccountNumber: String,
		CheckNumber: String,
		MICR: String,
		DriversLicense: String,
		State: String,
		SSN: String,
		DateOfBirth: String,
		CheckType: Personal,
		AccountType: Checking,
		RawMICR: String,
		BranchCity: String,
		EmailAddress: String,
		TelephoneNumber: String,
		Token: String,
		Address: 
		{
			StreetAddress1: String,
			StreetAddress2: String,
			StreetAddress3: String,
			City: String,
			StateOrProvinceCode: String,
			PostalCode: String,
			CountryCode: String
		},
		SECCode: String
	},
	DeviceData: 
	{
		SdkVersion: String,
		SerialNumber: String,
		BatteryLevel: 0,
		IsEncrypted: False,
		EncryptionType: String
	},
	Fsa: 
	{
		partialAuthSupport: False,
		qhpAmount: 0,
		rxAmount: 0,
		visionAmount: 0,
		dentalAmount: 0,
		clinicalAmount: 0,
		copayAmount: 0,
		transitAmount: 0
	},
	SoftDescriptor: 
	{
		AltMerchantName: String,
		AltMerchantAddress: String,
		AltMerchantCity: String,
		AltMerchantState: String,
		AltMerchantZip: String
	},
	ForceDuplicate: False,
	Register: String,
	InvoiceData: 
	{
		customerId: String,
		totalAmount: 0,
		tipAmount: 0,
		taxAmount: 0,
		shippingAmount: 0,
		convenienceAmount: 0,
		convenienceAmountPercentage: 0,
		surchargeAmount: 0,
		cashbackAmount: 0,
		isEstimatedAmount: False,
		isTaxExempt: False
	},
	OriginalTransaction: 
	{
		pnRef: 0,
		authCode: String
	},
	CustomFields: 
	[
		{
			Key: 0,
			Name: String,
			Value: String
		}
	],
	SignatureData: 
	{
		signatureType: signature1,
		data: String
	},
	Level2Data: 
	{
		poNumber: String,
		transactionDate: 0001-01-01,
		merchantZip: String,
		taxAmount: 0
	},
	Level3Data: 
	{
		shipFromZip: String,
		destinationZip: String,
		invoiceNumber: String,
		orderNumber: String,
		lineItems: 
		[
			{
				productCode: String,
				commodityCode: String,
				description: String,
				upc: String,
				invoiceNumber: String,
				taxType: String,
				quantity: 0,
				unitPrice: 0,
				discountAmount: 0,
				totalAmount: 0,
				taxAmount: 0,
				taxRate: 0,
				extendedAmount: 0,
				freightAmount: 0,
				dutyAmount: 0,
				taxIncluded: False
			}
		]
	},
	AuthCode: String,
	UseInterchangeDefaults: False,
	CaptureType: Credit
}

HTTP/1.1 200 OK
Content-Type: text/jsv
Content-Length: length

{
	amountData: 
	{
		AuthorizedAmount: 0,
		TotalAmount: 0,
		RemainingBalance: 0
	},
	InvoiceData: 
	{
		customerId: String,
		totalAmount: 0,
		tipAmount: 0,
		taxAmount: 0,
		shippingAmount: 0,
		convenienceAmount: 0,
		convenienceAmountPercentage: 0,
		surchargeAmount: 0,
		cashbackAmount: 0,
		isEstimatedAmount: False,
		isTaxExempt: False
	},
	hostCode: String,
	authCode: String,
	merchantKey: 0,
	resultCode: 0,
	resultText: String,
	pnRef: 0,
	message: String,
	message1: String,
	message2: String,
	binData: 
	{
		Bin: 0,
		CardBrand: String,
		IssuingOrg: String,
		CardType: String,
		CardCategory: String,
		IssuingCountry: String,
		IssuingCountryCodeA2: String,
		IssuingCountryCodeA3: String,
		IssuingCountryNumber: 0,
		IssuingPhone: String,
		IssuingWebsite: String,
		PanLength: 0,
		IssuedEntity: String,
		IsRegulated: False,
		IsCommercial: False
	},
	validationData: 
	{
		avsResponse: String,
		cvResponse: String,
		avsResponseText: String,
		cvResultText: String,
		streetMatchText: String,
		zipMatchText: String
	},
	customFields: 
	[
		{
			Key: 0,
			Name: String,
			Value: String
		}
	],
	token: String,
	rawEMVResponse: String
}

Syntch Gateway API

CreateTransactionRequest

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

Allowable Values

HTTP + JSV