Introduction

The PayTrace API (Application Programming Interface) is a powerful software solution that enables any software developer to integrate the power of the PayTrace Payment Gateway into their proprietary software.  Software developers may use the PayTrace API to add payment-processing functionality into their software through the seamless integration of HTTPS Post requests.

Through the power and efficiency of the PayTrace API, your software applications may process electronic payments in real-time and receive payment authorizations within 3 to 6 seconds.  The PayTrace API is built to process transactions and recurring payments, store customer and transaction profiles and email receipts.

The PayTrace API uses HTTPS post with Requests and Responses.  This API does NOT need to be installed or registered on a web server or on a client's computer which is running the software application. Integrating with the PayTrace API is quick and easy with our 5-star Support.


JSON API

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 Endpoint

All API requests are made to https://api.paytrace.com and all requests are served over HTTPS using TLS 1.2.


API Version

The current version of the JSON API is v1.

Getting Started

Are you ready to get started with the PayTrace API?


Here are the steps you will need to follow to start integrating with the PayTrace API.


1

In order to obtain your integrator_id and begin testing your integration, you will need to sign up for a Sandbox Account.

To request a sandbox account, fill out the Sandbox Request Form located here: Sandbox Request Form


Once completed, your integrator_id and sandbox credentials will be provided to you within 1 business day.

2After receiving your sandbox credentials, you will need to configure your account to match your anticipated production account. In order to do so, you will need to login to PayTrace and select the Security Settings tab under the Account Tab. For more information regarding PayTrace’s Security Settings please see the Account Security settings here.

AccountSecuritySetting.png
3Refer to our API integration documentation provided in this knowledge base to learn about the integration with different methods of our API.
4Send an authentication request with your user credentials to generate an access token.
5Prepare the request using an access token and Test data. Submit the request to one of the API methods.
6
For API errors, Check out the PayTrace Virtual Terminal → integration → API log.  Look at the API Log for more details.

API_Logs.png
7Once you are done with your testing phase, you can go live by requesting an active account from the preferred PayTrace Reseller.
8To go live, you must have a PayTrace Professional account with the API Module enabled. The aforementioned user credentials can be used in the PayTrace Virtual Terminal to create a PayTrace API user account to use with the API.

Please Note: PayTrace uses the API user credentials instead of an API key for Authentication.
9Once your integration is complete, we recommend that your users use their API User Account credentials with your integration.
10Don't forget to take a look at the PayTrace Virtual Terminal→Account→Security settings(as shown in step 2 above) to configure the additional mandatory parameters for your individual live account.
After configuring any additional parameters in the Security Settings, you must also send those additional parameters to avoid API errors. Please look at your Account Security Settings for the API.

Please Note: If you do not see the Account → Security Settings option in the PayTrace Virtual Terminal, please contact your Account Administrator to enable this Account option in the Virtual Terminal.

API Parameters Summary

Are you looking for quick access to the Request and Response parameters used by all the requests?

Here is the list of all of the Request and Response parameters being used by the JSON API.

Each API method will also provide a list of the necessary Required and Optional parameters.
Level 3 line Item parameters will be provided within the appropriate API Methods.

Required Request Parameters
AttributeDescriptionData TypeLength
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.number1-12
billing _address*Billing address registered with the customer's credit card.
For supported Schema, Click here Billing_Address Schema.

This object is only required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.
Object-
credit_cardCredit card details including number, expiration month and year.
For supported Schema, Click here Credi_Card Schema.
object-
csc* or encrypted_csc*CSC is the 3 or 4 digit code found on the signature line of the credit card. For Amex cards, the CSC is found on the front of the card.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.

This attribute is only required if the "Required CSC" field is enabled in the PayTrace Virtual Terminal→ Account → Security Settings page.
string3-4
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.

Note: This id should be an existing customer id in the PayTrace Vault to avoid API errors.
string
Data Format
1-25
hpf_tokenA one time nonce representing the senstitive credit card data collected by the Protect.js UI.string1-50
enc_keyUnique cipher key provided by the Protect.js UI.string1-50
emv_dataA string of data from a credit card chip provided by the IDTech EMV card reader.

This field is also used for FallBack Swipe data in the event that a fallback is triggered.
string255+
end_dateThe end date is used to indicate when to end searching for transactions to export.
It must be a valid date formatted as MM/DD/YYYY.
string10
integrator_idA unique ID to correlate an API consumer calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
string
12
invoice_id*A unique identifier for this transaction in your accounting or inventory management system.
This attribute is only required if the "Require Invoice" field is enabled in PayTrace Virtual Terminal → Account → Security Settings page.
string
Data Format
1-50
new_passwordA new password to be updated.string
Data Format
7-50
start_dateThe start date is used to indicate when to start searching for transactions to export.
It must be a valid date formatted as MM/DD/YYYY.
string10
swipe or encrypted_swipeA string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2.

Use encrypted_swipe when submitting encrypted swipe values by the PayTrace Client-Side Encryption JavaScript Library.
string
Data Format
255+
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: This should be in reference to a legitimate transaction within the  PayTrace system, processed in the past to avoid any API errors.
number1-9

* Request parameters are configurable from the PayTrace Virtual Terminal → Account → Security Settings page. Request parameters must be provided with the request (If request parameters are configured in the PayTrace Virtual Terminal) or API errors will occur.


Optional Request Parameters
AttributeDescriptionData TypeLength
batch_numberA batch number used to find specific batch details. This value is the sequential number assigned to the batch.number1-3
createdTransaction created date or batch created date or customer creation details.
For supported Schema, Click here Request_Creation_Record Schema.
object-
custom_dbaAn optional value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.string
Data Format
1-25
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.string
Data Format
1-17
descriptionOptional 255 max, alpha-numeric character text describing the transactions, products, customers, or other attributes of the transaction.string
Data Format
1-255
emailCustomer's email address where the Sales/Authorizations/Refunds receipt may be sent.string
Data Format
1-50
enable_partial_authorizationA flag that must be set to true in order to support partial authorization and balance amounts in transaction responses.
PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
boolean-
faxThe customer's fax number (i.e. 555-555-5555, or 5555555555).string
Data Format
10,12,13
include_binIf set to true, this will return the first 6 and last 4 digits of the card number.boolean-
including_textThe text submitted will be used to locate transactions containing this text, to narrow down the export results.string
Data Format
1-255
new_idA new unique identifier for a customer profile that may be sent with a request to update a customer profile.string1-25
phoneThe customer's phone number (i.e. 555-555-5555, or 5555555555).string
Data Format
10,12,13
recurrenceRecurrence Payment detail. For supported Schema, Click here Recurrence_Record Schema.object-
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.boolean-
shipping_addressThe customer's shipping address detail.
For supported schema, click here Shipping_Address Schema.
object-
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.number1-12
transaction_typeThe transaction type to find transactions.
Possible values: SALE, AUTHORIZATION, REFUND, VOID,
CAPTURE, FORCE, SETTLED, PENDING, DECLINED.
string4-13
discretionary_datafuture enhancement coming soon!


Response Parameters
AttributeDescriptionData TypeLength
successThis flag will indicate if the request is successful.
Possible values: true/false.
True indicates that the request was successful and no were no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean-
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for the possible valuesnumber3-4
status_messageStatus message about the request and provides additional information about the request execution end result.string1-255
approval_codeThis approval code is generated by the credit card issuer and returned with a successful transaction.string
Data Format
6
approval_messageA response from the credit card issuer with a successful requested transaction.string
Data Format
1-255
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
Data Format
1-255
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.
The card security code response is generated by the credit card issuer when a successful call to process any type of transaction is requested. The CSC provided with the request, is compared to the CSC assigned to the credit card. Check out possible AVS responses.
string
Data Format
1-255
emv_detailsAn array containing details of the EMV transaction.
For emv_details supported Schema, Click here emv_details Schema.
array of an object/objects-
transaction_idA unique identifier for each transaction in the PayTrace system.number1-9
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string
Data Format
1-50
masked_card_numberThe credit card number with all digits masked and replaced with 'x' except the last 4 digits.

This parameter will be returned in the JSON response only when the Credit Card number is one of the request parameters.
string
Data Format
15, 16, 19
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as what is provided with the request.string
Data Format
1-25
customersAn array of customer profiles.
For Customer profile supported Schema, Click here Customer_Record Schema.
array of an object/objects-
batchThis object contains details about the batch.
Note: For the supported Schema, Click here Batch_Record Schema
object-
batchesAn array of batch summary records.
For the supported Schema, Click here Batch_Summary_Record Schema
array of objects-
recurrenceFor the supported Schema, Click here Recurrence_Record Schema.
Note: Only the id will be returned on the successful creation of a recurring payment.
object-
recurrencesAn array of Recurrence Record objects. This parameter is used with the Export recurring transactions method.
For supported Schema, Click here Export_Recurrence_Record Schema.
Note:
If the Request parameter is a recurrence id, you will get an array of single recurrence transaction records.
If the Request parameter is a customer id, you will get an array of one or more transaction records.
array of objects-
transactionsAn array of transaction detail records within a batch report.
Note: The transaction records will not include discretionary data.
For supported Schema, Click here Transaction_Record Schema.

An array of transaction detail record objects for the given date range or a single transaction.
Note: These transaction details contains discretionary data.
For supported Schema, Click here Transaction_Detail_Record Schema
array of objects-
createdTransaction/Batch/Customer record creation details.
For supported Schema, Click here Response_Creation_Record Schema.
object-
next_dateThe next date when a recurring transaction is scheduled to occur.
The format will be MM/DD/YYYY.
string10
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.string
Data Format
1-255
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.number1-12
discretionary_dataDiscretionary_data details.
For the supported Schema, Click here Discretionary_Data Schema.
object-


Data Format
String with the combination of numbers and alphabets (including lower case and upper case).

Schema

Here are the Schemas, used by the JSON API



Credit_Card Schema
AttributeDescriptionTypeAttribute Requirement
number or
encrypted_number or
masked_number*
The customer's credit card number must be a valid credit card number that your PayTrace account is set up to accept.

Use the encrypted_number attribute when submitting encrypted credit card numbers by the PayTrace Client-Side Encryption JavaScript Library

Note: masked_number* is a response attribute that is returned with the Export Customer Profile (Vault) and Reporting API methods.
stringRequired
expiration_month2-digit expiration monthstringRequired
expiration_year2-digit or 4-digit expiration yearstringRequired




Billing_Address Schema
AttributeDescriptionTypeAttribute Requirement
nameName that appears on the credit card.stringOptional

Note:Required for ACH payment methods
street_addressStreet of the Billing Address that is on file for the cardholder's account.
This attribute is only required if the "Require Billing Address" field is enabled on the PayTrace Virtual Terminal→ Account→ Security Settings page.
stringRequired if configured
street_address2The second line of the Street Billing Address that is on file for the cardholder's account.stringOptional
cityCity of the Billing Address that is on file for the cardholder's account.stringOptional
stateState of the Billing Address that is on file for the cardholder's account.stringOptional
zipZIP code of the Billing Address that is on file for the cardholder's account.
This attribute is only required if the "Require Billing ZIP" field is enabled on the PayTrace Virtual Terminal→ Account→ Security Settings page.
Note: International ZIP codes require the country attribute.
stringRequired if configured
country2-digit ISO-3166-2 Country Code of the Billing Address that is on file for the cardholder's account.
Note: International ZIP codes require this attribute.
stringOptional




Shipping_Address Schema
AttributeDescriptionTypeAttribute Requirement
nameName of the person where the product is to be delivered.stringOptional
street_addressAddress where the product is to be delivered.stringOptional
street_address2The second line of the address where the product is delivered.stringOptional
cityCity where the product is to be delivered.stringOptional
stateState where the product is to be delivered.stringOptional
zipZIP code where the product is to be delivered.stringOptional
country2-digit ISO-3166-2 Country Code of where the product is delivered.stringOptional




Request_Creation_Record Schema
AttributeDescriptionTypeAttributes Requirements
byThe user name of the PayTrace user who has created the customer you are trying to export.stringRequired




Response_Creation_Record Schema
AttributeDescriptionType
throughPayTrace API or Virtual terminal that originally requested the customer profile or transaction be created or processed.string
atThe date and time when the transaction was first processed or the customer profile was created or batch was initiated/processed. The format will be a general date (i.e. MM/DD/YYYY HH:MM: SS)string
byThe PayTrace username who created the transaction or customer profile you are trying to export.string
from_ipThe IP address of the computer that originally requested the customer profile or transaction be created or processed.
The format will be a standard IP address (I.e. 111.111.111.111).
string




