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 |
| 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 |
page revision: 33, last edited: 21 Jul 2016 19:46
