PayTrace API Name Value Pairs Data Definitions

The PayTrace API accepts request strings that are formatted in name / value pairs. Also, the PayTrace API returns response strings that are formatted in name / value pairs.

PayTrace Request Name / Value Pair Data Definitions

Name Description Format Length
ADDTAX Any tax generated from freight or other services associated with the transaction. Numeric 1-12
ADDTAXIND A flag used to indicate where additional tax was included in this transaction. Set to Y if additional tax was included and N if no additional tax was applied. cell-alphabetic 1
ADDTAXINDLI Descriptor used to describe additional tax that is applied to the transaction amount in reference to this specific line item. alpha-numeric 1-4
ADDTAXLI Additional tax amount applied to the transaction applicable to this line item record. numeric 1-12
ADDTAXRATE Rate at which additional tax was assessed. numeric 1-4
ADDTAXRATELI Rate at which additional tax was calculated in reference to this specific line item record. numeric 1-4
AMOUNT Dollar amount of the transaction. Must be a positive number up to two decimal places. numeric 1-12
AMOUNTLI Total amount included in the transaction amount generated from this line item record. numeric 1-12
APPROVAL Approval code for the forced sale is only required and used if TranxType is set to 'Force'. alpha-numeric 6
APPROVEURL Optional URL that the customer will have the option of selecting if their transaction is approved via the PayTrace API Secure Checkout alpha-numeric 1-255
BADDRESS Address that the credit card statement is delivered. alpha-numeric 1-50
BADDRESS2 Second line of the address the credit card statement is delivered. alpha-numeric 1-50
BATCHNUMBER Number of the batch of transactions you wish to export via an ExportBatch request numeric 1-3
BCITY City that the credit card statement is delivered. alphabetic 1-50
BCOUNTRY Country code where the billing address is located alphabetic 2
BNAME Name that appears of the credit card alphabetic 1-50
BSTATE State that the credit card statement is delivered alphabetic 2
BZIP Zip code that the credit card statement is delivered numeric 5 or 9
CASHADVANCE When set to Y, this attribute causes a Sale transaction to be processed as a cash advance where cash is given to the customer as opposed to a product or service. Please note that Cash Advances may only be processed on accounts that are set up on the TSYS/Vital network and are configured to process Cash Advances. Also, only swiped/card present Sales may include the CashAdvance parameter alphabetic 1
CC Customer's credit card number must be a valid credit card number that your PayTrace account is set up to accept numeric 15, 16 or 19
CCODE Commodity code that generally applies to each product included in the order. Commodity codes are generally assigned by your merchant service provider alpha-numeric 1-4
CCODELI The complete commodity code unique to the product referenced in this specific line item record. Commodity codes are generally assigned by your merchant service provider alpha-numeric 1-12
CHECKID A unique identifier for each transaction in the PayTrace system. This value is returned in the CHECKIDENTIFIER parameter of an API response and will consequently be included in requests to email receipts, manage checks, etc numeric 1-8
CHECKTYPE The transaction type is the type of transaction you wish to process if the METHOD is set to ProcessCheck. CHECKTYPE must be set to one of the following: Sale, Hold, Refund, Fund, or Void. alphabetic 4 or 6
CSC CSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of Amex cards numeric 3-4
CUSTID Unique identifier for a customer profile. Each customer must have their own unique ID alpha-numeric 1-25
CUSTOMDBA Optional value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks alpha-numeric 1-25
CUSTOMERTAXID Customer’s tax identifier used for tax reporting purposes alpha-numeric 1-13
CUSTPSWD Password that customer uses to log into customer profile in shopping cart. Only required if you are using the PayTrace shopping cart. alpha-numeric 7-25
CUSTRECEIPT Defaulted to N, the customer receipt must be set to Y if a receipt should be emailed to the customer each time the recurring transaction is processed alphabetic 1
CUSTREF Customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. The customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement alpha-numeric 1-17
DCIND Flag used to determine whether the line item amount was a debit or a credit to the customer. Generally always a debit or a factor that increased the transaction amount. Possible values are D (net is a debit) and C (net is a credit) alphabetic 1
DDA Checking account number for processing check transactions or managing customer profiles numeric 1-20
DECLINEURL Optional URL that the customer will have the option of selecting if their transaction is declined via the PayTrace API Secure Checkout alpha-numeric 1-255
DESCRIPTION Optional text describing the transaction, products, customers, or other attributes of the transaction alpha-numeric 1-255
DISCOUNT Discount value should represent the amount discounted from the original transaction amount numeric 1-12
DISCOUNTIND Flag used to indicate whether discount was applied to the transaction amount in reference to this specific line item record alphabetic 1
DISCOUNTLI Discount amount applied to the transaction amount in reference to this line item record numeric 1-12
DISCOUNTRATE Rate at which discount was applied to the transaction in reference to this specific line item alpha-numeric 1-5
DUTY Duty should represent any costs associated with shipping through a country’s customs numeric 1-12
EDATE End date is used for export functions to indicate when to end searching for transactions to export. Must be a valid date formatted as MM/DD/YYYY Date 10
EMAIL Customer's email address where the sales receipt may be sent alpha-numeric 1-50
ENABLEPARTIALAUTH Flag that must be set to ‘Y’ in order to support partial authorization and balance amounts in transaction responses alphabetic 1
EXPMNTH Expiration month must be the two-digit month of the credit cards expiration date numeric 2
EXPYR Expiration year must be the two digit year of the credit cards expiration date numeric 2
FAX Customer's fax number (i.e. (555)555-5555, 555-555-5555, or 5555555555) alpha-numeric 10, 12 or 13
FORCEADDRESS Setting in the PayTrace API Secure Checkout that may be set to ‘Y’ if the customer’s complete billing address is required alphabetic 1
FORCECSC Setting in the PayTrace API Secure Checkout that may be set to ‘Y’ if the customer’s CSC is required alphabetic 1
FORCEEMAIL Setting in the PayTrace API Secure Checkout that may be set to ‘Y’ if the customer’s email address is required alphabetic 1
FREIGHT Freight value should represent the portion of the transaction amount that was generated from shipping costs numeric 1-12
FREQUENCY The billing cycle of the recurring transaction must be 1 for annually, 8 for semi-annually, A for trimesterly, 2 for quarterly, 9 for bi-monthly, , 3 for monthly, 4 for bi-weekly, 7 for 1st and 15th, 5 for weekly, or 6 for daily alpha-numeric 1
IDEXP Only used when processing Cash Advances. This required field is the expiration date of the card holder’s photo ID. MM/DD/YYYY Date 10
IMAGEDATA The IMAGEDATA value being submitted. Images need to be Base64 encoded. alpha-numeric
IMAGETYPE Signature image file type. File type should be JPG, GIF, TIF, PNG, BMP . alphabetic 5
INVOICE Invoice is the identifier for this transaction in your accounting or inventory management system alpha-numeric 1-50
LAST4 Only used when processing Cash Advances. This required field is the last 4 digits of the card number as it appears on the face of the card numeric 4
MEASURE Unit of measure applied to the product and its quantity. Level 3 Unit of Measurement Codes alpha-numeric 1-12
MERCHANTTAXID Merchant’s tax identifier used for tax reporting purposes alpha-numeric 20
METHOD Function that you are requesting PayTrace perform. alphabetic 1-50
NETGROSSIND Flag used to indicate whether the line item amount is net or gross to specify whether the line item amount includes tax. Possible values are Y (includes tax) and N (does not include tax) alphabetic 1
NEWCUSTID Unique identifier for a customer profile that may be sent with request to update a customer profile. This value will be the new customer ID alpha-numeric 1-25
NEWPSWD Your new PayTrace password when updating user password through the UpdatePassword method alpha-numeric 7-50
NEWPSWD2 Confirmation of you new PayTrace password when updating user password through the UpdatePassword method alpha-numeric 7-50
NEXT Next date the updated recurring transaction should be processed Date 10
NTAX Portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax numeric 1-12
ORDERID Developer’s identifier for an order that is placed through the PayTrace API Secure Checkout alpha-numeric 1-50
ORIGINALID Unique identifier of the request from your system that will be returned in the response if RETURNID is set to Y alpha-numeric 1-50
PHONE Customer's phone number (i.e. (555)555-5555, 555-555-5555, or 5555555555) alpha-numeric 10, 12, 13
PHOTOID Only used when processing Cash Advances. This required field may be the card holder’s drivers license number or other form of photo ID alpha-numeric 1-20
POSTURL Optional URL with any request where the response/error generated from the request may be sent in addition to the comptuer that originated the request alpha-numeric 1-255
PRODUCTID Your unique identifier for the product alpha-numeric 1-12
PSWD Your PayTrace password is required to authenticate your request* alpha-numeric* 7-20
QUANTITY Item count of the product in this order numeric 1-12
RECURID The ID of the Recurring Transaction that is being updated numeric 1-50
RECURTYPE Default value is C which represents credit card number. Alternative is A which represents an ACH/check transaction alphabetic 1
RETURNBIN If set to Y, card numbers from ExportTranx and ExportCustomers requests will include the first 6 and last 4 digits of the card number alphabetic 1
RETURNCLR If set to Y, card level results will be returned w/ the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks. alphabetic 1
RETURNID If set to Y will return the value of ORIGINALID in the response alphabetic 1
SADDRESS Address where the product is delivered alpha-numeric 1-50
SADDRESS2 Second line of the address where the product is delivered alpha-numeric 1-50
SCITY City where the product is delivered alphabetic 1-50
SCOUNTRY County where the product is delivered alphabetic 2
SCOUNTY County where the product is delivered alphabetic 1-50
SDATE Start date is used for export functions to indicate when to start searching for transactions to export. Must be a valid date formatted as MM/DD/YYYY Date 10
SEARCHTEXT Text that will be searched to narrow down transaction and check results for ExportTranx and ExportCheck requests alpha-numeric 1-255
SHIPPERS String of shipping service providers you would like shipping quotes from. String may contain USPS, FEDEX, or UPS in any order or combination alphabetic 3-19
SNAME Name of the person where the product is delivered alphabetic 1-50
SOURCESTATE State that the package will be sent from alphabetic 2
SOURCEZIP Zip code that the package will be sent from numeric 5,9
SSTATE State where the product is delivered alphabetic 2
START Date the recurring transaction should be processed for the first time Date 10
STRFWDDATE Optional future date when the transaction should be authorized and settled. Only applicable if the TranxType is STR/FWD Date 10
SWIPE The value of the magnetic stripe on the back of the credit card as recorded from a magnetic card reader. PayTrace strongly recommends that software providers avoid storing the swiped value. Because the first value in the magnetic stripe is a (%) symbol, we strongly recommend URL encoding the SWIPE value before posting it to PayTrace. Please note that PayTrace supports encrypted card readers. However, most encrypted card readers include pipe (|) symbols in the magstripe value. It is imperative that you replace these pipe symbols with “***” to ensure that the API is able to parse your request alpha-numeric 255+
SZIP Zip code where the product is delivered numeric 5,9
TAX Portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax exempt numeric 1-12
TERMS Must be to 'Y' in order to process any methods through the PayTrace API. Setting this variable to 'Y' indicates that you agree to the PayTrace terms and conditions found at https://paytrace.com/terms.html alphabetic 1
TEST The TEST attribute may be used with any of the transaction types (TranxType) of the ProcessTranx method. The value of the TEST attribute may only be a “Y”. Transactions processed with a TEST value of “Y” will be processed as test transactions with standardized test responses. Test transactions will not place a hold on the customer’s credit card alphabetic 1
TOTALCOUNT The total number of times the recurring transaction should be processed. Use 999 if the recurring transaction should be processed indefinitely numeric 1-3
TR Transit routing number for processing check transactions or managing customer profiles numeric 9
TRANXID A unique identifier for each transaction in the PayTrace system. This value is returned in the TRANSACTIONID parameter of an API response and will consequently be included in requests to email receipts, void transactions, add level 3 data, etc numeric 1-9
TRANXTYPE The transaction type is the type of transaction you wish to process if the METHOD is set to ProcessTranx. TRANXTYPE must be set to one of the following: Sale, Authorization, Str/Fwd, Refund, Void, Capture,Force and Deleteauthkey (Secure Checkout Only) alphabetic 4,5,6,7,13
UN Your PayTrace user name is required to authenticate your request alpha-numeric 7-50
UNITCOST Product amount per quantity numeric 1-12
USER User is the user name of the PayTrace user who created or processed the customer or transaction you are trying to export. This variable is a search criterion for the export methods alpha-numeric 1-50
WEIGHT Weight of the package that is being shipped. Weight must be provided in pounds and my have up to two decimals. Weight must be less than 70 pounds numeric 1-5
“……………………………” Discretionary Data elements that are configured in PayTrace’s Virtual Terminal may be passed through the API. All Discretionary Data elements are optional in the API, our integrated solutions may make them required. Discretionary Data elements should be passed w/ the Title in the name portion of the pair and the value to the right of the tilde. For example, a Discretionary Data element titled “Hair Color” could be passed as “Hair Color~Red|” Please note that Discretionary Data titles and values should be URL encoded. Also, multiple select Discretionary Data values should be comma delimited alpha-numeric 1-99