Discretionary_Data Schema

Note: 

Please make sure you have discretionary data defined with your merchant account. Check out Discretionary Data for more details.

* Please replace the attribute names with your account-specific discretionary data field names (Titles).

AttributeDescriptionType
Custom Discretionary Field Name1 *A field value stored in Custom Discretionary Field 1 of customer profile or transaction at PayTrace.string
Custom Discretionary Field Name2 *A field value stored in Custom Discretionary Field 2 of customer profile or transaction at PayTrace.string
Custom Discretionary Field Name3 *A field value stored in Custom Discretionary Field 3 of customer profile or transaction at PayTrace.string
Custom Discretionary Field Name4 *A field value stored in Custom Discretionary Field 4 of customer profile or transaction at PayTrace.string
Custom Discretionary Field Name5 *A field value stored in Custom Discretionary Field 5 of customer profile or transaction at PayTrace.string
Custom Discretionary Field Name6 *A field value stored in Custom Discretionary Field 6 of customer profile or transaction at PayTrace.string




Customer_Record Schema
AttributeDescriptionType
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.string
credit_cardFor the supported schema, Click here Credit_Card Schema.object
billing _addressFor the supported schema, Click here Billing_Address Schema.object
shipping_addressFor the supported schema, Click here shipping_address Schema.object
checkCheck the account detail. For the supported Schema, Click here Check Schema.
Note: This object will be included ONLY when the customer has check data.
object
emailCustomer's email address where the transaction receipt may be sent.string
phoneCustomer's phone number (i.e. 555-555-5555, or 5555555555).string
faxCustomer's fax number (i.e. 555-555-5555, or 5555555555).string
createdCreation record information for the customer profile. For the supported Schema, Click here Response_Creation_Record Schema.object
discretionary_dataDiscretionary_data details. For the supported Schema, Click here Discretionary_Data Schema.object




Transaction_Detail_Record Schema

This schema is associated with Export Transaction methods.

AttributeDescriptionType
transaction_idA unique identifier for each transaction in the PayTrace system.string
credit_cardFor the supported Schema, Click here Credit_Card Schema.object
transaction_typeThe transaction type.
Possible values: SALE, AUTHORIZATION, REFUND, VOID,
CAPTURE, FORCE, SETTLED, PENDING, DECLINED.
string
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.string
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.number
invoice_idA unique identifier for this transaction in your accounting or inventory management system.string
shipping_addressFor the supported schema, click here shipping_address Schema.object
billing_addressFor the supported Schema, Click here Billing_Address Schema.object
receipt_emailed_toCustomer's email address where the Authorization receipt may be sent.string
tax_amountA portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.string
customer_reference_idCustomer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. It is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.string
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageA transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
status_codeA code that shows the current status of the transaction.Possible values that status contains :
-GB or Settled indicates the transaction has been settled, and the batch number will be appended to the status.
-Y indicates the transaction will be settled that evening.
-N indicates the transaction was voided or declined.
string
status_messageA short message that shows the current status of the transaction for the settlement.string
createdTransaction creation details.
For supported schema, click here Response_Creation_Record Schema.
object
settledThe date and time when the transaction was settled/batched. Format will be a general date (i.e. MM/DD/YYYY HH:MM: SS)string
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.string
discretionary_dataDiscretionary_data details. For supported Schema, Click here Discretionary_Data Schema.object




Batch_Record Schema
AttributeDescriptionType
numberThis value is the sequential number assigned to the initiated settlement batch.
Note: This parameter can only be used as a request parameter for some methods.
number
american_expressAmerican Express Card details. For the supported schema, Click here Batch_Cards Schema.object
diners_clubFor the supported schema, Click here Batch_Cards Schema.object
discoverDiscover Card details. For the supported schema, Click here Batch_Cards Schema.object
master_cardMaster Card details. For the supported schema, Click here Batch_Cards Schema.object
private_labelFor the supported schema, Click here Batch_Cards Schema.object
visaVisa Card details. For the supported schema, Click here Batch_Cards Schema.object
SettledSettled represents the date when the batch was settled. The date format will be: MM/DD/YYYYstring




Batch_Cards Schema
AttributeDescriptionType
salesThe total number of sales (count) that were settled in the exported batch with a specific card type.number
collectedThe total sum of the sales amounts that were settled in the exported batch with a specific card type.number
refundsThe total number of refunds(count) that were settled in the exported batch with a specific card type.number
refundedThe total sum of refund amounts that were settled in the exported batch with a specific card type.number




Batch_Summary_Records Schema
AttributeDescriptionType
numberA sequential number assigned to the settlement batch.number
createdBatch creation details.
Note: Only the at attribute will be returned with a date.
For supported schema, click here Response_Creation_Record Schema.
object
transaction_countThe total number of transactions included in the batch for this settlement request.number
net_amountThis value is the net amount (sales minus refunds) of the initiated settlement batch.number
sales_countThe total number of sales included in a batch.number
sales_amountThe total amount of sales included in a batch.number
refund_countThe total number of refunds included in a batch.number
refund_amountThe total amount of refunds included in a batch.number




Transaction_Record Schema
AttributeDescriptionType
transaction_idA unique identifier for each transaction in the PayTrace system.string
credit_cardFor the supported Schema, Click here Credit_Card Schema.object
transaction_typeThe transaction type to find transactions.
Possible values: SALE, AUTHORIZATION, STR/FWD, REFUND, VOID,
CAPTURE, FORCE, SETTLED, PENDING, DECLINED.
string
descriptionOptional 255-character max text describing the transactions, products, customers, or other attributes of the transaction.string
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.number
invoice_idA unique identifier for this transaction in your accounting or inventory management system.string
shipping_addressFor the supported schema, Click here shipping_address Schema.object
billing_addressFor the supported Schema, Click here Billing_Address Schema.object
receipt_emailed_toThe customer's email address where the Authorization receipt may be sent.string
tax_amountA portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax exempt.string
customer_reference_idCustomer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. It is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.string
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
status_codeA code that shows the current status of the transaction. The possible values that this  status may contain:
-GB or Settled indicates the transaction has been settled, and the batch number will be appended to the status.
-Y indicates the transaction will be settled that evening.
-N indicates the transaction was voided or declined.
string
status_messageA short message that shows the current status of the transaction for the settlement.string
createdTransaction creation details.
For supported schema, Click here Response_Creation_Record Schema.
object
settledThe date and time when the transaction was settled/batched. The format will be a general date (i.e. MM/DD/YYYY HH:MM: SS)string
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.string




Recurrence_Record Schema

 id will be the only return paramter with Create, Update and Delete Methods for this schema.

AttributeDescriptionTypeAttribute Requirement
idA unique identifier for a recurring payment.

Note: This id will be used as a request parameter for recurring payment Update, Delete and Export methods only.
Note: This parameter will be a returned when a successful recurring payment is created, updated or deleted.
numberRequired for Update,
Delete and Export methods.
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberRequired for Create Method
Optional for Update Method
customer_receiptA boolean flag to set if you would like to send a receipt to the Customer's registered email.
false - Default value. Not to send the transaction receipt.
true - to send the transaction receipt.

Note:
Returns an error if the flag is set to true and no email address is registered with the customer profile.
booleanRequired for Create Method
Optional for Update Method
frequencyThe billing cycle of the recurring transaction. Possible values are :
1 - annually
8 - semi-annually
A - trimesterly
2 - quarterly
9 - bi-monthly
3 - monthly
4 - bi-weekly
7 - 1st and 15th
5 - weekly
6 - daily.
stringRequired for Create Method
Optional for Update Method
start_dateThe date the recurring transaction should be processed for the first time. The format will be MM/DD/YYYY.stringRequired for Create Method
Optional for Update Method
total_countThe total number of times the recurring transaction should be processed.
Use 999 if the recurring transaction should be processed indefinitely.
stringRequired for Create Method
Optional for Update Method
transaction_typeThe type of transaction you wish to process.
Possible values: Sale or Authorization.
stringRequired for Create Method
Optional for Update Method
typeThe payment type (Credit Card or ACH), that is stored on the customer profile, and should be used for this recurring transaction.
The default value is "C" which represents credit card.
The alternative is "A" which represents an ACH/check transaction.
stringOptional for Create Method
Required for Update Method
if ACH/Check recurring payment
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.stringOptional




Export_Recurrence_Record Schema
AttributeDescriptionType
idA unique identifier for a recurring payment. This id will be used as a request parameter for recurring payment update, delete and export methods only.
Note: This parameter will be returned when a successful recurring payment is created, updated or deleted.
number
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.number
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.string
next_dateThe next date when a recurring transaction is scheduled to occur. The format will be MM/DD/YYYY.string
total_countThe total number of times the recurring transaction should be processed.
It will be 999 if the recurring transaction should be processed indefinitely.
number
current_countThe number of times this payment has been processed in context to the total number of the scheduled payments.
The payment will be completed when the current count is equal to the total count unless the total count is set to 999 (infinite).
number
repeat_countThe number of the days after a decline that the payment should be retried.number
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.string




Check Schema
AttributeDescriptionTypeAttribute Requirement
account_numberThe checking account number for processing check transactions or managing customer profiles.numberRequired
routing_numberThe routing number for processing check transactions or managing customer profiles.numberRequired
masked_account_numberA masked checking account number for processing check transactions or managing customer profiles.
Note: This parameter will be returned with export check transaction requests instead of the plain account number.
stringNA
masked_routing_numberA masked Routing number for processing check transactions or managing customer profiles.
Note: This parameter will be returned with export check transaction requests instead of the plain routing number
stringNA




Check_Transaction_Detail_Record Schema

This schema is associated with Export Check Transaction methods.

AttributeDescriptionType
check_transaction_idA unique identifier for each check transaction in the PayTrace system.number
checkAccount detail. For supported Schema, Click here Check Schema.
Note: A masked parameter will be used for check account details.
object
check_typeThe check type.
Possible values: SALE, HOLD, REFUND,
VOID, SETTLED, PENDING.
string
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.string
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.number
invoice_idA unique identifier for this transaction in your accounting or inventory management system.string
shipping_addressFor the supported schema, click here shipping_address Schema.object
billing_addressFor the supported Schema, Click here Billing_Address Schema.object
receipt_emailed_toThe customer's email address where the Authorization receipt may be sent.string
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax exempt.string
customer_reference_idThe customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. It is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.string
status_codeA code that shows the current status of the transaction. Possible values this status may contain:
-GB or Settled indicates the transaction has been settled, and the batch number will be appended to the status.
-Y indicates the transaction will be settled that evening.
-N indicates the transaction was voided or declined.
string
createdTransaction creation details.
For the supported schema, click here Response_Creation_Record Schema.
object
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.string
discretionary_dataDiscretionary_data details. For the supported Schema, Click here Discretionary_Data Schema.object




EMV_Details Schema
AttributeDescriptionType
AIDEMV Tag data provided by EMV Readerstring
TVREMV Tag data provided by EMV Readerstring
IADEMV Tag data provided by EMV Readerstring
TSIEMV Tag data provided by EMV Readerstring
ARCEMV Tag data provided by EMV Readerstring

API Sample Code

The following sample code is available in GitHub.

Authentication

The PayTrace JSON API requires authentication and authorization in order to make all of the requests.  The PayTrace JSON API uses OAuth 2.0 for Authentication and Authorization.

OAuth 2.0 provides a "password" 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 Request Header settings, click here Request Header settings.
Each API request requires authentication via the access token described earlier (except for an Authentication request as described below).     

Request URL

Post
/oauth/token

