DEVELOPER

B2B API



Products

B2B API Integration Guide

EnvironmentBase URL
Sandboxhttps://api.sandbox.paytrace.com/
Productionhttps://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:

  1. Switch sandbox endpoints to the production endpoints.
  2. 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.

Example
JSON
{
	"status": "success",
	"status_code": 201,
	"data": {
		"access_token": "eyJ...4sA=",
		"refresh_token": "eyJ...n_v4sA=",
		"token_type": "Bearer",
		"expires_in": 900,
		"refresh_expires_in": 3600
	}
}

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.

HeaderValue
AuthorizationThe Bearer JWT received from the Authorization step.
Content-Typeapplication/json
Cache-Controlno-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:

Example
JSON
{
	"status": "success",
	"status_code": 200,
	"data": {
		"response_code": 101,
		"response_message": "Your transaction was successfully approved.",
		"transaction_id": "123456789",
		"approval_code": "999999",
		"approval_message": "APPROVAL 999999",
		"avs_response": null,
		"csc_response": null,
		"masked_card_number": "xxxxxxxxxxxx5454",
		"discretionary_data": null,
		"emv_details": null
	}
}

The response_code will contain one of the following codes with an associated response_message:

CodeMessageReason
1One or more errors occurred.An internal exception that was not handled has occurred.
100Password updated.
101Transaction approved.
102Transaction NOT approved.
103Transaction 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.
106Transaction refunded.
107Transaction NOT refunded.
108TEST Transaction refunded, HOWEVER NO FUNDS WILL BE REFUNDED.Returned when a request to process a TEST refund transaction generates a completed transaction.
109Transaction voided.
110Transaction NOT voided.
112Transaction captured.
113Transaction NOT captured.
120Check processed.
122Check refunded.
124Check managed.Returned when a request to manage a check for void or fund is successfully processed.
125Check 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.
149Receipt for a transaction ID was emailed.
150Recurring transaction created.
151Recurring transaction updated.
152Recurring transaction deleted.
155This 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.
160Customer created.
161Customer updated.
162Customer deleted.
165Transaction approved & customer created.
167Transaction approved & customer NOT created.
170Visa level 3 added to transaction ID.Returned when a request to add level 3 data is successful for a Visa transaction.
171MasterCard 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.
180Transaction 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:
Example
JSON
{
	"status": "error",
	"status_code": 422,
	"data": [
		{
			"detail": "Please send the e2ee encrypted value.",
			"type": "VALIDATION",
			"code": "E2EE_REQUIRED",
			"field": "body/csc",
			"error_id": null
		}
	]
}

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 CodeError DetailReason
30Customer ID, xxxxx, was not found or is incomplete.A customer ID is required when processing a request that references a stored customer.
35Please provide a valid Credit Card Number.All card numbers sent to PayTrace must pass the Mod 10 check.
36Customer 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.
37Customer 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.
39Your 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.
40An error occurred during the decryption process. PayTrace supports encrypted card readers. This error is returned if an error occurs during the decryption process.
43Please provide a valid Expiration Month.All transactions and customer profiles must have a 2 digit expiration month.
44Please provide a valid Expiration Year.All transactions and customer profiles must have a 2 digit expiration year.
45Please provide a valid Checking Account Number.Required if creating a customer without a card number or processing a check transaction.
46Please provide a valid Transit Routing Number.Required if creating a customer without a card number or processing a check transaction.
47Please 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.
48Please 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.
51Please provide a valid Amount.All transactions must have a valid numeric amount.
53Capture Amount can not exceed 30% of the original authorized amount.All transactions must have a valid numeric amount.
54Cash 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.
55Cash 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.
56Cash Advances may not be processed to stored customers.Cash advance transactions must be processed as face to face transactions.
57Your 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.
58Please 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.
59Please provide a valid Check ID. Manage Check and email receipt requests require a check ID that references a check-in PayTrace’s system.
61The 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.
62Please provide a valid Photo ID.Cash Advance requests require a photo ID to be provided.
63Please provide a valid ID Expiration.Cash Advance requests require an ID expiration date to be provided.
64Please provide a valid Last 4 of Card.Cash Advance requests require the last 4 digits of the card number to be provided.
65Cash 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.
82Please 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.
83This is not an approved transaction so it can not be captured.Only approved authorizations may be captured.
84This 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.
110Please 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.
114Please provide a valid Store & Forward Date.Store & Forward transactions may be submitted with optional scheduled processing dates.
115Please provide a valid Approval Code.Forced sales must be processed with valid approval codes.
116Please provide a valid Transaction Type. Only valid transaction types are accepted, and all requests to ProcessTranx require a transaction type.
117Please provide a valid Billing Name.Optional field for transactions and customers that must have the correct format.
118Please 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.
119Please provide a valid Billing Address 2.Optional field for transactions and customers that must have the correct format.
120Please provide a valid Billing City.Optional field for transactions and customers that must have the correct format.
121Please provide a valid Billing State.Optional field for transactions and customers that must have the correct format.
122Please 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.
123Please provide a valid Billing Country.Optional field for transactions and customers that must have the correct format.
124Please provide a valid Shipping Name.Optional field for transactions and customers that must have the correct format.
125Please provide a valid Shipping Address.Optional field for transactions and customers that must have the correct format.
126Please provide a valid Shipping Address 2.Optional field for transactions and customers that must have the correct format.
127Please provide a valid Shipping City.Optional field for transactions and customers that must have the correct format.
128Please provide a valid Shipping County.Optional field for transactions and customers that must have the correct format.
129Please provide a valid Shipping State.Optional field for transactions and customers that must have the correct format.
130Please provide a valid Shipping Zip Code.Optional field for transactions and customers that must have the correct format.
131Please provide a valid Shipping CountryOptional field for transactions and customers that must have the correct format.
132Please provide a valid Phone Number.Optional field for transactions and customers that must have the correct format.
133Please provide a valid Source State.Required for calculating shipping requests.
134Please provide a valid Source Zip Code.Required for calculating shipping requests.
135Please provide a valid list of Shippers.Required for calculating shipping requests.
136Please provide a valid Weight.Required for calculating shipping requests.
137Please provide a valid Fax Number.Optional field for transactions and customers that must have the correct format.
139Please 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.
141Please provide a valid Email Address. Optional field for transactions and customers that must have the correct format. Required to email a receipt.
148Please provide a valid CSC. Optional field for transactions that must have the correct format. May be required if configured in your security settings.
149Please provide a valid Invoice Number.Optional field for transactions and that must have the correct format.
150Please provide a valid Description.Optional field for transactions and that must have the correct format.
151Please provide a valid Tax Amount.Optional field for transactions and that must have the correct format.
152Please provide a valid Customer Reference.Optional field for transactions and that must have the correct format.
153This 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.
160Please provide a valid Frequency.A frequency is required to create a recurring payment.
161Please provide a valid Transaction Count.A transaction count is required to create a recurring payment.
162Please provide a valid Start Date.The start date is required to create a recurring payment.
163Please provide a valid Next Date.The next date is required to create a recurring payment.
164Please provide a valid Repeat value.An optional repeat value may be sent for recurring payments.
165Please provide a valid Recurring Payment ID.A recurring payment ID is required to update a recurring payment.
169No recurring payments were found with this criteria.Export recurring payments request returned no results.
170No approved transactions were found for this customer.Export recurring payment request returned no results.
171Please 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.
175Please provide a valid Start Date.The start date for exporting transaction reports.
176Please provide a valid End Date.End date for exporting transaction reports.
177Please provide a date range.The end date must be passed/greater than the start date.
178Please provide a valid User.The user account for exporting transaction reports.
179Please provide a valid number of Days.The number of days value will need to be between 1 and 999 in the request.
180No transactions were found with these criteria.Export transactions request returned no results.
185No customers were found with these criteria.Export customers request returned no results.
190Please provide a valid National Tax Amount.Optional field for level 3 data that must have the correct format.
191Please provide a valid Merchant Tax ID.Optional field for level 3 data that must have the correct format.
192Please provide a valid Customer Tax ID.Optional field for level 3 data that must have the correct format.
193Please provide a valid Commodity Code.Optional field for level 3 data that must have the correct format.
194Please provide a valid Discount Amount.Optional field for level 3 data that must have the correct format.
195Please provide a valid Freight Amount.Optional field for level 3 data that must have the correct format.
196Please provide a valid Duty Amount.Optional field for level 3 data that must have the correct format.
197Please provide a valid Additional Tax Amount.Optional field for level 3 data that must have the correct format.
198Please provide a valid Additional Tax Rate.Optional field for level 3 data that must have the correct format.
199Please provide a valid Additional Tax Indicator.Optional field for level 3 data that must have the correct format.
200Please provide a valid Line Item record.A required field for level 3 data that must have the correct format.
201Please provide a valid Line Item Commodity Code.Optional field for level 3 data that must have the correct format.
202Please provide a valid Line Item Description.Optional field for level 3 data that must have the correct format.
203Please provide a valid Line Item Product ID.Optional field for level 3 data that must have the correct format.
204Please provide a valid Line Item Quantity.Optional field for level 3 data that must have the correct format.
205Please provide a valid Line Item Measure.Optional field for level 3 data that must have the correct format.
206Please provide a valid Line Item Unit Cost.Optional field for level 3 data that must have the correct format.
207Please provide a valid Line Item Additional Tax Amount.Optional field for level 3 data that must have the correct format.
208Please provide a valid Line Item Additional Tax Rate.Optional field for level 3 data that must have the correct format.
209Please provide a valid Line Item Discount.Optional field for level 3 data that must have the correct format.
210Please provide a valid Line Item Amount.Optional field for level 3 data that must have the correct format.
211Please provide a valid Line Item Additional Tax Indicator.Optional field for level 3 data that must have the correct format.
212Please provide a valid Line Item Discount Rate.Optional field for level 3 data that must have the correct format.
213Please provide a valid Line Item Discount Indicator.Optional field for level 3 data that must have the correct format.
214Please provide a valid Line Item Net Gross Indicator.Optional field for level 3 data that must have the correct format.
215Please provide a valid Line Item Debit Credit Indicator.Optional field for level 3 data that must have the correct format.
230Batch was not initiated as no transactions are pending settlement.Returned if request to SettleTranx is sent when no transactions may be settled.
231Batch 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.
300Invalid 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.
301Invalid Chip attempts exceeded. Please attempt swipe. Returned after 3 consecutive invalid card reads prompting a Fallback. Reattempt transaction by Swiping card.
302Empty Candidate. Please attempt swipe. Returned if card reader had technical issues reading card prompting a Fallback. Reattempt transaction by Swiping card.
303Card reader error. Please reinsert card. Returned if card reader had technical issues reading card prompting a Fallback. Reattempt transaction by Swiping card.
335Chip data Corrupted.Returned if EMV chip encryption fails or if the card is read incorrectly.
370The 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.
601Please provide a valid account type. Returned if provide ACH Account type is invalid. Reattempt the transaction by reinserting a valid Account type.
602Please provide a valid SEC code. Returned if provide ACH SEC code is invalid. Reattempt the transaction by reinserting a valid SEC code.
603Referenced 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.
604The 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.
605Provided 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.
606Provided idempotency-key not found.Returned if there is no ACH transaction record found for provided idempotency-key.
607Duplicate 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.
608Please 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.
710Dynamic 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.
711Dynamic 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.
712Dynamic 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.
713Dynamic 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.
750PayTrace 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
778PayTrace 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.
779BLOCKED - 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.
790PayTrace 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.
811The Transaction ID that you provided was not found.The transaction ID isn’t found on the account.
812The 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.
813The 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.
867Please provide valid new passwords.Passwords must be provided when processing a request to change your password.
869Please provide new passwords that are unique to your previous 4 passwords.New passwords must be unique to your 4 previous passwords.
880This customer is scheduled for recurring payment # xxxxx and may not be deleted.Customers with pending recurring payments may not be deleted.
900Please indicate that you agree with PayTrace’s terms and conditions.The TERMS parameter must be set to Y.
950Unreferenced 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.
951Forced 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.
952Swiped/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.
961No 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.
970param 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.
971Please provide a valid integrator_id. Returned when Integrator Id is not provided or when Provided Integrator Id is not registered with PayTrace.
973The processor information for xxxxxx is incomplete.An incomplete PayTrace account is not able to process requests.
974Your 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.
975Your 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.
976Your 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.
977Your 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.
978Your 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.
979Password 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.
980Log in failed for insufficient permissions.The user account must have permission/access to process an authorization.
981Log in failed for insufficient permissions.The user account must have permission/access to process a refund.
982Log in failed for insufficient permissions.The user account must have permission/access to process a void.
983Log in failed for insufficient permissions.The user account must have permission/access to process a capture.
984Log in failed for insufficient permissions.The user account must have permission/access to process a forced sale.
985Log in failed for insufficient permissions.The user account must have permission/access to create, update, or delete customers.
986Log in failed for insufficient permissions.The user account must have permission/access to create, update, or export a recurring payment.
987Please provide a valid method or request to process.Only valid methods are accepted for processing through the API.
988Log in failed.An unsuccessful login attempt occurred because of an IP rule conflict.
989Log in failed for insufficient permissions.The user account must have permission/access to export transactions.
990Please provide properly formatted parameters.The API request is not properly formatted as a JSON format.
993xxxxxx is not a valid parameter name. An invalid parameter was included in the request. Some parameters are case sensitive.
For example: number as "NUMBER"
997PayTrace API only supports POST requests.All integration API requests should be of POST type to adhere to PCI requirements
998Log 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.
999Log in failed for insufficient permissions.The user account must have permission/access to process a sale.
1001Decryption failed.Encrypted request data should be encrypted with the merchant account-specific public key only.
9102-9185System 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:

  1. You have a valid account with API module enabled. PayTrace recommends testing in a Sandbox account prior to testing in a live environment.
  2. Make sure to set and be aware about your account security settings from the PayTrace Virtual Terminal.
  3. You server side code submits a valid authorization token in the expected format. See the Authentication section for more information.
  4. Your API requests should have at least the required request parameters to avoid errors.
  5. 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 TypeCredit Card Number*Expiration MM/YY