PayTrace Response Name / Value Pair Data Definitions

Name Description Format Length
ACHCODE Flag that is returned for checks processed through a real-time check processor. 0/zero indicates that the check was accepted numeric 6
ACHMSG Message returned from real-time check processor alpha-numeric 1-255
APPCODE Approval code is generated by credit card issuer and returned when a successful call to ProcessTranx is requested alpha-numeric 6
APPMSG Approval message is the textual response from the credit card issuer that is returned when a successful call to ProcessTranx is requested alpha-numeric 1-255
AUTHKEY Authorization key is returned with a successful request to validate an order through the PayTrace API Secure Checkout alpha-numeric 1-255
AVSRESPONSE The address verification system response is generated by the credit card issuer when a successful call to ProcessTranx is requested. AVS compares the billing address and billing zip code provided with the ProcessTranx request to the address where the customer's credit card statement is delivered. See How To Determine if a Transaction has been Approved page for possible AVS responses alpha-numeric 1-255
BALANCEAMOUNT Remaining balance on a prepaid or debit card. This value will only be returned if ENABLEPARTIALAUTH is set to Y alpha-numeric 1-50
BATCHNUM Batch number is returned with a successful request to settle transactions. This value is the sequential number assigned to the batch that was initiated numeric 3
CHECKIDENTIFIER ID assigned by PayTrace to each check at the time the check is processed. CHECKIDENTIFIER is returned with a successful call to ProcessCheck alpha-numeric 1-16
CSCRESPONSE The card security code response is generated by the credit card issuer when a successful call to the ProcessTranx is requested. The CSC provided with the ProcessTranx request. is compared to the CSC assigned to the credit card. See Appendix B for possible AVS responses alpha-numeric 1-255
CUSTOMERID ID assigned by PayTrace to each customer at the time the customer profile is created. CustomerID is returned with a successful call to CreateCustomer or UpdateCustomer alpha-numeric 1-255
CUSTOMERRECORD Formatted customer record returned when a successful call to ExportCustomers method is requested alpha-numeric ……
ERROR PayTrace validates each name / value pair it receives. If any errors or inconsistencies in this data or the request, PayTrace will return an error. Each request may return multiple errors alpha-numeric 1-255
IP IP address of the computer that originally requested the customer profile or transaction be created or processed formatted as a standard IP address (I.e. 111.111.111.111). IP address is returned with a successful call to ExportCustomers or ExportTranx alpha-numeric 7-15
LASTCHECK Date of the last check transaction processed in MM/DD/YYYY HH:MM:SS AM/PM format Date 1-22
LASTTRANX Date of the last credit card transaction processed in MM/DD/YYYY HH:MM:SS AM/PM format Date 1-22
NETAMOUNT Net amount is returned with a successful request to settle transactions. This value is the net amount (sales minus refunds) of the batch that was initiated numeric 1-15
PARTIALAMOUNT Authorized transaction amount in the event that a transaction is partially approved. This value will only be returned if ENABLEPARTIALAUTH is set to Y alpha-numeric 1-50
REFUNDAMOUNT Total amount of refunds included in a batch. This value is returned in ExportBatches requests numeric 1-12
REFUNDCOUNT Total number of refunds included in a batch. This value is returned in ExportBatches requests numeric 1-6
RESPONSE Sentence or two that confirms the method that was requested alpha-numeric 1-255
SALESAMOUNT Total amount of sales included in a batch. This value is returned in ExportBatches requests numeric 1-12
SALESCOUNT Total number of sales included in a batch. This value is returned in ExportBatches requests numeric 1-6
SETTLED Date and Time returned with the TransactionRECORD formatted a general date (i.e. MM/DD/YYYY HH:MM:SS). Settled represents the date and time the transaction was settled/batched alpha-numeric 19
SHIPPINGCOMPANY The name of the shipping company that quoted the price (i.e. UPS, USPS, FEDEX) alphabetic 3-5
SHIPPINGMETHOD The method of shipment that was quoted (i.e. Next Day, Priority, Ground, etc.) alpha-numeric 1-255
SHIPPINGRATE Cost to use the specified shipping service provider and method formatted in U.S. dollars as provided by the shipping service provider numeric 1-5
SHIPPINGRECORD Shipping records are returned when a successful call to CalculateShipping is requested alpha-numeric …..
STATUS Status is returned with each transaction in the transaction list that is returned from a successful call to the ExportTranx method. If the status contains the letters "GB" or "Settled" then the transaction has been settled, and the batch number will be appended to the status. If the is "Y" then the transaction will be settled that evening. If the status is "N" then the transaction was voided or declined alpha-numeric 1-10
TRANSACTIONID ID assigned by PayTrace to each transaction at the time the transaction is processed. TransactionID is returned with a successful call to ProcessTranx alpha-numeric 1-16
TRANSACTIONRECORD Formatted transaction record returned when a successful call to ExportTranx method is requested alpha-numeric 1-25
TRANXCOUNT Transaction count is returned with a successful request to settle transactions. This value is the total number of transactions that were included in the batch numeric 1-3
VISAREFUNDAMOUNT Total sum of Visa refunds that were settled in the exported batch. Similar values will be returned for all applicable card types, i.e. MasterCardRefundAmount, AmexRefundAmount, DiscoverRefundCount, etc numeric 1-15
VISAREFUNDCOUNT Total number of Visa refunds that were settled in the exported batch. Similar values will be returned for all applicable card types, i.e. MasterCardRefundCount, AmexRefundCount, DiscoverRefundCount, etc… numeric 1-3
VISASALESAMOUNT Total sum of Visa sales that were settled in the exported batch. Similar values will be returned for all applicable card types, i.e. MasterCardSalesAmount, AmexSalesAmount, DiscoverSalesCount, etc… numeric 1-15
VISASALESCOUNT Total number of Visa sales that were settled in the exported batch. Similar values will be returned for all applicable card types, i.e. MasterCardSalesCount, AmexSalesCount, DiscoverSalesCount, etc… numeric 1-3
WHEN Date and Time returned with the TransactionRECORD and the CustomerRECORD formatted a general date (i.e. MM/DD/YYYY HH:MM:SS). When represents the date and time the transaction was first processed or the customer profile was created alpha-numeric 19