B2B API
ProductsB2B API Integration Guide
Environment | Base URL |
---|---|
Sandbox | https://api.sandbox.paytrace.com/ |
Production | https://api.paytrace.com/ |
API Version
The current version of the Json API is V3.Getting Started
Introduction
The B2B API is a powerful solution that enables any software developer to integrate PayTrace services into their proprietary software. Developers can use the B2B API to add payment processing in real time to any site or application by seamlessly integrating HTTPS Post requests. The API also goes beyond payment processing, offering the ability to store customer and transaction profiles, effortlessly generate email receipts, process recurring payments, automate accounts receivable, and more.
Sign up for a free sandbox account and Integrator ID
Contact us to request sandbox credentials that can be used for testing in a test environment. Once your sandbox account is approved, you will receive your integrator_id and sandbox credentials within 5 business days.
Once you have your sandbox credentials and integrator ID, you can use this Integration Guide and the API Specification linked below to build your integration.
Best Practices
Do not use the same API username and password from your Sandbox to Production accounts and vice versa.
Understanding Integrator IDs
Integrator IDs are not specific to any individual account but are associated with the integration itself. They help PayTrace identify which merchant accounts are using a particular integration. For instance, if an ISV partner builds a WooCommerce plugin for PayTrace, every merchant using this plugin will share the ISV partner’s integrator_id. This ID serves as a reference, informing PayTrace about the merchants utilizing the specific integration
Sandbox vs. Production Reminder
When development and testing are complete, you are ready to go live with your production account. Don’t forget to do the following:
- Switch sandbox endpoints to the production endpoints.
- Switch API user credentials from Sandbox to Production credentials.
If you do not have a production environment please contact us.
JSON API
This JSON API is designed as a REST API (Representational State Transfer). It has predictable responses and dedicated URLs for each method. This API utilizes OAuth 2.0 for authentication and authorization. It has HTTP verbs and HTTP response codes to provide the integrators and developers the fastest and most secure methods to integrate with our platform. JSON will be returned in all responses from the API, including errors with PayTrace defined error codes.
API Endpoints
All production API requests are made to https://api.paytrace.com. All sandbox API requests are made to https://api.sandbox.paytrace.com. All requests are served over HTTPS using TLS 1.2.
PayTrace Help Documentation
Explore the PayTrace Help Documentation for essential tools and knowledge, empowering you to maximize the effectiveness of the PayTrace Virtual Terminal. Unlock valuable insights and resources to enhance your user experience. Dive in to discover how to make the most of PayTrace’s features and capabilities.
Data Wrapped Responses
All responses are wrapped in a data-wrapper. This means for any of the documented response schemas, you will find the schema nested under the data property of the response itself.
ExampleJSON
In this case, the content of response.data would match the response schema defined in the API specification. If using language level schemas, this may be an important consideration. In all cases, the status_code property should match the HTTP status code sent.
Schemas
All schemas (and endpoints) are available and conform to the OpenAPI 3 spec. You can view the OpenAPI schema in your browser or download it from the Resources page. This endpoint does not require authentication, and can be integrated programmatically into your custom solutions.
Request Headers
Please note that the following Request Header settings remain consistent through all API Methods except Authentication Token request.
Header | Value |
---|---|
Authorization | The Bearer JWT received from the Authorization step. |
Content-Type | application/json |
Cache-Control | no-cache |
Response Codes
The response_code plays an important role to determine if a requested API method is successful or not. It is highly recommended to check its value if writing a custom implementation (if checking manually, response_message or other API return data will often have a human readable description of what happened, however the message value may change over time, while the code will not). A sample of a data-wrapped response containing a response_code is as follows:
ExampleJSON
The response_code will contain one of the following codes with an associated response_message:
Code | Message | Reason |
---|---|---|
1 | One or more errors occurred. | An internal exception that was not handled has occurred. |
100 | Password updated. | |
101 | Transaction approved. | |
102 | Transaction NOT approved. | |
103 | Transaction approved. However, it was voided because of address and/or CSC mismatch. | Returned when a request to process a sale or authorization transaction generates an approved transaction whose AVS and or CSC response falls below the auto-void specification in your security settings. |
106 | Transaction refunded. | |
107 | Transaction NOT refunded. | |
108 | TEST Transaction refunded, HOWEVER NO FUNDS WILL BE REFUNDED. | Returned when a request to process a TEST refund transaction generates a completed transaction. |
109 | Transaction voided. | |
110 | Transaction NOT voided. | |
112 | Transaction captured. | |
113 | Transaction NOT captured. | |
120 | Check processed. | |
122 | Check refunded. | |
124 | Check managed. | Returned when a request to manage a check for void or fund is successfully processed. |
125 | Check NOT processed. | Returned when a request to process a check is not successfully processed. The response is generally only returned when the check is processed through a real-time processor. |
149 | Receipt for a transaction ID was emailed. | |
150 | Recurring transaction created. | |
151 | Recurring transaction updated. | |
152 | Recurring transaction deleted. | |
155 | This customer’s most recent recurring transaction took place on DD/MM/YYYY. | Returned when a request to export a customer’s recurring payment is successfully processed. |
160 | Customer created. | |
161 | Customer updated. | |
162 | Customer deleted. | |
165 | Transaction approved & customer created. | |
167 | Transaction approved & customer NOT created. | |
170 | Visa level 3 added to transaction ID. | Returned when a request to add level 3 data is successful for a Visa transaction. |
171 | MasterCard level 3 added to transaction ID. | Returned when a request to add level 3 data is successful for a MasterCard transaction. |
175 | The batch was successfully initiated, and the batch report will be sent to: email@address.com, email2@address.com in just a few moments. | Returned when a request to settle transactions is successful. The response will also include the Batch Number, Transaction Count, and Net Amount. |
180 | Transaction amount adjusted. |
AVS and CSC Response
An approved transaction does not guarantee that the customer who provided the billing information is truly the card holder. Preventing fraud is paramount in the payment processing industry for multiple reasons, primarily minimizing merchant exposure to chargebacks and strengthening customer confidence in electronic payments.
Depending on your style of business and potential for chargeback exposure, PayTrace encourages you to validate each transaction’s fraud indicators, in addition to approval response, to verify if a transaction is legitimate and should be settled.
AVS (Address Verification System) and CSC (Card Security Code) Responses are excellent indicators to verify that your customer is the true card holder. Therefore, it is recommended to validate the AVS and CSC Responses against the following potential responses to determine if the appropriate fraud prevention features have been met before settling a transaction.
Here are the possible values for avs_response and csc_response parameters.
AVS Response
- Full Exact Match
- Address Match Only
- Zip Match Only
- No Match
- Address Unavailable
- Non-US Issuer does not participate
- Issuer System Unavailable
- Not a Mail/Phone Order
- Service Not Supported
CSC Response
- Match
- No Match
- Not Processed
- Not Present
- Issuer Does Not Support CSC
If you are processing an American Express transaction (15 digit card number starts with 37) and you provide a CSC value, the CSC Response will be empty. Note that American Express does not approve transactions whose CSC value is invalid.
Visa, MasterCard, Discover, and Diner’s Club will return a CSC Response.
JCB does not support CSC.
Error Responses
The B2B API will return a standard HTTP status code and JSON error response when any error occurs. In general, HTTP codes in the 2XX range indicate success, codes in the 4XX range indicate an error that failed with the provided information (e.g., a required parameter was omitted, invalid value of request parameters, a charge failed, etc.), or the card/transaction is declined. Codes in the 5XX range indicate an error with the internal servers. An error response will have a consistent format, and the errors are always an array of 1 or more errors. A sample response with an error format:ExampleJSON
The detail is a human readable message similar to response_message on a success. The type is a grouping of errors - in this case, a basic validation error. The code is an immutable value that can be implemented against. For some error types, in particular VALIDATION, the field will be a property path (similar to an XPath) that indicates what value property was wrong. Depending on the type of error, error_id may be filled out - this will often correspond to the response_code that indicates an error on the prior section.
Error Codes
The potential error object error_id values are as follows:
Error Code | Error Detail | Reason |
---|---|---|
30 | Customer ID, xxxxx, was not found or is incomplete. | A customer ID is required when processing a request that references a stored customer. |
35 | Please provide a valid Credit Card Number. | All card numbers sent to PayTrace must pass the Mod 10 check. |
36 | Customer ID, xxxxxx, does not have a valid billing address. | If your account requires a billing address to process a transaction, PayTrace will check the referenced customer’s profile. |
37 | Customer ID, xxxxxx, does not have a valid billing ZIP. | If your account requires a billing ZIP to process a transaction, PayTrace will check the referenced customer’s profile. |
39 | Your PayTrace account is not set up to accept this card type. | All card types are validated before being saved or used. By default, all accounts are able to process Visa, MasterCard, and Diner’s Club cards. Accounts must be set up to accept American Express, Discover, and JCB cards in order for PayTrace to accept them. |
40 | An error occurred during the decryption process. | PayTrace supports encrypted card readers. This error is returned if an error occurs during the decryption process. |
43 | Please provide a valid Expiration Month. | All transactions and customer profiles must have a 2 digit expiration month. |
44 | Please provide a valid Expiration Year. | All transactions and customer profiles must have a 2 digit expiration year. |
45 | Please provide a valid Checking Account Number. | Required if creating a customer without a card number or processing a check transaction. |
46 | Please provide a valid Transit Routing Number. | Required if creating a customer without a card number or processing a check transaction. |
47 | Please provide an Amount that is less than your Sale Ceiling Amount. | All sales, authorizations, and forced sales must have a valid numeric amount that is less than your sale ceiling amount. |
48 | Please provide an Amount that is less than your Refund Ceiling Amount. | All refunds must have a valid numeric amount that is less than your refund ceiling amount. |
51 | Please provide a valid Amount. | All transactions must have a valid numeric amount. |
53 | Capture Amount can not exceed 30% of the original authorized amount. | All transactions must have a valid numeric amount. |
54 | Cash Advances may only be processed as Sales. | Cash Advances must be processed as Sale transaction types. It only applies if ProcessTranx request includes CASHADVANCE~Y| parameter. |
55 | Cash Advances may only be processed through accounts set up in the TSYS/Vital network. | Cash Advances may only be processed if your merchant account is set up on the TSYS network. It only applies if ProcessTranx request includes CASHADVANCE~Y| parameter. |
56 | Cash Advances may not be processed to stored customers. | Cash advance transactions must be processed as face to face transactions. |
57 | Your PayTrace account is not set up to process Cash Advances. | In order to process Cash Advances, your PayTrace account must be configured to accept this type of payment. |
58 | Please provide a valid Transaction ID. | Void, capture, add level 3 data, and email receipt requests require a transaction ID that references a transaction in PayTrace’s system. |
59 | Please provide a valid Check ID. | Manage Check and email receipt requests require a check ID that references a check-in PayTrace’s system. |
61 | The Customer ID that you provided was not found in the PayTrace records. | If a transaction is to be referenced to a stored customer profile, a valid customer ID must be provided. |
62 | Please provide a valid Photo ID. | Cash Advance requests require a photo ID to be provided. |
63 | Please provide a valid ID Expiration. | Cash Advance requests require an ID expiration date to be provided. |
64 | Please provide a valid Last 4 of Card. | Cash Advance requests require the last 4 digits of the card number to be provided. |
65 | Cash Advances may only be processed on Visa, MasterCard, and Discover cards. | Cash Advance transactions are only permitted on Visa, MasterCard, and Discover cards. |
80 | The Check ID that you provided was not found in the PayTrace records. It may already be voided or settled. | Only pending and held checks may be managed. |
81 | The Transaction ID that you provided was not found in the PayTrace records. It may be a previously voided transaction or an unsettled transaction. | Only settled sales transactions may be refunded with a transaction ID. |
82 | Please provide a valid Batch Number. | If a batch number is present in an ExportBatch request, it must be a numeric value between 1 and 999. |
83 | This is not an approved transaction so it can not be captured. | Only approved authorizations may be captured. |
84 | This transaction’s approval code has expired as it was obtained more than 20 days ago. | Transactions must be captured within 20 days of authorization. |
85 | The Transaction ID that you provided was not found in the PayTrace records. It may already be captured or settled. | Only approved authorizations that are currently not pending settlement may be captured. |
86 | The Transaction ID that you provided was not found in the PayTrace records. It may already be voided, settled, or an uncaptured authorization. | Only approved sales, authorizations, and refunds that have not been settlement may be voided. A declined sale, a settled sale or a refunded sale may not be voided. |
87 | The Transaction ID that you provided was not found in the PayTrace records, and the receipt could not be emailed. | Only receipts with valid transaction IDs will be emailed. |
88 | The Transaction ID that you provided was not found in the PayTrace records, and level 3 data could not be added to the Visa transaction. | Only Visa sales that are currently pending settlement will have level 3 data added to them. |
89 | The Transaction ID that you provided was not found in the PayTrace records, and level 3 data could not be added to the MasterCard transaction. | Only MasterCard sales that are currently pending settlement will have level 3 data added to them. |
90 | The Transaction ID that you provided was not found in the PayTrace records, and the amount was not updated. | Only merchants using TSYS/Vital may update transaction amounts on non-Cash Advance transactions. Sales must be approved and pending settlement, refunds must be pending settlement, authorizations must be approved and unsettled, and forced sales must be pending settlement in order for their amounts to be updated to an amount less than or equal to the original transaction amount. |
110 | Please provide a valid value for Discretionary Title |
Discretionary Data values must match the criteria that are specified in the Virtual Terminal.
"Discretionary Title" in the response message is replaced with the actual title of the discretionary data element that needs an appropriate value. |
114 | Please provide a valid Store & Forward Date. | Store & Forward transactions may be submitted with optional scheduled processing dates. |
115 | Please provide a valid Approval Code. | Forced sales must be processed with valid approval codes. |
116 | Please provide a valid Transaction Type. | Only valid transaction types are accepted, and all requests to ProcessTranx require a transaction type. |
117 | Please provide a valid Billing Name. | Optional field for transactions and customers that must have the correct format. |
118 | Please provide a valid Billing Address. | Optional field for transactions and customers that must have the correct format. May be required if configured in your security settings. |
119 | Please provide a valid Billing Address 2. | Optional field for transactions and customers that must have the correct format. |
120 | Please provide a valid Billing City. | Optional field for transactions and customers that must have the correct format. |
121 | Please provide a valid Billing State. | Optional field for transactions and customers that must have the correct format. |
122 | Please provide a valid Billing Zip Code. | Optional field for transactions and customers that must have the correct format. May be required if configured in your security settings. |
123 | Please provide a valid Billing Country. | Optional field for transactions and customers that must have the correct format. |
124 | Please provide a valid Shipping Name. | Optional field for transactions and customers that must have the correct format. |
125 | Please provide a valid Shipping Address. | Optional field for transactions and customers that must have the correct format. |
126 | Please provide a valid Shipping Address 2. | Optional field for transactions and customers that must have the correct format. |
127 | Please provide a valid Shipping City. | Optional field for transactions and customers that must have the correct format. |
128 | Please provide a valid Shipping County. | Optional field for transactions and customers that must have the correct format. |
129 | Please provide a valid Shipping State. | Optional field for transactions and customers that must have the correct format. |
130 | Please provide a valid Shipping Zip Code. | Optional field for transactions and customers that must have the correct format. |
131 | Please provide a valid Shipping Country | Optional field for transactions and customers that must have the correct format. |
132 | Please provide a valid Phone Number. | Optional field for transactions and customers that must have the correct format. |
133 | Please provide a valid Source State. | Required for calculating shipping requests. |
134 | Please provide a valid Source Zip Code. | Required for calculating shipping requests. |
135 | Please provide a valid list of Shippers. | Required for calculating shipping requests. |
136 | Please provide a valid Weight. | Required for calculating shipping requests. |
137 | Please provide a valid Fax Number. | Optional field for transactions and customers that must have the correct format. |
139 | Please make sure the Shipping State and Shipping Zip are accurate. | Returned if errors are returned from the shipping provider(s) during the calculation of the shipping request. |
140 | … | Dynamic error(s) returned from shipping provider(s) may be returned from CalculateShipping requests. |
141 | Please provide a valid Email Address. | Optional field for transactions and customers that must have the correct format. Required to email a receipt. |
148 | Please provide a valid CSC. | Optional field for transactions that must have the correct format. May be required if configured in your security settings. |
149 | Please provide a valid Invoice Number. | Optional field for transactions and that must have the correct format. |
150 | Please provide a valid Description. | Optional field for transactions and that must have the correct format. |
151 | Please provide a valid Tax Amount. | Optional field for transactions and that must have the correct format. |
152 | Please provide a valid Customer Reference. | Optional field for transactions and that must have the correct format. |
153 | This customer profile does not have an email address to send the receipt. | A customer profile must have an email address in order for the recurring receipts to be emailed to the customer. |
160 | Please provide a valid Frequency. | A frequency is required to create a recurring payment. |
161 | Please provide a valid Transaction Count. | A transaction count is required to create a recurring payment. |
162 | Please provide a valid Start Date. | The start date is required to create a recurring payment. |
163 | Please provide a valid Next Date. | The next date is required to create a recurring payment. |
164 | Please provide a valid Repeat value. | An optional repeat value may be sent for recurring payments. |
165 | Please provide a valid Recurring Payment ID. | A recurring payment ID is required to update a recurring payment. |
169 | No recurring payments were found with this criteria. | Export recurring payments request returned no results. |
170 | No approved transactions were found for this customer. | Export recurring payment request returned no results. |
171 | Please provide a unique customer ID. | Each request to create a customer must contain a unique customer ID. |
172 | Please provide a Customer Password that is greater than 6 characters and less than 255 characters. | If you have access to the PayTrace shopping cart, you must provide a password when creating a customer. |
175 | Please provide a valid Start Date. | The start date for exporting transaction reports. |
176 | Please provide a valid End Date. | End date for exporting transaction reports. |
177 | Please provide a date range. | The end date must be passed/greater than the start date. |
178 | Please provide a valid User. | The user account for exporting transaction reports. |
179 | Please provide a valid number of Days. | The number of days value will need to be between 1 and 999 in the request. |
180 | No transactions were found with these criteria. | Export transactions request returned no results. |
185 | No customers were found with these criteria. | Export customers request returned no results. |
190 | Please provide a valid National Tax Amount. | Optional field for level 3 data that must have the correct format. |
191 | Please provide a valid Merchant Tax ID. | Optional field for level 3 data that must have the correct format. |
192 | Please provide a valid Customer Tax ID. | Optional field for level 3 data that must have the correct format. |
193 | Please provide a valid Commodity Code. | Optional field for level 3 data that must have the correct format. |
194 | Please provide a valid Discount Amount. | Optional field for level 3 data that must have the correct format. |
195 | Please provide a valid Freight Amount. | Optional field for level 3 data that must have the correct format. |
196 | Please provide a valid Duty Amount. | Optional field for level 3 data that must have the correct format. |
197 | Please provide a valid Additional Tax Amount. | Optional field for level 3 data that must have the correct format. |
198 | Please provide a valid Additional Tax Rate. | Optional field for level 3 data that must have the correct format. |
199 | Please provide a valid Additional Tax Indicator. | Optional field for level 3 data that must have the correct format. |
200 | Please provide a valid Line Item record. | A required field for level 3 data that must have the correct format. |
201 | Please provide a valid Line Item Commodity Code. | Optional field for level 3 data that must have the correct format. |
202 | Please provide a valid Line Item Description. | Optional field for level 3 data that must have the correct format. |
203 | Please provide a valid Line Item Product ID. | Optional field for level 3 data that must have the correct format. |
204 | Please provide a valid Line Item Quantity. | Optional field for level 3 data that must have the correct format. |
205 | Please provide a valid Line Item Measure. | Optional field for level 3 data that must have the correct format. |
206 | Please provide a valid Line Item Unit Cost. | Optional field for level 3 data that must have the correct format. |
207 | Please provide a valid Line Item Additional Tax Amount. | Optional field for level 3 data that must have the correct format. |
208 | Please provide a valid Line Item Additional Tax Rate. | Optional field for level 3 data that must have the correct format. |
209 | Please provide a valid Line Item Discount. | Optional field for level 3 data that must have the correct format. |
210 | Please provide a valid Line Item Amount. | Optional field for level 3 data that must have the correct format. |
211 | Please provide a valid Line Item Additional Tax Indicator. | Optional field for level 3 data that must have the correct format. |
212 | Please provide a valid Line Item Discount Rate. | Optional field for level 3 data that must have the correct format. |
213 | Please provide a valid Line Item Discount Indicator. | Optional field for level 3 data that must have the correct format. |
214 | Please provide a valid Line Item Net Gross Indicator. | Optional field for level 3 data that must have the correct format. |
215 | Please provide a valid Line Item Debit Credit Indicator. | Optional field for level 3 data that must have the correct format. |
230 | Batch was not initiated as no transactions are pending settlement. | Returned if request to SettleTranx is sent when no transactions may be settled. |
231 | Batch was not initiated as another batch is in progress or pending. | Returned if request to SettleTranx is sent when another batch is being settled or the last batch is pending any settlement problems. |
300 | Invalid Chip Read. Please reinsert card. | Returned if Card reader had technical issues reading the card. Reattempt the transaction by reinserting the chip into the reader. |
301 | Invalid Chip attempts exceeded. Please attempt swipe. | Returned after 3 consecutive invalid card reads prompting a Fallback. Reattempt transaction by Swiping card. |
302 | Empty Candidate. Please attempt swipe. | Returned if card reader had technical issues reading card prompting a Fallback. Reattempt transaction by Swiping card. |
303 | Card reader error. Please reinsert card. | Returned if card reader had technical issues reading card prompting a Fallback. Reattempt transaction by Swiping card. |
335 | Chip data Corrupted. | Returned if EMV chip encryption fails or if the card is read incorrectly. |
370 | The transaction has been terminated by the reader, please try again. | Returned if Card reader terminates the transaction for reasons other than prompting a Fallback. Reattempt the transaction by reinserting the chip into the reader. |
601 | Please provide a valid account type. | Returned if provide ACH Account type is invalid. Reattempt the transaction by reinserting a valid Account type. |
602 | Please provide a valid SEC code. | Returned if provide ACH SEC code is invalid. Reattempt the transaction by reinserting a valid SEC code. |
603 | Referenced Refund operation is not permitted for this transaction. | Returned if provide ACH transaction reference is not Refundable. Reattempt the transaction by reinserting a valid ACH transaction reference. |
604 | The Transaction ID that you have provided is already refunded. | Returned if provide ACH transaction id is already Refunded. Reattempt the transaction by reinserting a valid ACH transaction id which is not refunded before. |
605 | Provided SEC code is not supported. | Returned if provide SEC code is not supported for a ACH transaction. Reattempt the transaction by reinserting a valid SEC code which is supported for the ACH transaction you want to perform. |
606 | Provided idempotency-key not found. | Returned if there is no ACH transaction record found for provided idempotency-key. |
607 | Duplicate idempotency-key. | Returned if your Merchant has already used provided idempotency-key to make an ACH transaction. Reattempt the transaction by reinserting an unique idempotency-key. |
608 | Please provide a valid processor credential. | Returned if the processor credential provided by your Merchant is invalid. Reattempt the transaction by reinserting a valid processor credential. |
700 | This transaction was not approved because the authorization network was not available. Please retry this transaction again. | If a response is not returned to PayTrace from the issuing bank within 30 seconds, then a response is returned through the API advising of the authorization network being unavailable. |
710 | Dynamic response from the processing network | If a void request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
711 | Dynamic response from the processing network | If a capture request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
712 | Dynamic response from the processing network | If a refund request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
713 | Dynamic response from the processing network | If a forced sale request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
740 | PayTrace is unable to process this check as the check processor information is incomplete or the network returned an error. | In the event that you receive this error message, please contact PayTrace Support to determine if some of the check processor information on your account is incomplete. |
750 | PayTrace does not support this transaction type for this check processor. | Specific check processors only support certain transaction types. For example, Paya only supports sale requests and some instances of void requests. If a request is sent w/ a transaction type that is not supported by the check processor enabled on the PayTrace account, this error is returned. |
777 | PayTrace blocked this transaction because it is a duplicate, and it may be reprocessed in ### minute(s). | cell-content |
778 | PayTrace blocked this transaction because it exceeded the specified velocity filter. | PayTrace compares requests to process new transactions against specified velocity filters when velocity filters are established on specific PayTrace accounts. For more information about velocity filters, contact PayTrace Support. |
779 | BLOCKED - This card number has been blocked to prevent potential fraud. | This occurs when 4 consecutive not-approved transactions are processed within a 24-hour time frame to the same card number. Voided transactions within the same 24-hour period count towards this. |
790 | PayTrace blocked this transaction because it exceeded the specified API Transaction Limit. | API Transactions have exceeded normal, daily transaction limits and thus, have been temporarily disabled. Fraudulent transactions may be the cause. |
811 | The Transaction ID that you provided was not found. | The transaction ID isn’t found on the account. |
812 | The Transaction ID that you provided was found but was not processed by you | Transaction ID exists on this account but the user only has permission to view their own transactions and this transaction was processed by another user. |
813 | The Transaction ID that you provided was found but the card type is not supported. | Transaction ID exists but the card number is corrupt or is no longer supported. |
816 | The Transaction ID that you provided could not be captured. Only uncaptured, approved authorizations can be captured. | Transaction ID exists but its status can’t be captured. |
817 | The Transaction ID that you provided could not be refunded. Only settled transactions can be refunded. Please try to void the transaction instead. | Transaction ID exists but its status can’t be refunded. |
818 | The Transaction ID that you provided could not be voided. Only transactions that are pending settlement or uncaptured authorizations can be voided. | Transaction ID exists but its status can’t be voided. |
819 | Refund amount can not exceed the original settled amount. Previous refunds against this transaction count towards the original transaction amount. | Total refund amount, including all previous attempts, is larger than the Transaction’s settlement amount. |
867 | Please provide valid new passwords. | Passwords must be provided when processing a request to change your password. |
869 | Please provide new passwords that are unique to your previous 4 passwords. | New passwords must be unique to your 4 previous passwords. |
880 | This customer is scheduled for recurring payment # xxxxx and may not be deleted. | Customers with pending recurring payments may not be deleted. |
900 | Please indicate that you agree with PayTrace’s terms and conditions. | The TERMS parameter must be set to Y. |
950 | Unreferenced refunds are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept refunds to be processed without referencing the previously processed transaction’s ID. |
951 | Forced Sales are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept forced sales to be processed. |
952 | Swiped/card present transactions are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept card present transactions. |
961 | No payment fields found with the provided token. | Returned when Protect Tokenized data is not found within the PayTrace system or Provided Token or enc_key is corrupted. |
970 | param is missing or the value is empty: value | Returned when required Protect.js or EMV parameters are not provided within the API request or if they have empty values. |
971 | Please provide a valid integrator_id. | Returned when Integrator Id is not provided or when Provided Integrator Id is not registered with PayTrace. |
973 | The processor information for xxxxxx is incomplete. | An incomplete PayTrace account is not able to process requests. |
974 | Your PayTrace account is not set up to use the B2B API. | Your account must have access to the API in order to process through it. |
975 | Your PayTrace account is not set up to process recurring transactions. | Your account must have access to the recurring payments module in order to process recurring payments. |
976 | Your account is only set up to process Cash Advances and Voids. | Cash advance accounts may only process cash advances, voids, email receipts, export transactions, and update password requests. |
977 | Your PayTrace account is not set up to process EMV transactions. | EMV transactions may only be processed by accounts that are set up to process EMV transactions. Please contact PayTrace or your reseller for more information. |
978 | Your account is not set up to process checks. | Check transactions may only be processed by accounts that are set up to process Check transactions. Please contact PayTrace or your reseller for more information. |
979 | Password is expired. Please log in to the virtual terminal to reset the password. | Passwords must be changed at least once every 90 days. Reminders are emailed 14, 7, 1, and 0 days before the password expires. |
980 | Log in failed for insufficient permissions. | The user account must have permission/access to process an authorization. |
981 | Log in failed for insufficient permissions. | The user account must have permission/access to process a refund. |
982 | Log in failed for insufficient permissions. | The user account must have permission/access to process a void. |
983 | Log in failed for insufficient permissions. | The user account must have permission/access to process a capture. |
984 | Log in failed for insufficient permissions. | The user account must have permission/access to process a forced sale. |
985 | Log in failed for insufficient permissions. | The user account must have permission/access to create, update, or delete customers. |
986 | Log in failed for insufficient permissions. | The user account must have permission/access to create, update, or export a recurring payment. |
987 | Please provide a valid method or request to process. | Only valid methods are accepted for processing through the API. |
988 | Log in failed. | An unsuccessful login attempt occurred because of an IP rule conflict. |
989 | Log in failed for insufficient permissions. | The user account must have permission/access to export transactions. |
990 | Please provide properly formatted parameters. | The API request is not properly formatted as a JSON format. |
993 | xxxxxx is not a valid parameter name. |
An invalid parameter was included in the request. Some parameters are case sensitive.
For example: number as "NUMBER" |
997 | PayTrace API only supports POST requests. | All integration API requests should be of POST type to adhere to PCI requirements |
998 | Log in failed |
An unsuccessful login attempt occurred. With either of the following reasons.
1. The account is disabled. 2. Four consecutive unsuccessful log in attempts will disable a user’s account. |
999 | Log in failed for insufficient permissions. | The user account must have permission/access to process a sale. |
1001 | Decryption failed. | Encrypted request data should be encrypted with the merchant account-specific public key only. |
9102-9185 | System error occurred, and a PayTrace specialist has been notified. Thank you for your patience. | Non-Specific Error. Please contact Developer Support for further information. |
Testing Information
For API testing and integration, make sure to check following:
- You have a valid account with API module enabled. PayTrace recommends testing in a Sandbox account prior to testing in a live environment.
- Make sure to set and be aware about your account security settings from the PayTrace Virtual Terminal.
- You server side code submits a valid authorization token in the expected format. See the Authentication section for more information.
- Your API requests should have at least the required request parameters to avoid errors.
- Your code can handle HTTP errors and API errors gracefully. See the Error Responses section for more information.
Test Data
The following data can be used to test in the sandbox environment. Note that using this data in a live environment will result in declines.
Testing Credit Cards
Credit Card Type | Credit Card Number | *Expiration MM/YY |
---|---|---|
Visa | 4012000098765439 | 12/35 |
MasterCard | 5499740000000057 | 12/35 |
Discover | 6011000993026909 | 12/35 |
American Express | 371449635392376 | 12/35 |
*Any valid expiration month and year will work as well.
Testing CSCs
Credit Card Type | CSC Number | Response |
---|---|---|
Visa | 999 | Approval |
MasterCard | 998 | Approval |
Discover | 996 | Approval |
American Express | 9997 | Approval |
Testing Addresses for AVS Response
Address (street number) | Zip Code | Response Text |
---|---|---|
8320 | - | Address Match |
- | 85284 | Zip Match |
8320 | 85284 | Exact Match |
- | 99999 | Ver Unavailable |
Testing Amount
Amount | Response Text |
---|---|
$0.00 | Amount Error |
$0.01 | Call |
$0.02 | Call |
$0.05 | Hold - Call |
$0.06 | Hold - Call |
$0.07 | Hold - Call |
$0.08 | Hold - Call |
$0.20 | Decline |
$0.21 | Decline |
$0.22 | Decline |
$0.23 | Decline |
$0.24 | Decline |
$0.25 | Decline |
$0.26 | Decline |
$0.29 | Expired Card |
$0.39 | No Such Issuer |
$0.41 | RE-ENTER |
$0.43 | Serv Not Allowed |
$0.44 | Serv Not Allowed |
$0.48 | CVV Mismatch |
$0.49 | Card OK |
$0.50 | APPROVAL |
$0.51 | Prompt for Level II Data |
$0.53 | Prompt for Level 3 Data |
$1.00 or more | APROVAL |
$1.12 | Decline |
$1.13 | Decline |
$11.11 | Partial Approval |
$52.00 | Partial Approval |
Configuring Security Settings
After receiving your sandbox credentials, you must configure your sandbox account to match your anticipated production account. To do so, log in to PayTrace and select the Security Settings tab under the Account Tab. Please see the Account Security settings here for more information regarding PayTrace Security Settings.
Setup
- Send an authentication request with your API user credentials to generate an access token.
- Prepare the request using an access token and test data. Submit the request to one of the API methods.
- For API errors, see the PayTrace Virtual Terminal → Integration → API log. Look at the API Log for more details.
Creating API Credentials
Log in to the PayTrace sandbox application with Virtual Terminal using your admin web username and password.
Creating API User Credentials Best Practices
Do not use any special characters within your username and password. Alphanumeric only.
Permissions
Use the Select All button under Permissions to allow your API user to manage everything within the integration. If you do not do this, you may run into processing issues.
Authentication
The PayTrace JSON API requires authentication and authorization to make all the requests. The PayTrace JSON API uses OAuth 2.0 for Authentication and Authorization.
OAuth 2.0 provides a "client_credentials" grant type that can be used to exchange a username and password for an access token directly. If you decide not to use any of the 3rd party OAuth 2.0 libraries, the following steps are needed :
- You can simply make a request to our API with your API account user credentials and get the Bearer access token.
- Then use the Bearer Access token in an Authorization Header along with other settings to make any further API request provided with this documentation. For more information, see the Request Header section.
To initiate the transaction request, you will need to make calls to two API endpoints.
The first call is to authenticate. You can make this call using a variety of server-side languages or libraries of your choice. Here are the details for this request:
Method: POST
Request URL: https://api.sandbox.paytrace.com/v3/token/
CURL Exampleshell
Request BodyJSON
Authentication Error Example
The following error response will be returned when sending incorrect user credentials with HTTP status code 401-Unauthorized.
Authentication ErrorJSON
Authentication Successful Response
When authentication is successful, you will receive a JSON response which includes an "access_token" field. The value in this field will be used in the next step.
How to utilize the Authentication token in the Authorization header
Once you get the Authentication token, you can submit the token_type and access_token as values in the Authorization Header of your API request.
Authorization Header format
The authentication format is Bearer access_token.
Authorization Successful Response
The following response will be returned with HTTP Status code 200 OK.
Successful ResponseJSON
Each API request requires authentication via the access token described earlier.
Authentication Errors Summary
errors | error_description |
---|---|
invalid_grant |
The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
invalid_token |
Depending upon the token value, the appropriate error message will be returned. -The access token was revoked. -The access token expired. -The access token is invalid. |
unsupported_grant_type |
The authorization grant type is not supported by the authorization server. |
invalid_resource_owner |
The provided resource owner credentials are not valid, or resource owner cannot be found. |
invalid_request |
The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed. |
invalid_client |
Client authentication failed due to an unknown client, no client authentication included, or unsupported authentication method. |
access_denied |
The resource owner or authorization server denied the request. |
invalid_scope |
The requested scope is invalid, unknown, or malformed. |
server_error |
The authorization server encountered an unexpected condition which prevented it from fulfilling the request. |
temporarily_unavailable |
The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
Grant Type: Client Credentials or Refresh Token
This endpoint serves multiple purposes. It will grant the initial access token via the grant_type=client_credentials parameter, as well as a refresh token via the grant_type=refresh_token parameter.
Status Updates and Communications
To receive notifications whenever PayTrace creates an incident, updates an incident, resolves an incident or changes a component status, sign up for the Status Page . Notifications are available via webhook, text and email.
To stay up to date with PayTrace product updates & features, webinar schedules & registration, payment industry jib jab, plus random contributions of PayTracer culture, talent, and in-house happenings, we encourage you to subscribe to our Blog.
e2ee Client-Side Library
The PayTrace End-to-end-encryption (e2ee) Library supports client-side encryption of sensitive data, reduces merchant's and integrator's exposure to PCI-compliance verification. Sensitive data can be encrypted at the user's web browser using The PayTrace JavaScript E2ee Library. The encrypted data can only be decrypted by PayTrace. The merchant or the integrator has no access to the original sensitive data. It helps to ensure that sensitive data remains unreadable in as many locations as possible. Primarily card data (credit and debit) and other sensitive data points fall into this category.
In contrast to earlier API versions, all data points noted as e2ee are required to be encrypted before being sent to this API.
The benefits of using the PayTrace Client-Side E2ee Library
- It will allow your customers to process transactions on your website.
- Your customers are not required to be redirected to another payment page.
- It provides your customers the comfort and security of processing payments on your website.
- Utilizing this Library reduces your PCI scope
Encryption Details
The sensitive data is encrypted before the web form is submitted and until it is received at PayTrace's secure server. The RSA public/private key pair is used to encrypt sensitive credit card data. The public key corresponds to API E2ee Public key endpoint. It will be used to encrypt the sensitive data. Only PayTrace can decrypt the encrypted data with the private key.
How to utilize the PayTrace Client-Side Encryption Library
- Incorporate The PayTrace Client-Side Encryption Library in a web form.
- Get the encrypted field value with your server side code.
- Submit the encrypted values to the API calls.
How to incorporate the PayTrace Client-Side E2ee Library in a web form?
The following steps are required to utilize The PayTrace Client-Side E2ee Library in a web form.
-
Setup: Include The PayTrace E2ee Library using script tag in a header section.
ExampleHTML
-
For the sensitive data fields that should be encrypted at the browser, add the "pt-encrypt" class.
ExampleHTML
-
Submit a form with any of the following scenarios.
-
Bind the submit event of the form to the PayTrace Client-Side E2ee Library.
ExampleHTML
-
Or submit a valid form to the PayTrace Client Side E2ee Library. You will need to validate your form with your own implementation first and then submit the valid form. However, you will need to set the key with paytrace.setKeyAjax(url) method before a valid form is submitted.
ExampleHTML
-
Bind the submit event of the form to the PayTrace Client-Side E2ee Library.
How to submit encrypted values to the API
Once you have received the encrypted values on the server side with form submission, submit them using an API Request. No additional request parameters are needed to prompt the API to accept the encrypted values. This API accepts encrypted values only. For example, the credit card number will assigned card.number, the CSC will be assigned to csc.
Protect.js
In today’s world, security and PCI compliance play important roles in protecting cardholders and delivering cash flow for businesses.
Protect.js uses an iframe to create PayTrace hosted fields when collecting sensitive-payment information. This allows you to control the UI and UX of your checkout process so that cardholder data never touches your servers.
You can quickly start accepting secure payments and storing cardholders’ payment information by embedding a few lines of code within your existing checkout flow while achieving the highest level of PCI-Compliance, SAQ-A.
The benefits of using PayTrace Protect.js
- It will allow your customers to process transactions on your website.
- It will allow your customers to safely and securely store their credit card information for future use.
- Your customers are not required to be redirected to another payment page.
- It provides your customers the comfort and security of processing payments on your website.
- Using Protect.js reduces your PCI scope and can help you qualify for PCI SAQ-A.
The PayTrace Protect.js Workflow
Protect.js Details
Protect.js places PayTrace Hosted Payment fields within an iframe on your webform. This will allow your customers to enter their sensitive credit card information directly into PayTrace while ensuring your server does not handle any sensitive data. Once this information has been captured, Protect.js will then return a one-time-use hpf_token (nonce) and enc_key. The nonce and enc_key can then be submitted via an API request in order to process transactions or create customer profiles.
How to incorporate Protect.js in a web form
The following steps are required to utilize The PayTrace Protect.js Library in a web form. Our examples make use of Promises and Arrow Functions which are not supported by IE11. For integrators wishing to support IE11, you will need to use Callback Functions and methods. For assistance, please contact our dedicated Developer Support team.
-
Setup: Include the JS library and div container tag for iframe on your website. Please refer to the code
sample:
ExampleHTML
This step allows the PTPayment object to become available when the Protect library script is sourced in the web application. See the available PTPayment methods below.
Toggle PTPayment Methods
Method Description process
Validates and tokenizes Hosted Payment Field Data
setup
Initializes the Protect.js Hosted Payment Fields within iframe using the clientkey.
Styling options can be statically applied during the setup call. For more information regarding our styling options, see Styling Options.
validate
Validates Hosted Payment Field input prior to tokenizing data.
Takes function as an argument.
reset
Clears Hosted Payment Fields and resets Protect.js to its beginning state.
-
Get authorization for the application to use the JSON API. Make an OAuth authorization call to the JSON API
to get an API AUTH TOKEN. This token will be used as the authorization bearer access token to authorize the
application to use PayTrace’s API. The token should be kept secret and should never be added to client side
code. This token is valid for 2 hours.
ExampleShell
See the Authentication section for more information about how to generate an Oauth Token.
-
Use the JSON API Authorization token to get authorization to use Protect.js using the API AUTH TOKEN from
step two as the authorization header. Make a JSON API POST request to:
https://api.paytrace.com/v3/payment_fields/token/create
to get a PROTECT AUTH TOKEN (clientKey). The clientkey will be used to authorize the application to use
Protect.js. This key is valid for 20 minutes.
ExampleCURL
-
Use the Protect authorization token to set up the payment form. Please refer to the code sample:
ExampleHTML
By this point, you should be able to see the Protect.js iframe rendered on your webpage. See the example below:
To improve the look and feel of Protect.js, styling options can be statically applied during the setup call. For more information regarding our styling options, see the Protect.js Styling section.
-
Bind the submit event to an event handler for the tokenization of sensitive data. The process method will
tokenize the sensitive data in the payment fields. The method returns an http promise that will either be
fulfilled (resolved) or rejected. If it is rejected, the possible reasons are: network error, internal
error, or the fields did not pass validation.
-
Validate the fields before tokenizing sensitive data. PTPayment.validate will validate the payment
fields and allow you to re-prompt your customers to enter valid information.
Dynamic styling can then be used to better control your customer experience when invalid input is entered. For more information regarding our styling options, see the Protect.js Styling section.
For a list of potential validation errors, see the Validation Error Responses below. Please refer to the code sample:
ExampleJS -
Or directly tokenize sensitive data. The tokenization process also validates the sensitive data payment
fields. Dynamic styling can then be used within the error handling to better control your customer
experience when invalid input is entered. For more information regarding our styling options, see the
Protect.js Styling section.
For a list of potential validation errors, see the Validation Error Responses below. Please refer to the code sample:
ExampleJS
-
Validate the fields before tokenizing sensitive data. PTPayment.validate will validate the payment
fields and allow you to re-prompt your customers to enter valid information.
Validation Error Responses
If for any reason the users input fails the Protect.js validation, the appropriate response code will be returned in the error response.
Toggle Response Codes
Response Code | Description | Reason |
---|---|---|
35 |
Please provide a valid Credit Card Number. |
The Credit card Number was invalid or not provided. |
43 |
Please provide a valid Expiration Month. |
The expiration Month was invalid or not provided. |
44 |
Please provide a valid Expiration Year. |
The expiration Year was invalid or not provided. |
148 |
Please provide a valid CSC. Must be 3 to 4 digits. |
The CSC/CVV value was invalid. |
400 |
Varies based on validation error |
In the case that an error occurs in which a general use case is not covered, this response code will be thrown with a description indicating the field that it detected a problem with. |
How to submit Protect.js Tokens through the API
Once you have received the hpf_token (nonce) and enc_key, you will then submit these values using an API request and the Oauth token from Step 2. API methods that are meant to be used with the Protect.js UI are listed within their appropriate request categories and begin with the keyword Protect.
Toggle API Methods
Method | Description |
---|---|
Processes a Sale transaction using the Protect.js UI. | |
Processes a Sale transaction and creates a customer profile, upon transaction approval, using the Protect.js UI. | |
Processes an Authorization using the Protect.js UI. | |
Stores your customer’s billing and payment information, in PayTrace’s PCI-compliant Customer Database (Vault), using the Protect.js UI. | |
Modifies an existing customer profile, stored in PayTrace’s PCI-compliant Customer Database (Vault), using the Protect.js UI. |
Successful Protect.js tokenization responseJSON
Protect.js validation error responseJSON
Protect.js Styling
Protect.js allows you to style the Hosted Payment Fields to best fit your website. Styling can be applied either statically, during the setup method call, or dynamically during runtime.
Static Styling Options
The following options are available during the Protect.js setup phase.
Styleable Fields
Field | Description |
---|---|
code | CSC Input field |
cc | Credit card number input field |
exp | Expiration date Input field |
body | Body of the iframe |
NOTE: Only background_color can be modified.
Styling Options
Option | Description | Acceptable Values |
---|---|---|
background_color | Background color of the text box or iframe |
CSS keyword or hexadecimal color value
Default color is 'white' |
border_color | Color of textbox border |
CSS keyword or hexadecimal color value
Default color is 'black' |
border_style | Border style of the text box |
CSS keyword
Default style is 'solid' |
font_color | Font color of input data |
CSS keyword or hexadecimal color value
Default color is 'black' |
font_size | Font size of input data | CSS units |
height | Height of text box |
CSS units
Will default to font_size if not provided |
input_border_radius | Border radius of text box | CSS units |
input_border_width | Border width of text box | CSS units |
input_font | Font of input data |
CSS keyword
Can include several font names for fallback options |
input_font_weight | Font weight of input data |
CSS keyword or font-weight value
Default font-weight is 'normal' or 400 |
input_margin | Margin around text box border |
CSS units
(top, right, bottom, left) |
input_padding | Padding between input data and text box border |
CSS units
(top, right, bottom, left) |
label_border_color | Border color around payment field label |
CSS keyword or hexadecimal color value
Default color is 'black' |
label_border_radius | Border radius around payment field label | CSS units |
label_border_style | Border style around payment field label |
CSS keyword
Default style is 'solid' |
label_border_width | Border width around payment field label | CSS units |
label_color | Color of payment field label |
CSS keyword or hexadecimal color value
Default color is 'black' |
label_font | Font of payment field label |
CSS keyword
Can include several font names for fallback options |
label_font_weight | Font weight of payment field label |
CSS keyword or font-weight value
Default font-weight is 'normal' or 400 |
label_margin | Margin around payment field label border |
CSS units
(top, right, bottom, left) |
label_padding | Padding between payment field label and payment field label border |
CSS units
(top, right, bottom, left) |
label_size | Size of payment field label | CSS units |
label_width | Width of payment field label | CSS units |
padding_bottom | Padding added below input text box | CSS units |
type |
Payment field input boxes can be defined as text or a dropdown
NOTE: Only available for Expiration Month and Year sensitive data field input boxes |
'dropdown' or 'textbox'
Default type is 'dropdown' |
width | Width of text box | CSS units |
Static Styling Example
Dynamic Styling Options
The following PTPayment methods can be used to style the Project.js Payment fields during runtime. To utilize these methods, you will need to implement them within the .then method once the promise has resolved.
Dynamic Styling Methods
Method | Description |
---|---|
style | Allows you to modify any of the input field styling options. |
theme |
Allows you to adjust where the labels are displayed around the payment field input boxes.
Available Options: 'above the line', 'horizontal', 'below the line', 'label-extended-top' or 'label-none' The default theme is 'above the line' if a theme is not defined. Labels will be right justified against the input fields with the 'horizontal' theme. The 'label-extended-top' theme places the security code on its own line below the expiration date. The 'label-none' theme removes the labels completely and only displays the input boxes. NOTE: May require you to adjust the size of the div container via CSS. |
getControl |
Allows you to customize the label text for the input fields
The default labels are CC Number, Expiration and Security Code if custom labels are not defined. The control types are: securityCode, creditCard, expiration. |