Visa401200009876543912/35
MasterCard549974000000005712/35
Discover601100099302690912/35
American Express37144963539237612/35

*Any valid expiration month and year will work as well.

Testing CSCs

Credit Card TypeCSC NumberResponse
Visa999Approval
MasterCard998Approval
Discover996Approval
American Express9997Approval

Testing Addresses for AVS Response

Address (street number)Zip CodeResponse Text
8320-Address Match
-85284Zip Match
832085284Exact Match
-99999Ver Unavailable

Testing Amount

AmountResponse Text
$0.00Amount Error
$0.01Call
$0.02Call
$0.05Hold - Call
$0.06Hold - Call
$0.07Hold - Call
$0.08Hold - Call
$0.20Decline
$0.21Decline
$0.22Decline
$0.23Decline
$0.24Decline
$0.25Decline
$0.26Decline
$0.29Expired Card
$0.39No Such Issuer
$0.41RE-ENTER
$0.43Serv Not Allowed
$0.44Serv Not Allowed
$0.48CVV Mismatch
$0.49Card OK
$0.50APPROVAL
$0.51Prompt for Level II Data
$0.53Prompt for Level 3 Data
$1.00 or moreAPROVAL
$1.12Decline
$1.13Decline
$11.11Partial Approval
$52.00Partial 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

  1. Send an authentication request with your API user credentials to generate an access token.
  2. Prepare the request using an access token and test data. Submit the request to one of the API methods.
  3. 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 :

  1. You can simply make a request to our API with your API account user credentials and get the Bearer access token.
  2. 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 Example