Request Header Settings
HeaderValue
Accept*/*
HTTP ProtocolHTTP/1.1
Content-Typeapplication/x-www-form-urlencoded; charset=UTF-8

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirement
usernamePayTrace API UsernamestringRequired
passwordPassword for PayTrace APIstringRequired
grant_typeThe grant type for this flow is passwordstringRequired

Optional Attributes: None


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.


Response Attributes
AttributeDescriptionType
access_tokenThe access token issued by PayTrace. The access token will expire (see expires_in), after which you will have to request a new access token.string
token_typeThe type of the token issued.string
expires_inThe lifetime in seconds of the access token.number
created_atToken creation time in Epoch time format.number

Errors with Authentication

The error responses will include an HTTP status code and JSON body.  In general, code 4XX and 5XX ranges indicate some failure for an authentication token request.

Specific JSON error responses will be returned to provide authentication error details.  Here is the Authentication error Response attributes detail.  Check out API Errors for HTTP status codes.


Authentication Error Response Attributes
AttributeDescriptionType
errorA unique identifier for an error. Please refer to Authentication Errors Summary to find all values.string
error_descriptionAn error message providing details about the error. Please refer to Authentication Errors Summary to find all values.string

Authentication Errors Summary
errorserror_description
invalid_grantThe 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_tokenDepending 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_typeThe authorization grant type is not supported by the authorization server.
invalid_resource_ownerThe provided resource owner credentials are not valid, or resource owner cannot be found.
invalid_requestThe request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed.
invalid_clientClient authentication failed due to an unknown client, no client authentication included, or unsupported authentication method.
access_deniedThe resource owner or authorization server denied the request.
invalid_scopeThe requested scope is invalid, unknown, or malformed.
server_errorThe authorization server encountered an unexpected condition which prevented it from fulfilling the request.
temporarily_unavailableThe authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Authentication Error Example

For example, If you pass incorrect API user credentials, you will get an error Response with the appropriate error and error description with an HTTP status code 401-unauthorized.

How to utilize 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

Authentication format is Bearer access_token

Bearer and access_token should have a space between them {Bearer access_token} as shown in Authentication Header format and it's example.     

Request Header

Please note that following Request Header settings remain consistent through all API Methods except Authentication Token request.    
Header Value
Authorization {Bearer access_token } generated from OAuth Authentication request.
For more information, click here : Authentication

Example:
Bearer 4656d6f6132333:4656d6f6132333:2b607b9a4
4720c9c3ca867653c7e6ef8b3f3802709c17f2a54402820d155f214
Content-Type application/json
Cache-Control no-cache

API Endpoint

https://api.paytrace.com

API 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 it's value.

The response_code will contain one of the following codes with an associated status _message.

Please note that Response codes may change periodically, so it is important to review this page for the updates.   

API Response codes
Response CodeStatus MessageReason
1One more errors has occurred.

For all Reports and Exports : Your request has been successfully completed.
Returned when a one or more error occurred and Transaction has not been processed. You will need to check.

For all Reports and exports : Returned when request is successful and requested data is exported.
100Your password was successfully updated.Returned when a request to Update Password is successfully processed.
101Your transaction was successfully approved.Returned when a request to process a sale or authorization transaction generates an approved transaction.
102Your transaction was not approved.Returned when a request to process a sale or authorization transaction does not generate an approved transaction.
103Your transaction was successfully approved. However, it was voided because your address and/or CSC did not match.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.
106Your transaction was successfully refunded.Returned when a request to process a refund generates an completed transaction.
107Your transaction was not successfully refunded.Returned when a request to process a refund does not generate a completed transaction.
108Your TEST transaction was successfully refunded HOWEVER, NO FUNDS WILL BE REFUNDED.Returned when a request to process a TEST refund transaction generates a completed transaction.
109Your transaction was successfully voided.Returned when a request to void a transaction generates a voided transaction.
110Your transaction was not successfully voided.Returned when a request to void a transaction does not generate a voided transaction.
112Your transaction was successfully captured.Returned when a request to capture a transaction generates a captured transaction.
113Your transaction was not successfully captured.Returned when a request to capture a transaction does not generate a captured transaction.
120Your check was successfully processed.Returned when a request to process a sale or hold check is successful.
122Your check was successfully refunded.Returned when a request to refund a check is successful.
124Your check was successfully managed.Returned when a request to manage a check for void or fund is successfully processed.
125Your check was NOT successfully 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.
149The receipt for transaction ID ######## was successfully emailed to email address.Returned when a request to email a receipt is successfully processed.
150The recurring transaction was successfully created.Returned when a request to create a recurring payment is successfully processed.
151The recurring transaction was successfully updated.Returned when a request to update a recurring payment is successfully processed.
152The recurring transaction was successfully deleted.Returned when a request to delete a recurring payment is successfully processed.
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.
160The customer profile for customer ID/customer Name was successfully created.Returned when a request to create a customer profile is successfully processed.
161The customer profile for customer ID/customer Name was successfully updated.Returned when a request to update a customer profile is successfully processed.
162The customer profile for customer ID/customer Name was successfully deleted.Returned when a request to delete a customer profile is successfully processed.
165Your transaction was successfully approved and customer profile is created.Returned when the request to process a sale transaction generates an approved transaction and customer profile is created.
167Your transaction was successfully approved. However, the requested customer profile could not be created.Returned when the request to process a sale transaction generates an approved transaction, however the requested customer profile already exists and thus could not be created.
170Visa level 3 was successfully added to Transaction ID ######. ### line items were created.Returned when a request to add level 3 data is successful for a Visa transaction.
171MasterCard level 3 was successfully added to Transaction ID ######. ### line items were created.Returned when a request to add level 3 data is successful for a MasterCard transaction.
175The 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.
180The transaction amount was successfully adjusted.Returned when a request to adjust a transaction amount is successfully processed.

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 chargeback 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
Info!
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.

API Errors

PayTrace 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 card/transaction is declined.  Codes in the 5XX range indicate an error with PayTrace servers.

With API error response, you will need to check success and response_code Parameters.  Then you will need to check for the error codes.  Check out API Response code and API Error Codes for all possible values.

Error response will be returned with following scenarios.


Declined Transaction

With this scenario, transaction does not succeed due to processing networks errors or if card is declined due to any other reasons.

In that case, checking a HTTP status code, success and response_code parameters would be recommended.  You will need to check the avs_response and csc_response to avoid any credit card related fraud.

Please check out API Response code and AVS and CSC response for possible values.

There will be few additional parameters in the JSON response based on the request.  Sample Error response of declined (unsuccessful) transaction is provided with each individual API methods.


Error with the input/request parameters

With this scenario, transaction fails due to invalid parameters values/names, required parameters not provided, duplicate values etc.  In that case, Additional errors object will be returned with respective error codes and error messages.  Please refer the Sample Error Response.

Check out API Error Codes to get possible error codes and associated error messages.

API can return multiple error codes with associated Error messages. So we recommend you to have your code gracefully handle those error codes and messages.   

Any invalid input parameters will return an error.  For Example, If you send an invalid Credit Card number and expiration Month i.e. any numbers other than 1 to 12.

masked_card_number will be a included within JSON response only when credit card number is one of the request parameters.   

Here is a list of HTTP status code with PayTrace API.


API HTTP Status Codes
Http Status codeReason
200-OKRequest worked as expected.
400-Bad RequestAny invalid Request parameters/values, Required parameters are missing or a declined transaction.
401-UnauthorizedWhen access token is invalid or expired.
500-Internal server errorsError with PayTrace servers.

API Logs From PayTrace Virtual Terminal

If you have an access to PayTrace Virtual Terminal, you can view API errors, occurred during particular time period from Virtual terminal → Integration → API log Menu.  Please select the time period to view the API logs.

API Error Codes

The additional errors object will be included when an input parameter is missing or invalid.

Here are the API error codes and associated messages with possible scenarios.


         

API Error Codes
Error CodeError MessageReason
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.
80The 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.
81The 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.
85The 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.
86The 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.
87The 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.
88The 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.
89The 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.
90The 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 TitleDiscretionary 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.
140Dynamic 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.
172Please 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.
700This 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 networkIf 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 networkIf 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 networkIf 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 networkIf a forced sale request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor.
740PayTrace 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.
777PayTrace 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.
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 youTransaction 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.
816The 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.
817The 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.
818The 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.
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: valueReturned 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 PayTrace 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" , encrypted_csc as "ENCRYPTED_CSC"
997PayTrace API only supports POST requests.All integration API requests should be of POST type to adhere to PCI requirements
998Log in failedAn 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-185System 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 & Integration, Make sure to check following:

  1. You have a valid account with API module enabled.   Sandbox user account will work too.
  2. Make sure to set & be aware about your Account security settings from PayTrace Virtual Terminal.
  3. You server side code submits valid authorization token in expected format.  Check out Authentication for more information.
  4. Your API requests should have at least required request parameters to avoid errors.
  5. Your code can handle HTTP Errors and API errors gracefully.  Check out API Errors for more information.

Test Data

You can use our test data during initial integration and API testing phase.


Testing Credit Cards
Credit Card TypeCredit Card Number*Expiration MM/YY
Visa401200009876543912/20
MasterCard549974000000005712/20
Discover601100099302690912/20
American Express37144963539237612/20

*Any valid expiration month and year will work too.


Testing CSCs
Credit Card TypeCSC NumberResponse
Visa999Approval
MasterCard998Approval
Discover996Approval
American Express9997Approval

Testing Addresses for AVS Response

You can use any street name with the combination of following street number and zip code.

Check out all AVS and CSC responses.

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

Testing Amount

$1.00 or more amount should give an approval response.

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 moreAPPROVAL
$1.12Decline
$1.13Decline
$11.11Partial Approval
$52.00Partial Approval

Testing ACH
Checking account numberRouting number
123456325070760

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 our 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.

Client-Side Encryption Library

The PayTrace Encryption 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 Encryption Library. The encrypted data can only be decrypted by PayTrace. The merchant or the integrator has no access to the original sensitive data.


The benefits of using The PayTrace Client-Side Encryption 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

The PayTrace Client-Side Encryption Library Workflow

PayTrace_Javacsript_Diagram.png

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 your PayTrace account and 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. Get your account specific public key and save it to your environment.
  2. Incorporate The PayTrace Client-Side Encryption Library in a web form.
  3. Submit the encrypted values to the API.

How to get a public Key

  1. Log into your PayTrace Account or Sandbox Account from the PayTrace Virtual Terminal.
  2. Go to the Integrations Menu → Download Public Key Page
  3. This Page will allow you to save the .PEM file/Public Key for your PayTrace Account.

How to incorporate The PayTrace Client-Side Encryption Library in a web form

The following steps are required to utilize The PayTrace Client-Side Encryption Library in a web form.
A public key, as described above, must be completed before moving forward.

1. Include The PayTrace encryption library using script tag in a header section.

     Please refer to the code section Sample →

2. For the sensitive data fields that should be encrypted at the browser, add the pt-encrypt class.

     The encrypted value of the field will be submitted to your server using the name attribute of the input element. 

     You can access the encrypted values using the name attribute on the server.  Please refer to the code section sample

3. Submit a form with any of the following scenarios.

3.1 Bind the submit event of the form to the PayTrace Client-Side Encryption Library as shown in the code section

       (Please provide the appropriate URL of 'YourPublicKeyFile.pem' if it is on different server.)

OR

3.1 Submit a valid form to the PayTrace Client Side Encryption Library.

       You will need to validate your form with your own implementation first and then submit the valid form.  As long as you set the key before a valid form is submitted, it should work.  Please refer the code section sample →

How to submit encrypted values to the API

Once you have received the encrypted values, you will then submit them using an API Request. In order to prompt the API to accept the encrypted values, you will need to prepend encrypted_ to the Number and CSC parameters within the request.

For example, the credit card number will be encrypted_number, the CSC will be encrypted_csc and the swipe will be encrypted_swipe to send the encrypted values to the API.

Please refer to the Keyed Sale request using the encrypted_number and the encrypted_csc in the code section.

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

PayTrace_Javacsript_Diagram.png

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.

1. Setup: Include JS library and div container tag for iframe on your website.

     Please refer to the code section Sample →

     This step allows the PTPayment object to become available when the Protect library script is sourced in the web application. See available PTPayment methods below:


Toggle PTPayment Methods
MethodDescription
processValidates and tokenizes Hosted Payment Field Data
setupInitializes the Protect.js Hosted Payment Fields within iframe using the clientkey in step 3.

Styling options can be statically applied during the setup call. For more information regarding our styling options, see Styling Options.
validateValidates Hosted Payment Field input prior to tokenizing data.

Takes function as an arguement. See example 5.1
resetClears Hosted Payment Fields and resets Protect.js to its beginning state.

2. Get authorization for application to use JSON API

     Make 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.

     See  Authentication for a reference on how to generate an Oauth Token.

3. Use the JSON API Authorization token to get authorization to use Protect

     Using the API AUTH TOKEN from step two as the authorization header, make a JSON API POST request to:  https://api.paytrace.com/v1/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.

     Please refer to the code section for request and response samples→

4. Use the Protect authorization token to setup the 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 option, see Styling Options.

     Please refer to the code section for Sample→

5. Bind submit event to event handler for tokenization of sensitive data

     The process method will tokenize the sensitive data in the payment fields. The method returns a 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.

5.1 Validate 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 Styling Options.

     For a list of potential validation errors, see Validation Error Responses below.

     Please refer to the code section for Sample→

OR

5.2 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 Styling Options.

     For a list of potential validation errors, see Validation Error Responses below.

     Please refer to the code section for Sample→

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 CodeDescriptionReason
35Please provide a valid Credit Card Number.The Credit card Number was invalid or not provided.
43Please provide a valid Expiration Month.The expiration Month was invalid or not provided.
44Please provide a valid Expiration Year.The expiration Year was invalid or not provided.
148Please provide a valid CSC. Must be 3 to 4 digits.The CSC/CVV value was invalid.
400Varies based on validation errorIn the case that an error occurrs in which a general use case is not covered, this response code will be thrown with a discription 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.

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.

Please refer to the code section for an example of Static Styling


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 iframeCSS keyword or hexadecimal color value

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

Default color is 'black'
border_styleBorder style of the text boxCSS keyword

Default style is 'solid'
font_colorColor of font text within textboxCSS keyword or hexadecimal color value

Default color is 'black'
font_sizeFont size of input dataCSS units
label_colorColor of payment field labelCSS keyword or hexadecimal color value

Default color is 'black'
label_sizeSize of payment field labelCSS units
typePayment 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'
heightHeight of text boxCSS units

Will default to font_size if not provided
widthWidth of text boxCSS units

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.

Please refer to the code section for examples of dynamic Styling


Dynamic Styling Methods
MethodDescription
styleAllows you to modify any of the input field styling options.
themeAllows you to adjust where the labels are displayed around the payment field input boxes.

Available Options: 'above the line' or 'horizontal' or 'below the line'

The default theme is 'above the line' if a theme is not defined.

NOTE: May require you to adjust the size of the div container via CSS.
getControlAllows 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.

EMV

Add secure EMV functionality to your applications with PayTrace’s semi-integrated EMV solution. By simply plugging in a few extra lines of code, you will gain access our secure-encrypted keyboard emulated EMV device.


PayTrace’s EMV 2.0 allows the host application to acquire secure-encrypted card information from the ID TECH Augusta EMV reader. The card data is encrypted at the point of interaction, ensuring that sensitive cardholder data is never exposed to your environment. This will add a layer of security to your card-present chip transactions and enable merchants to qualify for Level III interchange rates using PayTrace EMV 2.0.


PayTrace EMV 2.0 uses a customized encryption and configuration file. Only PayTrace authorized distributors can securely configure the ID Tech Augusta device to work with our service. For more information regarding these authorized distributors, please see the PayTrace Recommended Hardware page.

EMV Sale(Card Present)

This Sale Method can be used when a Credit card is present. This method performs the operation of Authorization and Capture in one sale request.

Request URL

Post
 /v1/transactions/sale/emv

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
emv_dataA string of data from a credit card chip provided by the IDTech EMV card reader.

This field is also used for FallBack Swipe data in the event that a fallback is triggered. See Fallback for more information regarding Fallback swipes
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers' calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting an encrypted CSC value with the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled within the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, click here shipping_address Schema.objectOptional
emailA customer's email address where the Authorization receipt will be sent.stringOptional
descriptionOptional 255 character max length text describing the transactions, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.boolean
Optional
custom_dbaThe value that is sent to the cardholder’s issuer that overrides the business name stored within the PayTrace system. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationThis flag must be set to true in order to support partial authorizations and balance amounts in transaction responses.

PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For the supported  schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and response_code parameters.   Check out API Response Codes for possible values.

Additional verification can be performed with the avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
emv_detailsFor the supported schema, Click here EMV_Details Schema.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with EMV Sale

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, check the success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values. Test data can be found here.

Declined Transaction Example

If a sale transaction is declined by the processing network, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


EMV Authorization(Card Present)

An EMV Authorization can be performed when a Credit card is present.

This method verifies a customer's credit card information and places a hold on the amount requested.   A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Request URL

Post
 /v1/transactions/authorization/emv

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
emv_dataA string of data from a credit card chip provided by the IDTech EMV card reader.

This field is also used for FallBack Swipe data in the event that a fallback is triggered. See Fallback for more information regarding Fallback swipes
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers' calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc instead when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled within the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt will be sent.stringOptional
descriptionOptional 255 character max length text describing the transactions, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.boolean
Optional
custom_dbaA value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationThis flag must be set to true in order to support partial authorizations and balance amounts in the transaction responses.

PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.

Additional Verification can be performed with avs_response and csc_response.  Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request and provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
emv_detailsFor the supported schema, Click here EMV_Details Schema.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with EMV Authorization

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, check the success and response_code parameter values.   Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.

You will get an API error response with an invalid Request or input Parameters.              

Declined Transaction Example

If an Authorization transaction is declined by the processing network, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


EMV Refund Authorization(Card Present)

This method can be used when a credit card is present.  It issues credit back to the credit card holder's account.

Request URL

Post
 /v1/transactions/refund/emv

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
emv_dataA string of data from a credit card chip provided by the IDTech EMV card reader.

This field is also used for FallBack Swipe data in the event that a fallback is triggered. See Fallback for more information regarding Fallback swipes
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers' calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
billing _addressFor the supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refunds receipt will be sent.stringOptional
descriptionOptional 255 character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and is returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with EMV Refund Auth

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.       

Declined Transaction Example

If a refund transaction is declined by the processing network, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.


EMV FallBack Handling

An EMV fallback transaction occurs when a customer attempts to use an EMV (chip) card, at an EMV chip terminal, but the chip is unable to be read due to technical issues. The Terminal will then “fall back” to the magnetic strip technology in order to continue the transaction as a swiped transaction.

When the card reader experiences a Technical issue, it will provide a value in place of the normal EMV chip data. When the API receives this value, it will respond with one of the following API error Codes which indicate how to proceed with the transaction.



Fallback Types
TypeDescriptionError codeError Message
No ChipThe card has no chip and can only be swiped.

Note: No Error code or message provided
--
TechnicalThe chip is damaged or cannot be read. This will prompt your customer to reattempt the chip read.300Invalid Chip Read. Please reinsert the card.
TechnicalThe chip is damaged or cannot be read and must be swiped.

Note: Only prompts after 3 unsuccessful chip reads
301Invalid Chip attempts exceeded. Please re-attempt the swipe.
Empty CandidateThe EMV terminal does not have applications in common with the EMV card and must be swiped.302Empty Candidate. Please attempt to swipe.
TechnicalThe Card reader failed to read the chip. This will prompt your customer to reattempt the chip read.303Card reader error. Please reinsert card.

Handling Fallback Responses

After receiving a response from the PayTrace API that indicates a Fallback has been triggered, the customer should be prompted to proceed according to the API error message received within the response. The new value provided by the chip reader should then be sent within the emv_data field and resubmitted using the same EMV API request method used for the original attempt.



Testing Fallback Responses

The following emv_data values will prompt the API to respond with the appropriate EMV Fallback responses. In order to complete the transaction, use the appropriate Fallback Swipe emv_data values after the fallback response has been provided.



Fallback EMV Values
TypeDescriptionemv_data Value
TechnicalPrompts to retry inserting the chip due to a technical errorDFEF6102F220
TechnicalPrompts to swipe the card due to too many failed chip insert attemptsDFEF6102F222
Empty CandidatePrompts to swipe the card due to empty candidate card readDFEF6102F221


No Chip Fallback Swipe Value:

02E300801E0025009292;4259********0890=2202*************?*548979D445DA7143316A17895BC86FABC1F9BB794B24424223708FB02865A1B7FD6611B518A1A2F7FF2D226008BDD7B500000000000000000000000000000000000000003932385439363636393362994900A9000080007B34CE03

Empty Candidate Fallback Swipe Value: 

DFEE250250059F390180DFEE238201D602CA01801F402400B39B%*5413********0011^UAT USA/TEST CARD 10      ^2212************?*;5413********0011=2212************?*B7F09688FC1E2B3CB957390EB0EB1C64CBF3235C4E92320D21D9BBB4D20C745DA8776A1DD6D8C776B74DFC84860FF4018D40936D059665C359B151EF032F52F6B3DEBEEE2EB149626951C72A7F07D04129CDD5F96ABEDD44438CA5A4E718C6ECB8DEA14E42FB84E4AA2B2636ECCDAFCA00000000000000000000000000000000000000000000000000000000000000000000000000000000393335543038373430306299499706000060002378E603

Technical Fallback Swipe Value:

DFEE250230029F390180DFEE238201FC02F001801F452500B39B%*4761********0267^UAT USA/TEST CARD 05      ^2212*****************?*;4761********0267=2212*************?*F8C00132E9679248B45A08C64C66D53C3DC832ACCF8E979749FE8EDF50EB58822E3F3626B9FACFD0988ED4DF3C350993D1FBF14A4E46F6FC065E07DDE762E6A1C94FDFD42B1EDEFBDEE878E1EBF1073A1710FE82C6A8C99F63D75DDDC8C4FF40D0591C7BFB966FA90138FAC27804C7AB195E71435A9E0AA7BDCCE874CA118492000000000000000000000000000000000000000000000000000000000000000000000000000000003934345433303137333162994997060000C0000773D903


Sale Transactions

A Sale transaction performs the operation of Authorization and Capture in one request.  A Sale request can be used with encrypted values (encrypted_number and encrypted_csc) that were encrypted by the PayTrace Client-Side Encryption JavaScript Library.


Keyed Sale(Card Not Present)

A Keyed Sale can be performed when the card is NOT present.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with this request.             

Request URL

Post
 /v1/transactions/sale/keyed

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(This must be provided if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
credit_cardFor supported Schema, Click here Credit_Card Schema.objectNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscThe CSC is the 3 or 4 digit code found on the signature line of the credit card. The CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor the supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.boolean
Optional
custom_dbaThe value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationThis flag must be set to true in order to support partial authorizations and balance amounts in the transaction responses.

PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and response_code parameters.   Check out API Response Codes for possible values.

Additional verification can be performed with avs_response and csc_response.  Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values: true/false.
True indicates the request was successful and there were no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request which provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system which will be returned in the response.string
masked_card_numberA credit card number with all digits masked and replaced with 'x' except the last 4 digits.

This parameter will be returned in the JSON response only when the Credit Card number is one of the request parameters.
string

Error with Keyed Sale

The error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input parameter.             

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, the appropriate Response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad Request.  Test data can be found here.


Swiped Sale(Card Present)

This Sale Method can be used when a Credit card is present. This method performs the operation of Authorization and Capture in one sale request.

Request URL

Post
 /v1/transactions/sale/swiped

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
swipe or encrypted_swipeA string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2.

Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client Side Encryption JavaScript Library.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled from the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled from PayTrace Virtual Terminal → Account → Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled from the PayTrace Virtual Terminal → Account → Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address Schema.objectOptional
emailCustomer's email address where the Authorizations receipt may be sent.stringOptional
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountPortion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.boolean
Optional
custom_dbaValue that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationFlag must be set to true in order to support partial authorization and balance amounts in transaction responses.

PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional Verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageA transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Swiped Sale

The error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values. Test data can be found here.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, the appropriate Response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Sale By Transaction ID

This method can be used to process a sale transaction with the credit card billing information from a past transaction made within PayTrace.

Request URL

Post
 /v1/transactions/sale/by_transaction

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: The transaction ID should be a reference to a legitimate transaction with the PayTrace system in the past to avoid API errors.
numberNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor the supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionAn optional 255-character max-length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.

Additional Verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates request was successful and no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Sale By Transaction ID

The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.


Vault Sale By Customer ID

A Vault Sale will allow you to process a transaction with an existing Customer ID (Token) from your Customer Database (Vault) at PayTrace.

Request URL

Post
 /v1/transactions/sale/by_customer

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.   Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Sale By Customer ID

The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information. 

To check any unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.  Test data can be found here.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Protect Sale

A Protect Sale will allow you to process a transaction using the token and encryption key created when using the Protect.js UI.

Request URL

Post
 /v1/transactions/sale/pt_protect

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
hpf_tokenA one time nonce representing the senstitive credit card data collected by the Protect.js UI.stringNo configuration settings applied.

Required
enc_keyUnique cipher key provided by the Protect.js UI.stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.   Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Protect Sale

The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information. 

To check any unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.  Test data can be found here.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Protect Sale and Create Customer

This method will allow you to process a transaction and create a customer profile upon the transaction approval using the token and encryption key created when using the Protect.js UI.

Request URL

Post
 /v1/transactions/sale/pt_protect_customer

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
hpf_tokenA one time nonce representing the sensitive credit card data collected by the Protect.js UI.stringNo configuration settings applied.

Required
enc_keyUnique cipher key provided by the Protect.js UI.stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.

Note: This ID should not be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.   Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Protect Sale and Create Customer

The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information. 

To check any unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.  Test data can be found here.

Transaction Approval with Existing Customer Id Example

If a transaction is approved but the provided customer id already exists in the database, A customer profile will not be created. When this occurs, you will receive an HTTP status code in the 2XX range with a JSON body. Unlike with a sucessfull response, you will receive a response code of 167 with a status_message stating "Your transaction was successfully approved. However, the requested customer profile could not be created." Check out API Response Codes for other possible values.

Declined Transaction Example

If a sale transaction attempt is declined by the processing network due to any reason, the appropriate response code will be returned in the error response. A customer profile will not be created if the transaction has been declined.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Authorization

An Authorization transaction verifies a customer's credit card information and places a hold on the amount requested.  A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with Authorization.


Keyed Authorization(Card Not Present)

Keyed Authorization can be performed when the card is NOT present.

This Method verifies a customer's credit card information and places a hold on the amount requested.  A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with this request.     

Request URL

Post
 /v1/transactions/authorization/keyed

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
credit_cardFor supported Schema, Click here Credit_Card Schema.objectNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.booleanOptional
custom_dbaAn optional value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationThis flag must be set to true in order to support partial authorizations and balance amounts in the transaction responses.
PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with avs_response and csc_response.  Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and has no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string
masked_card_numberThe credit card number with all digits masked and replaced with 'x' except the last 4 digits.

This parameter will be returned in JSON response only when the Credit Card number is one of the request parameters.
string

Error with Keyed Authorization

The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and the esponse_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values. Test data can be found here.

You will get an API error response with invalid Request or input Parameters.     

Declined Transaction Example

If an Authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if the transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.


Swiped Authorization (Card Present)

A Swiped Authorization can be performed when a credit card is present.

This Method verifies a customer's credit card information and places a hold on the amount requested.   A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with this request.     

Request URL

Post
 /v1/transactions/authorization/swiped

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
swipe or encrypted_swipeA string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2.

Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled from the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled from the PayTrace Virtual Terminal → Account → Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled from the PayTrace Virtual Terminal → Account → Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailA customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.boolean
Optional
custom_dbaA value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationThis flag must be set to true in order to support partial authorizations and balance amounts in transaction responses.

PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional Verification can be performed with avs_response and csc_response.  Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageA Transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Swiped Authorization

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and the response_code parameter values.   Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.

You will get an API error response with invalid Request or input Parameters.     

Declined Transaction Example

If an Authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Authorization By Transaction ID

This method can be used to process an authorization transaction with the credit card billing information from a past transaction made within PayTrace.  A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Request URL

Post
 /v1/transactions/authorization/by_transaction

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: This should be a reference to a legitimate transaction within the PayTrace system in the past to avoid API errors.
numberNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting an encrypted CSC value by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor the supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured.

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailA customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with the avs_response and the csc_response. Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Authorization By Transaction Id

The error response will include an HTTP status code and JSON body with error information.   Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.

You will get an API error response with an invalid Request or input Parameters.    

Declined Transaction Example

If an authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.


Vault Authorization By Customer ID

This Method will allow you to process an authorization on the requested amount with an existing Customer ID (Token) from your Customer Database (Vault) at PayTrace.

A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Request URL

Post
 /v1/transactions/authorization/by_customer

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should be an existing customer ID within the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting the encrypted CSC value by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled in the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionAn optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
return_clrIf set to true, card level results will be returned with the response. Card level results include whether or not the card is a consumer, purchasing, check, rewards, etc. account. Card level results are only returned with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, Global, Paymentech, and Trident networks.booleanOptional
custom_dbaAn optional value that is sent to the cardholder’s issuer and overrides the business name stored in PayTrace. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks.stringOptional
enable_partial_authorizationThis flag must be set to true in order to support partial authorization and balance amounts in transaction responses.
PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer.
booleanOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with the avs_response and the csc_response.  Check out AVS and CSC response for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and there were no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Authorization By Customer Id

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful transactions, please check the success and response_code parameter values.   Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.    

Declined Transaction Example

If an authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Protect Authorization

This Method will allow you to process an authorization on the requested amount using the token and encryption key created when using the Protect.js UI.

A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.

Request URL

Post
 /v1/transactions/authorization/pt_protect

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
hpf_tokenA one time nonce representing the senstitive credit card data collected by the Protect.js UI.stringNo configuration settings applied.

Required
enc_keyUnique cipher key provided by the Protect.js UI.stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the Authorization receipt may be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.   Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates the request was successful and there are no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Protect Sale

The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information. 

To check any unsuccessful transactions, please check the success and the response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters avs_response and csc_response.  Check out AVS and CSC response for possible values.  Test data can be found here.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Capture Transaction

This method can be used to convert any preauthorized transaction into a Sale, to be settled for payment. The unsettled and preauthorized transaction ID that should be provided for a successful capture.

If an amount parameter is not submitted, the transaction will be captured with the original authorized amount.

Request URL

Post
 /v1/transactions/authorization/capture

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirement
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: The transaction should be unsettled and a pre authorized transaction within the PayTrace system to avoid any API errors.
numberRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.

Note: The amount must be less than or equal to the original authorization amount.
numberOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates the request was successful and had no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for the possible valuesnumber
status_messageA status message about the request and provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Capture Transaction

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

Declined Transaction Example

If a capture of a transaction request is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if the transaction is not captured, you will get a declined transaction response with an HTTP status code - 400 Bad request.  Test data can be found here.


Void Transaction

This method can be used to void any unsettled transaction.

Request URL

Post
 /v1/transactions/void

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirement
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be an Unsettled transaction with the PayTrace system to avoid any API errors.
numberRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for the possible values.number
status_messageA status message about the request and provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number

Error with Void Transaction

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.    

Declined Transaction Example

If a void transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if a void transaction is not successful, you will get a declined transaction response with a HTTP status code - 400 Bad request.  Test data can be found here.


Adjust Transaction

This method can be used to adjust a transaction amount.  The following conditions must be fulfilled for a successful transaction.

  • The transaction must be Unsettled.
  • Only the following transactions are allowed.
    • Approved authorization
    • Refund
  • The new amount must be greater than zero.
  • The new amount can not exceed 30% of the original authorized amount.

Request URL

Post
 /v1/transactions/adjust

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirement
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberRequired
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be an Unsettled transaction within the PayTrace system to avoid any API errors.
stringRequired

Optional Attributes: None


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is successful.   You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageStatus message about the request and provides additional information about the request execution end result.string

Error with Adjust Transaction

Error response will include an HTTP status code and JSON body with error information.   Check out API Errors for more information.

To check any unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

For example, If an amount is invalid or does not meet the adjustment criteria (described earlier), an error response will be returned with an HTTP status code of - 400 Bad request.  Test data can be found here.


Refund Authorization

As per the VISA Card brand enhancement mandate, a Refund Authorization or "Purchase Return Authorization" enables a card issuer to authorize and validate a refund for a cardholder, as well as identify if the account doesn't exist or has been closed. At this time this feature is only available for Visa transactions however, we anticipate this feature will be added for the other card brands in the future. Updates will be made as other Card Brands begin supporting this feature.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with Refund requests.


Keyed Refund Authorization (Card Not Present)

A Keyed Refund Authorization can be performed when the card is NOT present.

This method can be used to issue a credit back to the credit card holder's account.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with this request.

In order to avoid potential fees, PayTrace recommends using the Refund Authorization methods rather than the Refund methods.

Currently, not all card processors support this feature. Those that do not currently support this feature have an extension in place with VISA to not accrue fees on the Merchant.

For integrators using Card Processors that currently do not support this feature, VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.

This type of refund is known as an unreferenced refund. Please note there is potentially an increased risk of nefarious activity occurring with this type of refund request. For this reason, the permission needed to perform an Unreferenced Refund is disabled on live and sandbox accounts. It is recommended that the feature be disabled unless absolutely needed. If in the event this feature is needed, you can have it enabled by speaking with your Merchant Service Provider for live accounts or contacting our 5-star Support for sandbox accounts.

Request URL

Post
 /v1/transactions/refundauth/keyed

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
credit_cardFor supported Schema, Click here Credit_Card Schema.ObjectNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refunds receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request and provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string
masked_card_numberCredit card number with all digits masked and replaced with 'x' except the last 4 digits.

This parameter will be returned in the JSON response only when the Credit Card number is one of the request parameters.
string

Error with Keyed Refund Auth

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check any unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.                                 


Swiped Refund Authorization(Card Present)

This method can be used when a credit card is present.  It issues credit back to the credit card holder's account.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library. can be used with this request.              

Request URL

Post
 /v1/transactions/refundauth/swiped

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
swipe or encrypted_swipeThe string data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2.

Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled from PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refunds receipt will be sent.stringOptional
descriptionOptional 255-character max text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

Using this method, the VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA, Refund transactions will be processed as regular Refunds and will not contain Authorization data.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request and provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageTransaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Swiped Refund Auth

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.       

Declined Transaction Example

If a refund transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if the transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.


Refund Authorization By Transaction ID

This method can be used to process a refund of a settled transaction.  If the amount is submitted, a specific amount will be refunded with the credit card used in the referred transaction.

Request URL

Post
 /v1/transactions/refundauth/for_transaction

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.

Note: If the amount is not provided, the transaction will be refunded with the original amount.
numberNo configuration settings applied.

Required
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be a reference to a legitimate transaction within the PayTrace system in the past, to avoid any API errors.
numberNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled in the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page. page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refund receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Refund Auth By Transaction ID

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.        


Vault Refund Authorization By Customer ID

This method will allow you to process a Refund on the requested amount with an existing Customer ID (Token) from your Customer Database (Vault) at PayTrace.  The amount will be refunded to the credit card account associated with the customer Id.

Request URL

Post
 /v1/transactions/refundauth/to_customer

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refund receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.   You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageStatus message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
approval_messageThe transaction approval message from the processing networks.string
avs_responseA unique string identifier returned by the AVS. Check out AVS Response for the possible values.string
csc_responseA unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values.string
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Refund Auth By Customer Id

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values. Test data can be found here.


Refund Transaction

A Refund transaction allows a merchant to issue a refund back to a customer's credit card account.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with Refund requests.


Keyed Refund (Card Not Present)

Keyed Refunds can be performed when the card is NOT present.

This method can be used to issue a credit back to the credit card holder's account.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with this request.

This type of refund is known as an unreferenced refund. Please note there potentially is an increased risk of nefarious activity occurring with this type of refund request. For this reason, the permission needed to perform an Unreferenced Refund is disabled on live and sandbox accounts. It is recommended that the feature be disabled unless absolutely needed. If in the event this feature is needed, you can have it enabled by speaking with your Merchant Service Provider for live accounts or contacting our 5-star Support for sandbox accounts.

Request URL

Post
 /v1/transactions/refund/keyed

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
credit_cardFor supported schema, Click here Credit_Card Schema.ObjectNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
billing _addressFor the supported schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailA customer's email address where the Refund receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns a HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageA status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string
masked_card_numberCredit card number with all digits masked and replaced with 'x' except the last 4 digits.

This parameter will be returned in the JSON response when the Credit Card number is included in the request parameters.
string

Error with Keyed Refund

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.      


Swiped Refund (Card Present)

This method can be used when a credit card is present.  It issues a credit back to the credit card holder's account.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library. can be used with this request.   

Request URL

Post
 /v1/transactions/refund/swiped

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
swipe or encrypted_swipeA string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2.

Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" and "Required on Swiped" fields are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refunds receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. Must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Swiped Refund

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.   

Declined Transaction Example

If a refund transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.

For example, if the transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.


Refund By Transaction ID

This method can be used to process a refund of a settled transaction.  If the amount is submitted, the specific amount will be refunded to the credit card used in the referred transaction.

Request URL

Post
 /v1/transactions/refund/for_transaction

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.

Note: If the amount is not provided, the transaction will be refunded with the original amount.
numberNo configuration settings applied.

Required
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be a reference to a  legitimate transaction within the PayTrace system in a past to avoid any API errors.
numberNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page. page.

Required if configured
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refund receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is refunded.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Refund By Transaction ID

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.   


Vault Refund By Customer ID

This method will allow you to process a Refund on the requested amount with an existing Customer ID (Token) from your Customer Database (Vault) at PayTrace.  The amount will be refunded to the credit card account associated with the customer Id.

Request URL

Post
 /v1/transactions/refund/to_customer

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
csc or encrypted_cscCSC is the 3 or 4 digit code found on the signature line of the credit card. CSC is found on the front of AMEX cards.

Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled in the PayTrace Virtual Terminal→ Account → Security Settings page.

Required if configured
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the Refund receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction is approved.   You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for the possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
transaction_idA unique identifier for each transaction in the PayTrace system.number
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Refund By Customer Id

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values. Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.   


Email Receipt

This method can be used to send a transaction receipt in an email.

Request URL

Post
/v1/transactions/email_receipt

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirement
emailAn Email address to where the receipt will be sent to.

Note: One additional email address may be included using a comma separated string.
stringRequired
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be a legitimate transaction with PayTrace system to avoid any API errors.
numberRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None


Successful Response

A successful request returns a HTTP status code in the 2XX range with a JSON body.

A HTTP status code in the 2XX range does not indicate that a reqeust is successful.  You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates request was successful and no errors.
False indicates request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for the possible valuesnumber
status_messageStatus message about the request and provides additional information about the request execution end result.string

Error with Email Receipt

Error response will include a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful request, please check success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with any invalid Request or input Parameters.         

For example, If an invalid transaction id or an Invalid email address is submitted, error response will be returned with a HTTP status code - 400 Bad request.   Test data can be found here.


Customer Database (Vault)

What is a Customer Database (Vault) at PayTrace?

PayTrace provides a PCI-compliant Customer Database (Vault) for your account.  You can store a customer's billing and payment information in this database with your customer ID (token). This database can eliminate your application requirements for storing sensitive payment information.  The customer IDs can be used with future transactions. When an existing Customer ID is used for transactions, the associated billing and payment information from the database will be used.

You can manage your customer profiles using various create, update, delete and export methods in your PayTrace database (Vault).

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with all customer Profile methods.


Create Customer Profile

This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault) for your account.  You can assign a customer ID (token) with this method.

Request URL

Post
 /v1/customer/create

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.

Note: This ID should not be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
credit_cardFor supported Schema, Click here Credit_Card Schema.objectNo configuration settings applied.

Required only if check data is not provided.
checkThe checking account detail. For supported Schema, Click here Check Schema.objectNo configuration settings applied.

Required only if credit_card data is not provided.
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
phoneThe customer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxThe customer's fax number (i.e. 555-555-5555, or 5555555555).stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data Schema.objectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is created. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
customer_idA unique identifier for each customer in the PayTrace system, the value must be the same as provided with the request.string
masked_card_numberThe credit card number with all digits masked and replaced with 'x' except for the last 4 digits.

Note:This parameter will be returned in the JSON response when the Credit Card number is one of the request parameters.
string

Error with Create Customer Profile

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful requests check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

Error Example

If provided customer id already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.


Create Customer Profile from a Transaction

This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault) from a past transaction.  You can assign a customer Id (token) with this method.

Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with this request.   

Request URL

Post
 /v1/customer/create_from_transaction

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should not be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be a reference to a legitimate transaction within the PayTrace system processed in the past to avoid any API errors.
numberNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
phoneThe customer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxThe customer's fax number (i.e. 555-555-5555, or 5555555555).stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is created.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request.string

Error with Create Customer Profile

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

Any duplicate customer ID or an invalid Transaction ID, as well as an invalid input parameter, will result in an error.

To check for unsuccessful requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.   

Error Example

If provided customer id already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.


Update Customer Profile

This method can be used to modify your existing customer profile stored in PayTrace's PCI-compliant Customer Database (Vault) for your account. You can update any data including a new customer ID (token) for your customer with this method.

Encrypted values can be used with this request.           

Request URL

Post
 /v1/customer/update

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
customer_idA unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.stringNo configuration settings applied.

Required
credit_cardFor supported Schema, Click here Credit_Card Schema.objectNo configuration settings applied.

Required only if check data is not provided.
checkThe checking account detail. For supported Schema, Click here Check Schema.objectNo configuration settings applied.

Required only if credit_card data is not provided.
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, Click here shipping_address Schema.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
phoneThe customer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxThe customer's fax number (i.e. 555-555-5555, or 5555555555).stringOptional
new_idA new unique identifier for a customer profile that may be sent with a request to update a customer profile.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data Schema.objectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is Updated.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request.string
masked_card_numberThe credit card number with all digits masked and replaced with 'x' except the last 4 digits.

Note: This parameter will be returned in JSON response only when the Credit Card number is one of the request parameters.
string

Error with Update Customer Profile

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful requests, please check the success and response_code parameter values.   Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.         

Error Example

If the provided customer ID already exists in the database, you will get an error response with an HTTP status code - 400 Bad request.  Test data can be found here.


Delete Customer Profile

This method can be used to delete any existing customer profile stored in PayTrace's PCI-compliant Customer Database (Vault) for your account.

Request URL

Post
 /v1/customer/delete

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirements
customer_idA unique identifier for an existing customer profile stored in your Customer Database (Vault) at PayTrace.stringRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is deleted. You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values. Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request.string

Error with Delete Customer Profile

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.  

Error Example

If provided the customer ID doesn't exist in the database to update the profile, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.


Export Customer Profile

This method can be used to export your existing customer profiles stored in PayTrace's PCI-compliant Customer Database (Vault) for your account.

You can export specific customer profiles by providing optional request parameters.

Request URL

Post
 /v1/customer/export

Required Attributes
AttributeDescriptionTypeAttribute Requirement
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
customer_idA unique identifier for an existing customer profile stored in your Customer Database (Vault) at PayTrace.stringOptional
createdFor the supported Schema, Click here Request_Creation_Record Schema.objectOptional
emailThe customer's email address.stringOptional
include_binIf set to true, this will return the first 6 and last 4 digits of the credit card number.booleanOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is exported.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

This method will return an array of individual customer profiles.             

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
customersAn array of customer profiles.
For Customer Profile supported Schema, Click here Customer_Record Schema.
array

Error with Export Customer Profile

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

This method will return an empty customer array in the case where no customer records are found. You will get an API error response with an invalid Request or input Parameters.             

Error Example

If the provided customer ID customerTest150 is not an existing customer profile, you will get an empty customer array in a response with an HTTP status code - 200 OK request.  Test data can be found here.


Create Customer Profile Using Protect.js

This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault). You can assign a customer Id (token) with this method.

Request URL

Post
 /v1/customer/pt_protect_create

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should not be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
hpf_tokenA one time nonce representing the senstitive credit card data collected by the Protect.js UI.stringNo configuration settings applied.

Required
enc_keyUnique cipher key provided by the Protect.js UI.stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
phoneThe customer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxThe customer's fax number (i.e. 555-555-5555, or 5555555555).stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is created.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request.string

Error with Create Customer Profile

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

Any duplicate customer ID or invalid Protect Token, as well as an invalid input parameter, will result in an error.

To check for unsuccessful requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.        

Error Example

If provided customer id already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.


Update Customer Profile Using Protect.js

This method can be used to modify your existing customer profile stored in PayTrace's PCI-compliant Customer Database (Vault) for your account. You can update any data including a new customer ID (token) for your customer with this method.

Request URL

Post
 /v1/customer/pt_protect_update

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note: This ID should not be an existing customer ID in the PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
hpf_tokenA one time nonce representing the senstitive credit card data collected by the Protect.js UI.stringNo configuration settings applied.

Required
enc_keyUnique cipher key provided by the Protect.js UI.stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectThis object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address Schema.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
phoneThe customer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxThe customer's fax number (i.e. 555-555-5555, or 5555555555).stringOptional
new_idA new unique identifier for a customer profile that may be sent with a request to update a customer profile.stringOptional
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptional


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a customer profile is created.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
customer_idA unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request.string

Error with Update Customer Profile

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful requests, please check the success and response_code parameter values.   Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.            

Error Example

If the provided customer ID already exists in the database, you will get an error response with an HTTP status code - 400 Bad request.  Test data can be found here.


Level 3 Data

What is Level 3 data?

Level 3 data is additional information that may be applied to enrich a transaction’s reporting value to both the merchants and the customers. Generally, merchant service providers offer reduced or qualified pricing for transactions that are processed with Level 3 data.

Level 3 data can be added to any approved and unsettled Sale transaction with Visa or MasterCard. Some level 3 data, specifically enhanced data such as Invoice and Customer Reference ID, may overlap with data provided with the base transaction. Enhanced data, when applied, will always overwrite such data that may already be stored with the transaction.

Level 3 data consists of enhanced data and 1 or more line item records. This information is intended to describe the details of the transaction and the products or services rendered. However, defaults may be applied in the event when some data is missing or unknown. Skipped parameters will be replaced with PayTrace defaults.

Please make sure to set Level 3 defaults with your PayTrace Virtual Terminal Account before moving forward to add level 3 data methods.

Visa and MasterCard have their own requirements for level 3 data, so your application should be able to determine if the transaction being updated is with a Visa or a MasterCard before formatting and sending the request.

All Visa account numbers begin with “4” and all MasterCard account numbers begin with “5”.

In order to issue more cards, MasterCard is beginning to issue cards beginning with a "2" in 2017.
Why do I need to enter Level 2 or Level 3 data?

Level 2 and 3 data is additional information that can be sent through with your transactions that can help qualify (keep processing rates low) certain types of credit cards. Level 2 and 3 data typically can help when accepting Business Cards, Purchasing Cards, Corporate Cards, or Government (GSA) Cards.

In most cases when you accept these types of cards, the dollar amount of the transaction is larger than if you were to accept a consumer/personal credit card. When the dollar amounts of the transactions go up, the risk associated with the card brands funding them goes up. This results in a higher processing rate due to the higher risk. However, level 2 and 3 data helps provide additional information about the merchant, customer, and transaction to help meet the card brand's criteria for reaching a lower processing rate. This additional information is not required to process or get funded for your transactions. However, providing this information helps reduce the risk associated with the funding of the transactions by the card brands, which results in lower processing rates.

For more information about specific level 2 and 3 information, click here

Add Level 3 Data with MasterCard

This method can be used to add Level 3 data to any approved and unsettled sale transaction with  MasterCard.

You can add single or multiple line items as needed.

Request URL

Post
 /v1/level_three/mastercard
             

Required Attributes
AttributeDescriptionTypeAttribute Requirement
transaction_idA unique identifier for each transaction in the PayTrace system.
Note: This ID should reference a transaction that has been approved and is pending settlement within the PayTrace system to avoid any API errors.
numberRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
             

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringOptional
customer_reference_idCustomer reference ID is only used for transactions that are identified as corporate or purchasing credit cards.
The customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.
stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.numberOptional
national_tax_amountThe portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT).numberOptional
freight_amountThe freight value should represent the portion of the transaction amount that was generated from shipping costs.numberOptional
duty_amountThe portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT).numberOptional
source_addressOnly zip is a required attribute.
For the supported schema, Click here shipping_address Schema.
objectOptional
shipping_addressOnly zip and country are required attributes.
For the supported schema, Click here shipping_address Schema.
objectOptional
additional_tax_amountAny tax generated from freight or other services associated with the transaction.numberOptional
additional_tax_includedA boolean flag used to indicate if an additional tax was included in the transaction. Set to
true - if an additional tax was included. Set to
false - if no additional tax was applied.
booleanOptional
line_itemsLine items are a collection of product detail.
It is an array containing zero or more Line Item objects.
For supported schema, check out MasterCard_Line_Items Schema on the same page.
an array of an object/objectsOptional
             

MasterCard_Line_Items Schema
AttributeDescriptionTypeAttribute Requirements
additional_tax_amountAny tax generated from freight or other services associated with the transaction.numberOptional
additional_tax_includedA boolean flag used to indicate if an additional tax was included in the transaction.
Set to true - if an additional tax was included.
Set to false - if no additional tax was applied.
booleanOptional
additional_tax_rateThe rate at which additional tax was assessed.numberOptional
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberOptional
debit_or_creditFlag used to determine whether the line item amount was a debit or a credit transaction. Generally, this is always a debit or there is a factor that increased the transaction amount.
Possible values are D (net is a debit) and C (net is a credit).
stringOptional
descriptionOptional text describing the transaction, products, customers, or other attributes of the transaction.

Note 35 characters max limit.
stringOptional
discount_amountThe discount value should represent the amount discounted from the original transaction amount.numberOptional
discount_rateThe rate at which a discount was applied to the transaction in reference to this specific line item.

Note: When discount_amount and discount_included are true, this parameter is required for a successful request.
numberOptional
discount_includedA boolean flag used to indicate whether a discount was applied to the transaction amount in reference to the specific line item record.booleanOptional
merchant_tax_idThe merchant’s tax identifier used for tax reporting purposes.stringOptional
product_idYour unique identifier for the product.stringOptional
quantityItem count of the product in the order.numberOptional
tax_includedA boolean flag used to indicate whether a line item amount includes tax or not.booleanOptional
unit_of_measureThe unit of measure applied to the product and its quantity. Click here to find: Level 3 Unit of Measurement Codes.stringOptional
unit_costProduct amount per quantity.numberOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a Level 3 data is added.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.  

Response Attributes

             

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThat status message about the request and provides additional information about the request execution end result.string

Error with MasterCard Level 3 data

Error response will include an HTTP status code and JSON body with error information.   Check out API Errors for more information.

To check for unsuccessful add level 3 data requests, check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an error response if a transaction is not eligible to add level 3 data. Test data can be found here.

Error Example

With an invalid transaction ID or non-eligible transaction, you will get an error response with an HTTP status code - 400 Bad Request.


Add Level 3 Data with Visa

This method can be used to add Level 3 data to an approved and unsettled sale transaction with a Visa card.

You can add none or multiple line items as needed.

Request URL

Post
 /v1/level_three/visa
    

Required Attributes
AttributeDescriptionTypeAttribute Requirement
transaction_idA unique identifier for each transaction in the PayTrace system.
Note: It should be a reference to a transaction that is approved and pending settlement within the PayTrace system to avoid any API errors.
numberRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
    

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringOptional
customer_reference_idThe customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards.
The customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.
stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.numberOptional
national_tax_amountThe portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT).numberOptional
merchant_tax_idThe merchant’s tax identifier used for tax reporting purposes.stringOptional
customer_tax_idThe customer’s tax identifier used for tax reporting purposes.stringOptional
commodity_codeThe commodity code that generally applies to each product included in the order. Commodity codes are generally assigned by your merchant service provider.stringOptional
discount_amountThe discount value should represent the amount discounted from the original transaction amount.numberOptional
freight_amountThe freight value should represent the portion of the transaction amount that was generated from shipping costs.numberOptional
duty_amountThe portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT).numberOptional
source_addressZip is a required attribute.
For supported schema, click here shipping_address Schema.
objectOptional
shipping_addressZip and country are required attributes.
For supported schema, click here shipping_address Schema.
objectOptional
additional_tax_amountAny tax generated from freight or other services associated with the transaction.numberOptional
additional_tax_rateThe rate at which additional tax was assessed.numberOptional
line_itemsLine items are a collection of product details.
It is an array containing zero or more Line Items objects.
For supported schema, click here Visa_Line_Items Schema on the same page.
an array of an object/objectsOptional
    

Visa_Line_Items Schema
AttributeDescriptionTypeAttribute Requirements
additional_tax_amountAny tax generated from freight or other services associated with the transaction.numberOptional
additional_tax_rateThe rate at which additional tax was assessed.numberOptional
amountThe dollar amount of the transaction. Must be a positive number up to two decimal places.numberOptional
commodity_codeThe commodity code generally applies to each product included in the order. Commodity codes are generally assigned by your merchant service provider.stringOptional
descriptionOptional text describing the transaction, products, customers, or other attributes of the transaction.

Note: There is a max character limit of 35.
stringOptional
discount_amountThe discount value should represent the amount discounted from the original transaction amount.numberOptional
product_idYour unique identifier for the product.stringOptional
quantityItem count of the product in this order.numberOptional
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: The transaction ID should be a reference to a transaction that is approved and pending settlement within the PayTrace system to avoid any API errors.
numberOptional
unit_of_measureUnit of measure applied to the product and its quantity. Click here to find: Level 3 Unit of Measurement Codes.stringOptional
unit_costProduct amount per quantity.numberOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that Level 3 data was added.   You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

Response Attributes

    

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string

Error with Visa Level 3 data

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful add level 3 data requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an error response if a transaction is not eligible for level 3 data. Test data can be found here.

Error Example

With an invalid transaction ID or ineligible transaction, you will get an error response with an HTTP status code - 400 Bad Request.


Settle Transactions

This method can be used to initiate transaction settlement to your merchant service provider.

This request only works for terminal-based payment processing networks. 

Request URL

Post
 /v1/transactions/settle
 

Required Attributes
AttributeDescriptionTypeAttribute Requirement
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a settlement request is successful.   You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes

 

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageStatus message about the request and provides additional information about the request execution end result.string
transaction_countThe total number of transactions included in the batch for this settlement request.number
net_amountThis value is the net amount (sales minus refunds) of the initiated settlement batch.number
batchThe batch schema that provides details about the initiated batch for settlement.
Note: Only the number Attribute will be returned.
For supported Schema, Click here Batch_Record Schema
object

Error with settlement

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful settlement requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

Error Example

If no transactions are pending for settlement, you will get an error response with an HTTP status code - 400 Bad request.  Test data can be found here.


Export Single Batch

This method can be used to export a summary of specific batch details or currently pending settlement details by card and transaction type.  If no optional parameter is provided, the latest batch details will be returned.

By exporting the batch detail, your application will be able to determine the deposits and refunds.

Request URL

Post
/v1/batches/export_one

Required Attributes
AttributeDescriptionTypeAttribute Requirement
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes
AttributeDescriptionTypeAttribute Requirement
batch_numberA batch number to find specific batch details. This value is the sequential number assigned to the batch.numberOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that an export batch request is successful. You will need to verify the success and the response_code parameters.   Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
batchThis object contains details about the batch.
Note: For the supported Schema, Click here Batch_Record Schema.
object

Error with Export Batch

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful export batch requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

This method will always return success true.  All batch record values will be 0 or an empty string except for the batch_number if the batch_number doesn't exist.

Error Example

If batch_number 1 doesn't exist, you will get a response with an HTTP status code - 200 OK request.  All Batch record values will be 0 or empty string except batch_number. Test data can be found here.


Export Batches By Date Range

This method can be used to export a set of batch summary details with a provided date range.  This method will return one or more batch summary records.

By exporting the batch summary details, your application will be able to determine the deposits and refunds.

Request URL

Post
 /v1/batches/export

Required Attributes
AttributeDescriptionTypeAttribute Requirement
start_dateThe start date is used to indicate the beginning date used to search for transactions or batches to export.
This must be a valid date formatted as MM/DD/YYYY.
stringRequired
end_dateThe end date is used to indicate the ending date used to search for transactions or batches to export.
This must be a valid date formatted as MM/DD/YYYY.
stringRequired
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that an export batch request is successful.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request and provides additional information about the request execution end result.string
batchesThis is an array of batch summary records.
For supported Schema, Click here Batch_Summary_Record Schema
array of objects

Error with Export Batch

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful export batch requests, please check the success and response_code parameter values.   Check out API Response Codes for possible values.   Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.          

Error Example

If no batch exists within a requested date range, you will get an error response with an HTTP status code - 400 Bad Request.  Test data can be found here.


Export Settled Transactions By Batch

This method can be used to export settled transaction details within a specific batch.  This method will return one or more transaction records.

Request URL

Post
 /v1/batches/transaction_list

Required Attributes
AttributeDescriptionTypeAttribute Requirement
batch_numberA batch number to export the transactions. This value is the sequential number assigned to the batch.numberRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that an export report request is successful.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageA status message about the request that provides additional information about the request execution end result.string
transactionsThis is an array of transaction details records with a batch.
Note: Those transaction records will not include discretionary data.
For supported Schema, Click here Transaction_Record Schema.
array of objects

Error with Export Settled Transactions

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful export batch requests, check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.     

Error Example

If a batch doesn't exist or no transactions exist, you will get an error response with an HTTP status code - 400 Bad Request.  Test data can be found here.

Export Transaction By Transaction ID

This method can be used to export specific credit card transaction details.

Request URL

Post
 /v1/transactions/export/by_id

Required Attributes
AttributeDescriptionTypeAttribute Requirement
transaction_idA unique identifier for each transaction in the PayTrace system.
Note: It should reference a past, legitimate transaction within the PayTrace system to avoid any API errors.
stringRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
transaction_typeThe transaction type to find transactions.
Possible values: SALE, AUTHORIZATION, STR/FWD, REFUND, VOID,
CAPTURE, FORCE, SETTLED, PENDING, DECLINED.
stringOptional
createdFor supported Schema, Click here Request_Creation_Record Schema.objectOptional
customer_idA unique identifier for an existing customer profile stored in your Customer Database (Vault) at PayTrace.stringOptional
include_binIf set to true, this will return the first 6 and last 4 digits of the credit card number.booleanOptional
including_textThe text submitted will be used to locate transactions containing this text. This will help to narrow down the export results.stringOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that an export report request is successful.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.  This method will return an array of the transaction details object.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
transactionsThis is an array of the transaction detail record object.
Note : For supported Schema, Click here Transaction_Detail_Record Schema.
array of objects
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Export Transaction

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful export transaction requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

Error Example

If the transaction ID provided does not exist,  you will get an error response with an HTTP status code - 400 Bad Request. Test data can be found here.


Export Transactions By Date Range

This method can be used to export a set of credit card transaction details with a provided date range.  You can optimize your search by providing optional parameters.

Request URL

Post
 /v1/transactions/export/by_date_range

Required Attributes
AttributeDescriptionTypeAttribute Requirement
start_dateThe start date is used to indicate the beginning date used to search for transactions or batches to export.
This must be a valid date formatted as MM/DD/YYYY.
stringRequired
end_dateThe end date is used to indicate the ending date used to search for transactions or batches to export.
This must be a valid date formatted as MM/DD/YYYY.
stringRequired
integrator_idA unique ID to correlate API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
transaction_id

A unique identifier for each transaction in the PayTrace system.


Note: It should reference a past, legitimate transaction within the PayTrace system to avoid any API errors.

stringRequired
transaction_typeThe transaction type to find transactions.
Possible values: SALE, AUTHORIZATION, STR/FWD, REFUND, VOID, SETTLED, PENDING, DECLINED.
stringOptional
createdFor supported Schema, Click here Request_Creation_Record Schema.objectOptional
customer_idA unique identifier for an existing customer profile stored in your Customer Database (Vault) at PayTrace.stringOptional
include_binIf set to true, this will return the first 6 and last 4 digits of the card number.booleanOptional
including_textThe text submitted will be used to locate transactions containing this text. This will help to narrow down the export results.stringOptional

Successful Response

A successful request returns a HTTP status code in the 2XX range with a JSON body.

A HTTP status code in the 2XX range does not indicate that an export report request is successful.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.  Test data can be found here.  This method will return an array of transaction detail objects.

Response Attributes


Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.

Possible values : true/false.

True indicates that the request was successful and had no errors.

False indicates that the request was not successful and some kind of error has occurred.

boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
transactionsThis is an array of transaction detail record objects for the given date range.
Note: For supported Schema, Click here Transaction_Detail_Record Schema
array of objects
external_transaction_idA unique identifier of the request from your system that will be returned in the response.string

Error with Export Transactions

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful export transaction requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.

This method will return an empty transaction array if no transaction record is found.  You will get an API error response with an invalid Request or input Parameters.  

Error Example

If no transaction exists within a request date range, you will get a response with an HTTP status code - 200 OK.  Invalid dates will trigger an error response with 400 Bad Request.  Test data can be found here.


Recurring Payment

The PayTrace API allows you to create and manage recurring payments with your existing customers stored within the PayTrace customer database (Vault). Recurring Payments (transactions) will be processed as per the specified frequency until the transaction has been processed for the specified total count.

A unique ID will be assigned to the scheduled recurring payment when any recurring payment is created.  This ID can be used to update, delete or export recurring payments.


Create Recurring Payment

This method allows you to create a recurring payment with an existing customer from your Customer Database (Vault) within PayTrace.

Request URL

Post
 /v1/recurrence/create

Request Attributes

  

Required Attributes
AttributeDescriptionTypeAttribute Requirement
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note:  This ID should be from an existing customer ID within the PayTrace Vault to avoid API errors.
stringRequired
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
recurrenceRecurrence Payment detail. For supported Schema, Click here Recurrence_Record Schema.objectRequired
  

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
descriptionOptional 255 character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a transaction has been created.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.

Response Attributes

  

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
recurrenceFor supported Schema, Click here Recurrence_Record Schema.
Note:  ID will be the only parameter returned with the successful creation of a recurring payment.
object

Error with Recurring Payment

Error response will include a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.  

Error Example

If the customer_id customerid123 does not exist within the PayTrace vault, you will get an error response with an HTTP status code - 400 Bad request.


Update Recurring Payment

This method allows you to modify an existing recurring payment with a recurring payment ID.

Request URL

Post
 /v1/recurrence/update

Request Attributes

  

Required Attributes
AttributeDescriptionTypeAttribute Requirement
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
recurrenceRecurrence Payment detail. The ID is required and the remaining attributes are optional.
For supported Schema, Click here Recurrence_Record Schema.
objectRequired
  

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.
Note:  This ID should be an existing customer ID within the PayTrace Vault to avoid API errors.
stringOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a payment transaction is updated.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.

Response Attributes

  

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible values.number
status_messageThe status message about the request that provides additional information about the request execution end result.string
recurrenceFor supported Schema, Click here Recurrence_Record Schema.
Note:  ID will be the only parameter returned with a successful update request of a recurring payment.
object

Error with Recurring Payment

Error response will include an HTTP status code and JSON body with error information.   Check out API Errors for more information.

To check for unsuccessful transactions, check the success and response_code parameter values.   Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.   

Error Example

If the recurrence id or customer_id does not exist in the PayTrace vault, you will get an error response with an HTTP status code - 400 Bad request.


Delete Recurring Payment

This method allows you to permanently delete an existing recurring payment with just the recurring payment ID.

Request URL

Post
 /v1/recurrence/delete

Request Attributes

 

Required Attributes
AttributeDescriptionTypeAttribute Requirement
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
recurrenceRecurrence Payment detail. ID is the only parameter required.
For supported Schema, Click here Recurrence_Record Schema.
objectRequired

Optional Attributes: None

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a payment transaction is deleted.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.

Response Attributes

 

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
recurrenceFor supported Schema, Click here Recurrence_Record Schema.
Note:  ID will be the only parameter returned with a successful delete request of the recurring payment.

object

Errors with Recurring Payments

Error responses will include an HTTP status code and JSON body with error information.   Check out API Errors for more information.

To check for unsuccessful transactions, check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters with an HTTP status code - 400 Bad request.  


Export Recurring Payments

This method can be used to export a single recurring payment or all recurring payments for a specific customer.

Request URL

Post
 /v1/recurrence/export

Request Attributes

  

Required Attributes
AttributeDescriptionTypeAttribute Requirement
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) at PayTrace.

Note:  This ID should be an existing customer ID within the PayTrace Vault to avoid API errors.
stringRequired to find all recurring payments for a specific customer.
integrator_idA unique ID to correlate API consumer calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
recurrenceRecurrence Payment details. ID is the only parameter that is required.
For supported Schema, Click here Recurrence_Record Schema.
objectRequired to find a specific recurring payment transaction.

Optional Attributes: None

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a payment an export request is successful.  You will need to verify the success and response_code parameters.   Check out API Response Codes for possible values.

Response Attributes

  

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
recurrencesAn array of Recurrence Record objects.
For the supported schema, Click here Export_Recurrence_Record Schema.
Note: 
If the Request parameter is a recurrence ID, you will get an array of single recurrence transaction records.
If the Request parameter is a customer ID, you will get an array of one or more transaction records.
array of objects

Error with Recurring Payment

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful export requests, check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters with an HTTP status code.   

Error Example

If the customer ID or recurrence ID does not exist within the PayTrace vault, you will get an error response with an HTTP status code - 400 Bad request.


Export a Single Recurring Payment

This method can be used to export the most recent approved recurring payment transaction based on the specified customer profile.

Request URL

Post
 /v1/recurrence/export_approved

Request Attributes

 

Required Attributes
AttributeDescriptionTypeAttribute Requirement
customer_idA unique identifier for a customer profile stored within your Customer Database (Vault) at PayTrace.

Note:  This ID should be an existing customer ID within the PayTrace Vault to avoid API errors.
stringRequired
integrator_idA unique ID to correlate an API consumer's calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that an export request is successful.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.

Response Attributes

 

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
createdTransaction creation details. The 'at' attribute will be the only parameter used.
For supported Schema, Click here Response_Creation_Record Schema.
object
recurrenceRecurrence Payment detail.  ID will be the only parameter returned in a successful request.
For supported Schema, Click here Recurrence_Record Schema.
object
approval_codeThis code is generated by the credit card issuer and returned with a successful transaction.string
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.number
next_dateThe next date when a recurring transaction is scheduled to occur. The format should be - MM/DD/YYYY.string
discretionary_dataRecurrence payment discretionary data.
For supported Schema, check out Recurrence_Discretionary_Data Schema on the same page.
object
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.string
 

Recurrence_Discretionary_Data Schema
AttributeDescriptionType
TOTALCOUNTThe total number of times the recurring payment transaction should be processed.
It should be set to 999 if the recurring payment transaction should be processed indefinitely.
string
CURRENTCOUNTThe number of times this payment has been processed in context to the total number of scheduled payments.
The payment(s) will end when the current count is equal to the total count unless the total count is set to 999 (infinite).
string


Error with Recurring Payment

Error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful export requests, please check the success and response_code parameter values.  Check out API Response Codes for possible values.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters with an HTTP status code.  

Error Example

If the customer ID does not have any recurring transactions, you will get an error response with an HTTP status code - 400 Bad request.


Update Password

This method can be used to update a Web User or an API User password.  Web user passwords must be changed at least once every 90 days, while API User passwords/tokens must be changed once a year.

To find out more detail about the PayTrace user, Check out this page PayTrace User Profiles.

Request URL

Post
 /v1/password/change

Request Attributes

 

Required Attributes
AttributeDescriptionTypeAttribute Requirement
new_passwordA new password to be updated.stringRequired
integrator_idA unique ID to correlate an API consumers' calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required

Optional Attributes: None


Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a password has been updated.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

After a successful password update request, the User will be logged out immediately and required to use the new password to log back in.  

Response Attributes

 

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request and provides additional information about the request execution end result.string

Error with Update Password

If a new password does not meet the password requirements, an error response will be returned.

The error response will include an HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check for unsuccessful requests, check the success and response_code parameter values.  Check out API Response Codes for possible values.

You will get an API error response with an invalid Request or input Parameters.  

Error Example

If the new password is similar to the last 5 passwords, you will get an error response with an HTTP status code - 400 Bad request.


ACH Processing

Check or ACH (Automated Clearing House) transactions can be processed through the PayTrace API.  If you would like to enable check processing within your account, you will need to contact your Merchant Service Provider. They will be able to enable check processing for you within PayTrace.


Sale by account

Check or ACH (Automated Clearing House) Sale transactions can be performed with this method by providing the customer's key entered checking account details.

Request URL

Post
 /v1/checks/sale/by_account

Request Attributes

 

Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
checkThe checking account details. For supported Schema, Click here Check Schema.objectNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers' calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor the supported Schema, Click here Billing_Address Schema.objectThe Billing Address Name is required. The Billing Address and Billing ZIP may be required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
 

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor the supported schema, click here shipping_address.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
descriptionOptional 255 character length max text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema, Click here Discretionary_Data SchemaobjectOptionalobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a check transaction is approved.  You will need to verify the success and response_code parameters.  Check out API Response Codes for possible values.

Additional verification can be performed with the ach_code and ach_message parameters if the check is processed by a real-time check processor.          

Response Attributes

 

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
check_transaction_idA unique identifier for each check transaction in the PayTrace system.number
ach_codeThis code is generated and returned by the real-time check processor when the check is processed.
0 (zero) indicates that the check was accepted.
number
ach_messageA message generated by the real-time check processor.string

Error with ACH Sale

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, check the success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters ach_code and ach_message.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.                 

Declined Transaction Example

With a declined check transaction, the appropriate response code will be returned in the error response.

You will get a declined transaction response when a check sale transaction is declined by the real-time check processing network.          

For example, if a check transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.

Vault Sale

This method allows you to process a check transaction with an existing Customer ID (Token) from your Customer Database (Vault) within PayTrace.

Request URL

Post
 /v1/checks/sale/by_customer

Request Attributes

 

Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountThe dollar amount of the transaction. This must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
customer_idA unique identifier for a customer profile stored in your Customer Database (Vault) within PayTrace.

Note: This id should be an existing customer id with ACH details at PayTrace Vault to avoid API errors.
stringNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers' calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor the supported Schema, Click here Billing_Address Schema.objectBilling Address Name required. Billing Address and Billing ZIP may be required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required
invoice_idA unique identifier for the transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled within the PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
 

Optional Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailThe customer's email address where the transaction receipt will be sent.stringOptional
descriptionOptional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction.stringOptional
tax_amountThe portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt.stringOptional
customer_reference_idThe customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number.stringOptional
discretionary_dataDiscretionary data details. For the supported schema Click here Discretionary_Data SchemaobjectOptional

Successful Response

A successful request returns an HTTP status code in the 2XX range with a JSON body.

An HTTP status code in the 2XX range does not indicate that a check transaction is processed. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.

Additional verification can be performed with ach_code and ach_message parameters if the check is processed by a real-time check processor.      

Response Attributes

 

Toggle the Attributes details
AttributeDescriptionType
successThis flag will indicate if the request is successful.
Possible values : true/false.
True indicates that the request was successful and had no errors.
False indicates that the request was not successful and some kind of error has occurred.
boolean
response_codeThis code will show you the response code based on the request execution status. Check out API Response Codes for possible valuesnumber
status_messageThe status message about the request that provides additional information about the request execution end result.string
check_transaction_idA unique identifier for each check transaction within the PayTrace system.number
ach_codeThis code is generated and returned by the real-time check processor when the check is processed.
0 (zero) indicates that the check was accepted.
number
ach_messageA message generated by the real-time check processor.string

Error with Vault Sale

Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.

To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.

Additional error information can be retrieved from the response parameters ach_code and ach_message.  Test data can be found here.

You will get an API error response with an invalid Request or input Parameters.           

Declined Transaction Example

With a declined check transaction, the appropriate response code will be returned in the error response.

You can get a declined transaction response only when a check transaction is declined by the real-time check processing network.      

For example, if a check transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request.

Hold by account

Check or ACH (Automated Clearing House) hold transactions can be performed with this method by providing customer's key entered checking account details. Fund will not be transferred until this check transaction is captured or funded.

Check processor Paya doesn't support check hold transactions.      

Request URL

Post
 /v1/checks/hold/by_account

Request Attributes

 

Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
amountDollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
checkCheck account detail. For supported Schema, Click here Check Schema.objectNo configuration settings applied.

Required
integrator_idA unique ID to correlate an API consumers calls to the PayTrace system.

If you have not been assigned an Integrator ID, please request one on our Sandbox Request page.
stringNo configuration settings applied.

Required
billing _addressFor supported Schema, Click here Billing_Address Schema.objectBilling Address Name required. Billing Address and Billing ZIP may be required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled from PayTrace Virtual Terminal → Account → Security Settings page.

Required
invoice_idA unique identifier for this transaction in your accounting or inventory management system.stringThis attribute is only required if the "Require Invoice" field is enabled from PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured
 

Optional Attrib