shell
curl 'https://api.paytrace.com/v3/token' -XPOST -H'Content-Type: application/x-www-form-urlencoded' -data-raw 'grant_type=client_credentials' -data-raw 'client_id=YourApiUsername' -data-raw 'client_secret=YourApiPassword'
Request Body
JSON
{
	"username": "YOUR USERNAME",
	"password": "YOUR PASSWORD",
	"grant_type": "client_credentials",
	"integrator_id": "YOUR INTEGRATOR ID"
}

Authentication Error Example

The following error response will be returned when sending incorrect user credentials with HTTP status code 401-Unauthorized.

Authentication Error
JSON
{
	"error": "invalid_grant",
	"error_description": "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."
}

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 Response
JSON
{
	"access_token": "4656d6f6132333:4656d6f6132333:2b607b9a44720c9c3ca867653c7e6ef8b3f3802709c17f2a54402820d155f214",
	"token_type": "bearer",
	"expires_in": 7200,
	"created_at": 1489710779
}

Each API request requires authentication via the access token described earlier.

Authentication Errors Summary

errorserror_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

  1. It will allow your customers to process transactions on your website.
  2. Your customers are not required to be redirected to another payment page.
  3. It provides your customers the comfort and security of processing payments on your website.
  4. 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

  1. Incorporate The PayTrace Client-Side Encryption Library in a web form.
  2. Get the encrypted field value with your server side code.
  3. 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.

  1. Setup: Include The PayTrace E2ee Library using script tag in a header section.
    Example
    HTML
    <head><script src='https://api.sandbox.paytrace.com/v3/assets/js/e2ee/paytrace-e2ee.js'></script></head>
  2. For the sensitive data fields that should be encrypted at the browser, add the "pt-encrypt" class.
    Example
    HTML
    <body><div id='cc-data'><input type='text' class='form-control pt-encrypt' id='ccNumber' name='ccNumber' placeholder='Credit card number'><input type='text' class='form-control pt-encrypt' id='ccCSC' name='ccCSC' placeholder='Card security code'></div></body>
  3. Submit a form with any of the following scenarios.
    1. Bind the submit event of the form to the PayTrace Client-Side E2ee Library.
      Example
      HTML
      <script>$(document).ready(function() {paytrace.setKeyAjax('https://api.sandbox.paytrace.com/v3/e2ee/public-key.pem');});</script>
    2. 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.
      Example
      HTML
      <script>$(document).ready(function() {paytrace.setKeyAjax('https://api.sandbox.paytrace.com/v3/e2ee/public-key.pem');});$('#myform').submit(function(e) {e.preventDefault();if ($(this).valid()) {paytrace.submitEncrypted(this);} else {console.log('INVALID FORM. Your code for further action here');}return false;});</script>

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

  1. It will allow your customers to process transactions on your website.
  2. It will allow your customers to safely and securely store their credit card information for future use.
  3. Your customers are not required to be redirected to another payment page.
  4. It provides your customers the comfort and security of processing payments on your website.
  5. Using Protect.js reduces your PCI scope and can help you qualify for PCI SAQ-A.

The PayTrace Protect.js Workflow

Paytrace Protect diagram

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.

  1. Setup: Include the JS library and div container tag for iframe on your website. Please refer to the code sample:
    Example
    HTML
    <!-- This is the PayTrace Protect.js library: --> 
    <script src='https://protect.paytrace.com/js/protect.min.js'></script> 
    <!-- This is the PayTrace Sandbox Protect.js library: --> 
    <script src='https://protect.sandbox.paytrace.com/js/protect.min.js'></script> 
    
    <!-- The JS Library then adds the iframe using this div container tag during setup -->
    <div id='pt_hpf_form'><!--iframe sensitive data payment fields inserted here--></div>

    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.

  2. 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.
    Example
    Shell
    grant_type=client_credentials&client_id=YourUserName&client_secret=YourPassword

    See the Authentication section for more information about how to generate an Oauth Token.

  3. 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.
    Example
    CURL
    POST 
    URL='https://api.paytrace.com/v3/payment_fields/token/create' 
    Content-Type: application/json 
    Authorization: Bearer "Auth Token in Step 2"
  4. Use the Protect authorization token to set up the payment form. Please refer to the code sample:
    Example
    HTML
    <script> 
    	// Minimal Protect.js setup call 
    	PTPayment.setup({ 
    		authorization: { clientKey: <clientKey> } 
    	}).then(function(instance){ 
    		//use instance object to process and tokenize sensitive data payment fields. 
    	});
    </script>

    By this point, you should be able to see the Protect.js iframe rendered on your webpage. See the example below:

    Paytrace sample payment form

    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.

  5. 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.
    1. 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:

      Example
      JS
      // this can be any event we chose. We will use the submit event and stop any default event handling and prevent event handling bubbling.
      document.getElementById("ProtectForm").addEventListener("submit",function(e){
      	e.preventDefault();
      	e.stopPropagation();
      	// To trigger the validation of sensitive data payment fields within the iframe before calling the tokenization process:
      	PTPayment.validate(function(validationErrors) {
      		if (validationErrors.length >= 1) {
      			if (validationErrors[0]['responseCode'] == '35') {
      				// Handle validation Errors here
      				// This is an example of using dynamic styling to show the Credit card number entered is invalid
      				PTPayment.style({'cc': {'border_color': 'red'}});
      			}
      		} else {
      			// no error so tokenize
      			instance.process()
      				.then( (r) => submitPayment(r) )
      				.catch( (err) => handleError(err) );
      		}
      	});// end of PTPayment.validate
      });
      // end of add event listener submit
    2. 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:

      Example
      JS
      // this can be any event we chose. We will use the submit event and stop any default event handling and prevent event handling bubbling.
      document.getElementById("ProtectForm").addEventListener("submit",function(e){
      	e.preventDefault();
      	e.stopPropagation();
      	// The tokenization process also validates the sensitive data payment fields
      	PTPayment.process() //call tokenization
      		.then( (r) => submitPayment(r) )
      		// submit nonce and cipher key to PayTrace Protect Servers to tokenize sensitive data payment fields
      		.catch( (err) => handleError(err) );
      		// handle unsuccessful tokenization failures
      	});
      // end of add event listener submit

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

Protect Sale

Processes a Sale transaction using the Protect.js UI.

Protect Sale and Create Customer

Processes a Sale transaction and creates a customer profile, upon transaction approval, using the Protect.js UI.

Protect Authorization

Processes an Authorization using the Protect.js UI.

Create Customer Profile Using Protect.js

Stores your customer’s billing and payment information, in PayTrace’s PCI-compliant Customer Database (Vault), using the Protect.js UI.

Update Customer Profile Using Protect.js

Modifies an existing customer profile, stored in PayTrace’s PCI-compliant Customer Database (Vault), using the Protect.js UI.

Successful Protect.js tokenization response
JSON
{
	"success": true,
	"message": {
		"hpf_token": "f519084b-db08-4e82-8670-9e690d9897cc",
		"enc_key": "84jkunZs5Ae4_tNaW3QtIIjaE08wyg70oJfA-gtm6aY="
	}
}

Protect.js validation error response
JSON
{
	"message": "Field Validation Error(s)",
	"reason": [
		{
			"description": "Please provide a valid Credit Card Number.",
			"responseCode": "35"
		},
		{
			"description": "Please provide a valid Expiration Month.",
			"responseCode": "43"
		}
	]
}

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

FieldDescription
codeCSC Input field
ccCredit card number input field
expExpiration date Input field
bodyBody of the iframe

NOTE: Only background_color can be modified.

Styling Options

OptionDescriptionAcceptable Values
background_colorBackground color of the text box or iframe CSS keyword or hexadecimal color value

Default color is 'white'
border_colorColor of textbox border CSS keyword or hexadecimal color value

Default color is 'black'
border_styleBorder style of the text box CSS keyword

Default style is 'solid'
font_colorFont color of input data CSS keyword or hexadecimal color value

Default color is 'black'
font_sizeFont size of input dataCSS units
heightHeight of text box CSS units

Will default to font_size if not provided
input_border_radius Border radius of text boxCSS units
input_border_width Border width of text boxCSS 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 labelCSS units
label_border_style Border style around payment field label CSS keyword

Default style is 'solid'
label_border_width Border width around payment field labelCSS units
label_colorColor 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_sizeSize of payment field labelCSS units
label_width Width of payment field labelCSS units
padding_bottom Padding added below input text boxCSS 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'
widthWidth of text boxCSS units

Static Styling Example

PTPayment.setup({
 styles:
  {
   'code': {
    'font_color':'#5D99CA',
    'border_color':'#EF9F6D',
    'border_style':'dotted',
    'font_size':'13pt',
    'input_border_radius':'10px',
    'input_border_width':'2px',
    'input_font':'serif, cursive, fantasy',
    'input_font_weight':'700',
    'input_margin':'5px 0px 5px 20px',
    'input_padding':'0px 5px 0px 5px',
    'label_color':'#5D99CA',
    'label_size':'16px',
    'label_width':'150px',
    'label_font':'sans-serif, arial, serif',
    'label_font_weight':'bold',
    'label_margin':'5px 0px 0px 20px',
    'label_padding':'2px 5px 2px 5px',
    'label_border_style':'dotted',
    'label_border_color':'#EF9F6D',
    'label_border_radius':'10px',
    'label_border_width':'2px',
    'background_color':'white',
    'height':'25px',
    'width':'110px',
    'padding_bottom':'2px'
   },
   'cc': {
    'font_color':'#5D99CA',
    'border_color':'#EF9F6D',
    'border_style':'solid',
    'font_size':'13pt',
    'input_border_radius':'20px',
    'input_border_width':'2px',
    'input_font':'Times New Roman, arial, fantasy',
    'input_font_weight':'400',
    'input_margin':'5px 0px 5px 0px',
    'input_padding':'0px 5px 0px 5px',
    'label_color':'#5D99CA',
    'label_size':'16px',
    'label_width':'150px',
    'label_font':'Times New Roman, sans-serif, serif',
    'label_font_weight':'light',
    'label_margin':'5px 0px 0px 0px',
    'label_padding':'0px 5px 0px 5px',
    'label_border_style':'solid',
    'label_border_color':'#EF9F6D',
    'label_border_radius':'20px',
    'label_border_width':'2px',
    'background_color':'white',
    'height':'25px',
    'width':'320px',
    'padding_bottom':'0px'
   },
   'exp': {
    'font_color':'#5D99CA',
    'border_color':'#EF9F6D',
    'border_style':'dashed',
    'font_size':'12pt',
    'input_border_radius':'0px',
    'input_border_width':'2px',
    'input_font':'arial, cursive, fantasy',
    'input_font_weight':'400',
    'input_margin':'5px 0px 5px 0px',
    'input_padding':'0px 5px 0px 5px',
    'label_color':'#5D99CA',
    'label_size':'16px',
    'label_width':'150px',
    'label_font':'arial, fantasy, serif',
    'label_font_weight':'normal',
    'label_margin':'5px 0px 0px 0px',
    'label_padding':'2px 5px 2px 5px',
    'label_border_style':'dashed',
    'label_border_color':'#EF9F6D',
    'label_border_radius':'0px',
    'label_border_width':'2px',
    'background_color':'white',
    'height':'25px',
    'width':'85px',
    'padding_bottom':'2px',
    'type':'dropdown'
   },
   'body': {
    'background_color':'white'
   }
  },
 authorization:
  {
   'clientKey': clientKey
  }
}).then(function(instance){
//use instance object to process and tokenize sensitive data payment fields.
});

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

MethodDescription
styleAllows 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.

Dynamic Styling Example

//PTPayment.getControl examples
PTPayment.getControl("securityCode").label.text("CSC");
PTPayment.getControl("creditCard").label.text("CC");
PTPayment.getControl("expiration").label.text("Exp Date");

//PTPayment.theme examples
PTPayment.theme('horizontal');
PTPayment.theme('above the line');
PTPayment.theme('below the line');
PTPayment.theme('label-none');
PTPayment.theme('label-extended-top');

//PTPayment.style examples
PTPayment.style({'cc': {'border_style': 'dashed'}});
PTPayment.style({'code': {'label_color': 'red'}});
PTPayment.style({'exp': {'type': 'textbox'}});
©2025 North is a registered DBA of NorthAB, LLC. All rights reserved. North is a registered ISO of BMO Harris Bank N.A., Chicago, IL, Citizens Bank N.A., Providence, RI, The Bancorp Bank, Philadelphia, PA, FFB Bank, Fresno, CA, Wells Fargo Bank, N.A., Concord, CA, and PNC Bank, N.A.