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 the web server or client computer that is running the software application.   Integration with PayTrace API is easy and quick 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 methods.  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 JSON API is v1.

Get started

Are you ready to get started with PayTrace API?


Here are the steps you may need to follow to start an integration with PayTrace API.

1 Request a Sandbox account : To sign up and test your integration with the API module enabled.  Our sandbox account allows you to test all of our solutions with API.  This sandbox user request will provide you information about your integration with PayTrace and your sandbox user credentials.
2 Check out the PayTrace virtual Terminal→Account→Security settings for configuring additional mandatory parameters for your account.  After configuring any additional parameters from Security settings, those must be sent with relevant requests.Please check out Account Security settings for API here.

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

API_Logs.png
7 Once you are done with testing phase, Go live by requesting Active account from the preferred PayTrace Reseller.
8 To go live, you must have a PayTrace Professional account with API Module enabled. Those user credentials can be used for PayTrace virtual Terminal to create a PayTrace API user account to API.

Please Note: PayTrace uses API user credentials instead of API key for Authentication.
9 Once your integration is complete, we recommend that your users use their API User Account credentials with your integration.
10 Do not forget to Check out PayTrace virtual Terminal→Account→Security settings(as shown above) for configuring additional mandatory parameters for the individual live account.
After configuring any additional parameters from Security settings, those must be sent with relevant requests otherwise may turn into an API error for required parameters.  Please check out your Account Security settings for API.

Please Note: If you do not see Account → Security settings option on PayTrace Virtual Terminal, please contact the Account Administrator to enable the Account option on Virtual Terminal for you.

Client Side Encryption Library

The PayTrace Encryption Library supports client-side encryption of the sensitive data, reduces merchants and integrators exposure to PCI-compliance verification. Sensitive data can be encrypted at the user's web browser using a PayTrace JavaScript Encryption Library. These encrypted data can only be decrypted by PayTrace. The merchant or integrator has no access to the original sensitive data.


Benefits of using PayTrace Client Side Encryption Library
  • This 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

PayTrace Client Side Encryption Library Workflow

PayTrace_Javacsript_Diagram.png

Encryption Detail

The sensitive data are encrypted before the web form is submitted until it is received at PayTrace's secure server. 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 Client Side Encryption Library?

  1. Get your account specific public key and save it with your environment.
  2. Incorporate PayTrace Client Side Encryption Library in a web form.
  3. Submit encrypted values to the API.

How to get a public Key?

  1. Log into your PayTrace account or Sandbox Account from 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 PayTrace Client Side Encryption Library in a web form?

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

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

     Please refer the code section Sample →

2. On sensitive data fields to 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 those encrypted values using name attribute on the server.  Please refer 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 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?

To use encrypted values that your server has received from a Web form, you must submit them as a request parameter values to the API. You will need to prepend request parameter name with encrypted_before sending the request to the API.

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

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

API Parameters Summary

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

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

Specific required and optional parameter list is given with each API Method.
Level 3 request parameters detail is provided with related card methods.   

Required Request Parameters
Attribute Description Data Type Length
amount Dollar amount of the transaction. Must be a positive number up to two decimal places. number 1-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 from PayTrace Virtual Terminal → Account → Security Settings page.
Object -
credit_card Credit 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. CSC is found on the front of AMEX cards.

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

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

Note: This id should be an existing customer id at PayTrace Vault to avoid API errors.
string
Data Format
1-25
end_date End date is used to indicate when to end searching for transactions to export.
Must be a valid date formatted as MM/DD/YYYY.
string 10
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 from PayTrace Virtual Terminal → Account → Security Settings page.
string
Data Format
1-50
new_password A new password to be updated. string
Data Format
7-50
start_date Start date is used to indicate when to start searching for transactions to export.
Must be a valid date formatted as MM/DD/YYYY.
string 10
swipe or encrypted_swipe 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 instead when submitting encrypted swipe value by the PayTrace Client Side Encryption JavaScript Library.
string
Data Format
255+
transaction_id A unique identifier for each transaction in the PayTrace system.

Note: It should be a reference of legitimate transaction with PayTrace system in a past to avoid any API errors.
number 1-9

* Request parameters are configurable from PayTrace Virtual Terminal → Account → Security Settings page. Must be provided with request (if configured, results in an error when missing)


Optional Request Parameters
Attribute Description Data Type Length
batch_number A batch number to find specific batch details. This value is the sequential number assigned to the batch. number 1-3
created Transaction or batch or customer creation details.
For supported Schema, Click here Request_Creation_Record Schema.
object -
custom_dba 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_id 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. string
Data Format
1-17
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string
Data Format
1-255
email Customer's email address where the Sales/Authorizations/Refunds receipt may be sent. string
Data Format
1-50
enable_partial_authorization 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.
boolean -
fax Customer's fax number (i.e. 555-555-5555, or 5555555555). string
Data Format
10,12,13
include_bin If set to true, this will return the first 6 and last 4 digits of the card number. boolean -
including_text The text submitted will be used to locate transactions containing this text, to narrow down the export results. string
Data Format
1-255
new_id A new unique identifier for a customer profile that may be sent with a request to update a customer profile. string 1-25
phone Customer's phone number (i.e. 555-555-5555, or 5555555555). string
Data Format
10,12,13
recurrence Recurrence Payment detail. For supported Schema, Click here Recurrence_Record Schema. object -
return_clr If 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_address Customer's shipping address detail.
For supported schema, click here Shipping_Address Schema.
object -
tax_amount 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. number 1-12
transaction_type The transaction type to find transactions.
Possible values : SALE, AUTHORIZATION, REFUND, VOID,
CAPTURE, FORCE, SETTLED, PENDING, DECLINED.
string 4-13
discretionary_data future enhancement coming soon!


Response Parameters
Attribute Description Data Type Length
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number 3-4
status_message Status message about the request and provides additional information about the request execution end result. string 1-255
approval_code This approval code is generated by the credit card issuer and returned with a successful transaction. string
Data Format
6
approval_message A response from the credit card issuer with a successful requested transaction. string
Data Format
1-255
avs_response A unique string identifier returned by the AVS. Check out AVS Response for the possible values. string
Data Format
1-255
csc_response A 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
transaction_id A unique identifier for each transaction in the PayTrace system. number 1-9
external_transaction_id A unique identifier of the request from your system that will be returned in the response. string
Data Format
1-50
masked_card_number Credit card number with all digits masked and replaced with 'x' except last 4 digits.

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

It is an array of transaction detail record objects for the given date range or single transaction.
Note : Those transaction details contains discretionary data.
For supported Schema, Click here Transaction_Detail_Record Schema
array of objects -
created Transaction/Batch/Customer record creation details.
For supported Schema, Click here Response_Creation_Record Schema.
object -
next_date The next date when recurring transaction is scheduled to occur.
Format will be : MM/DD/YYYY.
string 10
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string
Data Format
1-255
amount Dollar amount of the transaction. Must be a positive number up to two decimal places. number 1-12
discretionary_data Discretionary_data details.
For 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 JSON API



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

Use encrypted_number attribute instead 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 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
nameCName 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_address2Second 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 ayTrace 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 delivered.stringOptional
street_addressAddress where the product is delivered.stringOptional
street_address2Second line of the address where the product is delivered.stringOptional
cityCity where the product is delivered.stringOptional
stateState where the product is delivered.stringOptional
zipZIP code where the product is 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 has originally requested the customer profile or transaction be created or processed.string
atThe date and time when transaction was first processed or the customer profile was created or Batch was initiated/Processed. Format will be a general date (i.e. MM/DD/YYYY HH:MM:SS)string
byThe PayTrace username who has created the transaction or customer profile you are trying to export.string
from_ipIP address of the computer that has originally requested the customer profile or transaction be created or processed.
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 attributes name 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 supported Schema, Click here Credit_Card Schema.object
billing _addressFor supported Schema, Click here Billing_Address Schema.object
shipping_addressFor supported schema, Click here shipping_address Schema.object
checkCheck account detail. For supported Schema, Click here Check Schema.
Note: This object will be included ONLY when customer has a check data.
object
emailCustomer's email address where the transactions 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 supported Schema, Click here Response_Creation_Record Schema.object
discretionary_dataDiscretionary_data details. For 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 supported Schema, Click here Credit_Card Schema.object
transaction_typeThe transaction type to find transactions.
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
amountDollar amount of the transaction. 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 supported schema, click here shipping_address Schema.object
billing_addressFor supported Schema, Click here Billing_Address Schema.object
receipt_emailed_toCustomer's email address where the Authorizations receipt may be sent.string
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.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 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 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 :Only this parameter can be used as a request parameter for some methods.
number
american_expressAmerican Express Card details. For supported schema, Click here Batch_Cards Schema.object
diners_clubFor supported schema, Click here Batch_Cards Schema.object
discoverDiscover Card details. For supported schema, Click here Batch_Cards Schema.object
master_cardMaster Card details. For supported schema, Click here Batch_Cards Schema.object
private_labelFor supported schema, Click here Batch_Cards Schema.object
visaVisa Card details. For 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
salesTotal number of sales (count) that were settled in the exported batch with specific card type.number
collectedTotal sum of sales amount that were settled in the exported batch with specific card type.number
refundsTotal number of refunds(count) that were settled in the exported batch with specific card type.number
refundedTotal sum of refund amounts that were settled in the exported batch with specific card type.number




Batch_Summary_Records Schema
AttributeDescriptionType
numberA sequential number assigned to the settlement batch.number
createdBatch creation details.
Note: Only at attribute will be returned with a date.
For supported schema, click here Response_Creation_Record Schema.
object
transaction_countTotal 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_countTotal number of sales included in a batch.number
sales_amountTotal amount of sales included in a batch.number
refund_countTotal number of refunds included in a batch.number
refund_amountTotal 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 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 transaction, products, customers, or other attributes of the transaction.string
amountDollar amount of the transaction. 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 supported schema, Click here shipping_address Schema.object
billing_addressFor supported Schema, Click here Billing_Address Schema.object
receipt_emailed_toCustomer's email address where the Authorizations receipt may be sent.string
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.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 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 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




Recurrence_Record Schema

Only id will be a 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 successful recurring payment is created, updated or deleted.
numberRequired for Update,
Delete and Export methods.
amountDollar amount of the transaction. 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 Customer's registered email.
false - Default value to not to send the transaction receipt.
true - to send the transaction receipt.

Note: 
Returns an error if 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 - for annually,
8 - for semi-annually,
A - for trimesterly,
2 - for quarterly,
9 - for bi-monthly,
3 - for monthly,
4 - for bi-weekly,
7 - for 1st and 15th,
5 - for weekly,
6 - for daily.
stringRequired for Create Method
Optional for Update Method
start_dateDate the recurring transaction should be processed for the first time. 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 payment.
Default value is "C" which represents credit card.
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 a returned when successful recurring payment is created, updated or deleted.
number
amountDollar amount of the transaction. 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 recurring transaction is scheduled to occur. 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 total number of scheduled payment.
The payment will be completed when current count is equal to total count unless total count is set to 999(infinite).
number
repeat_countThe number of the days after a decline 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_numberChecking account number for processing check transactions or managing customer profiles.numberRequired
routing_numberRouting number for processing check transactions or managing customer profiles.numberRequired
masked_account_numberMasked checking account number for processing check transactions or managing customer profiles.
Note: This parameter will be returned with export check transaction requests instead of plain account number.
stringNA
masked_routing_numberMasked Routing number for processing check transactions or managing customer profiles.
Note: This parameter will be returned with export check transaction requests instead of 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: Masked parameter will be used for check account details.
object
check_typeThe check type to find transactions.
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
amountDollar amount of the transaction. 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 supported schema, click here shipping_address Schema.object
billing_addressFor supported Schema, Click here Billing_Address Schema.object
receipt_emailed_toCustomer's email address where the Authorizations receipt may be sent.string
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.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
status_codeA code that shows 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
createdTransaction creation details.
For 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 supported Schema, Click here Discretionary_Data Schema.object

API Sample Code

Following sample codes are available on github.

Authentication

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

OAuth 2.0 provides a "password" grant type which can be used to exchange a username and password for an access token directly.  If you decide not to use any 3rd party OAuth 2. 0 libraries, following steps are needed :

  1. You can simply make a request to our API with your API account user credentials and get the Bearer type access token.
  2. Then use the Bearer Access token in a 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 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 a 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

Error with Authentication

Error response will include a HTTP status code and JSON body.  In general, code 4XX and 5XX ranges indicate some failure for authentication token request.

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


Authentication Error Response Attributes
AttributeDescriptionType
errorA unique identifier for error. Please refer Authentication Errors Summary to find out all values.string
error_descriptionError message providing details about the error. Please refer Authentication Errors Summary to find out 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, 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 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 an incorrect API user credentials, you will get an error Response with appropriate error and error description with a HTTP status code 401-unauthorized.

How to utilize Authentication token in 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 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 Code Status Message Reason
1 One 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.
100 Your password was successfully updated. Returned when a request to Update Password is successfully processed.
101 Your transaction was successfully approved. Returned when a request to process a sale or authorization transaction generates an approved transaction.
102 Your transaction was not approved. Returned when a request to process a sale or authorization transaction does not generate an approved transaction.
103 Your 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.
106 Your transaction was successfully refunded. Returned when a request to process a refund generates an completed transaction.
107 Your transaction was not successfully refunded. Returned when a request to process a refund does not generate a completed transaction.
108 Your 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.
109 Your transaction was successfully voided. Returned when a request to void a transaction generates a voided transaction.
110 Your transaction was not successfully voided. Returned when a request to void a transaction does not generate a voided transaction.
112 Your transaction was successfully captured. Returned when a request to capture a transaction generates a captured transaction.
113 Your transaction was not successfully captured. Returned when a request to capture a transaction does not generate a captured transaction.
120 Your check was successfully processed. Returned when a request to process a sale or hold check is successful.
122 Your check was successfully refunded. Returned when a request to refund a check is successful.
124 Your check was successfully managed. Returned when a request to manage a check for void or fund is successfully processed.
125 Your 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.
149 The receipt for transaction ID ######## was successfully emailed to email address. Returned when a request to email a receipt is successfully processed.
150 The recurring transaction was successfully created. Returned when a request to create a recurring payment is successfully processed.
151 The recurring transaction was successfully updated. Returned when a request to update a recurring payment is successfully processed.
152 The recurring transaction was successfully deleted. Returned when a request to delete a recurring payment is successfully processed.
155 This customer's most recent recurring transaction took place on DD/MM/YYYY. Returned when a request to export a customer's recurring payment is successfully processed.
160 The customer profile for customer ID/customer Name was successfully created. Returned when a request to create a customer profile is successfully processed.
161 The customer profile for customer ID/customer Name was successfully updated. Returned when a request to update a customer profile is successfully processed.
162 The customer profile for customer ID/customer Name was successfully deleted. Returned when a request to delete a customer profile is successfully processed.
170 Visa 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.
171 MasterCard 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.
175 The batch was successfully initiated, and the batch report will be sent to: email@address.com, email2@address.com in just a few moments. Returned when a request to settle transactions is successful. The response will also include the Batch Number, Transaction Count, and Net Amount.
180 The 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 code Reason
200-OK Request worked as expected.
400-Bad Request Any invalid Request parameters/values, Required parameters are missing or a declined transaction.
401-Unauthorized When access token is invalid or expired.
500-Internal server errors Error 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

Additional errors object will be included when 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 validating 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 with out a card number or processing a check transaction.
46Please provide a valid Transit Routing Number.Required if creating a customer with out 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.
54Cash Advances may only be processed as Sales.Cash Advances must be processed as Sale transaction types. 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. 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 voided a transaction or an unsettled transaction.Only settled transactions sales 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 transactions approval code has expired as it was obtained more than 20 days ago.Transactions must be captured with in 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. So, a declined sale, or a settled sale or refund 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 may 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 may 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 may 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's 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 must have correct format.
118Please provide a valid Billing Address.Optional field for transactions and customers must have correct format. May be required if configured in your security settings.
119Please provide a valid Billing Address 2.Optional field for transactions and customers must have correct format.
120Please provide a valid Billing City.Optional field for transactions and customers must have correct format.
121Please provide a valid Billing State.Optional field for transactions and customers must have correct format.
122Please provide a valid Billing Zip Code.Optional field for transactions and customers must have correct format. May be required if configured in your security settings.
123Please provide a valid Billing Country.Optional field for transactions and customers must have correct format.
124Please provide a valid Shipping Name.Optional field for transactions and customers must have correct format.
125Please provide a valid Shipping Address.Optional field for transactions and customers must have correct format.
126Please provide a valid Shipping Address 2.Optional field for transactions and customers must have correct format.
127Please provide a valid Shipping City.Optional field for transactions and customers must have correct format.
128Please provide a valid Shipping County.Optional field for transactions and customers must have correct format.
129Please provide a valid Shipping State.Optional field for transactions and customers must have correct format.
130Please provide a valid Shipping Zip Code.Optional field for transactions and customers must have correct format.
131Please provide a valid Shipping CountryOptional field for transactions and customers must have correct format.
132Please provide a valid Phone Number.Optional field for transactions and customers must have correct format.
133Please provide a valid Source State.Required for calculate shipping requests.
134Please provide a valid Source Zip Code.Required for calculate shipping requests.
135Please provide a valid list of Shippers.Required for calculate shipping requests.
136Please provide a valid Weight.Required for calculate shipping requests.
137Please provide a valid Fax Number.Optional field for transactions and customers must have correct format.
139Please make sure the Shipping State and Shipping Zip are accurate.Returned if errors are returned from shipping provider(s) during calculate 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 must have correct format. Required to email a receipt.
148Please provide a valid CSC.Optional field for transactions and must have correct format. May be required if configured in your security settings.
149Please provide a valid Invoice Number.Optional field for transactions and must have correct format.
150Please provide a valid Description.Optional field for transactions and must have correct format.
151Please provide a valid Tax Amount.Optional field for transactions and must have correct format.
152Please provide a valid Customer Reference.Optional field for transactions and must have 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 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.A start date is required to create a recurring payment.
163Please provide a valid Next Date.A 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.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 past/greater than the start date.
178Please provide a valid User.User account for exporting transaction reports.
179Please provide a valid number of Days.The 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 and must have correct format.
191Please provide a valid Merchant Tax ID.Optional field for level 3 data and must have correct format.
192Please provide a valid Customer Tax ID.Optional field for level 3 data and must have correct format.
193Please provide a valid Commodity Code.Optional field for level 3 data and must have correct format.
194Please provide a valid Discount Amount.Optional field for level 3 data and must have correct format.
195Please provide a valid Freight Amount.Optional field for level 3 data and must have correct format.
196Please provide a valid Duty Amount.Optional field for level 3 data and must have correct format.
197Please provide a valid Additional Tax Amount.Optional field for level 3 data and must have correct format.
198Please provide a valid Additional Tax Rate.Optional field for level 3 data and must have correct format.
199Please provide a valid Additional Tax Indicator.Optional field for level 3 data and must have correct format.
200Please provide a valid Line Item record.Required field for level 3 data and must have correct format.
201Please provide a valid Line Item Commodity Code.Optional field for level 3 data and must have correct format.
202Please provide a valid Line Item Description.Optional field for level 3 data and must have correct format.
203Please provide a valid Line Item Product ID.Optional field for level 3 data and must have correct format.
204Please provide a valid Line Item Quantity.Optional field for level 3 data and must have correct format.
205Please provide a valid Line Item Measure.Optional field for level 3 data and must have correct format.
206Please provide a valid Line Item Unit Cost.Optional field for level 3 data and must have correct format.
207Please provide a valid Line Item Additional Tax Amount.Optional field for level 3 data and must have correct format.
208Please provide a valid Line Item Additional Tax Rate.Optional field for level 3 data and must have correct format.
209Please provide a valid Line Item Discount.Optional field for level 3 data and must have correct format.
210Please provide a valid Line Item Amount.Optional field for level 3 data and must have correct format.
211Please provide a valid Line Item Additional Tax Indicator.Optional field for level 3 data and must have correct format.
212Please provide a valid Line Item Discount Rate.Optional field for level 3 data and must have correct format.
213Please provide a valid Line Item Discount Indicator.Optional field for level 3 data and must have correct format.
214Please provide a valid Line Item Net Gross Indicator.Optional field for level 3 data and must have correct format.
215Please provide a valid Line Item Debit Credit Indicator.Optional field for level 3 data and must have 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.
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 with in 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 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.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.Transaction ID isn't found on their 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 uncpatured, approved authorizations can be captured.Transaction ID exists but it's 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 it's 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 it's 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 schedule 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 with out 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.
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 receipt, export transactions, and update password requests.
978Your account is not set up to process checks.Checks 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 into virtual terminal to reset 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 log in 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.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. Few parameters are case sensitive.
For example: number as "NUMBER" , encrypted_csc as "ENCRYPTED_CSC"
998Log in failed.An unsuccessful log in attempt occurred. With either of the following reasons.
1. The account is disabled.
2. 4 consecutive unsuccessful log in attempts which will disabled a user account.
999Log in failed for insufficient permissions.The user account must have permission/access to process a sale.
1000Decryption failed.Encrypted request data should be encrypted with merchant account specific public key only.

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 Type Credit Card Number *Expiration MM/YY
Visa 4012000098765439 12/20
MasterCard 5499740000000057 12/20
Discover 6011000993026909 12/20
American Express 371449635392376 12/20

*Any valid expiration month and year will work too.


Testing CSCs
Credit Card Type CSC Number Response
Visa 999 Approval
MasterCard 998 Approval
Discover 996 Approval
American Express 9997 Approval

Testing Addresses for AVS Response

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 code Response Text
8320 - Address Match
- 85284 Zip Match
8320 85284 Exact Match
- 99999 Ver Unavailable

Testing Amount

$1.00 or more amount should give an approval response.

Amount Response Text
$0.00 Amount Error
$0.01 Call
$0.02 Call
$0.05 Hold - Call
$0.06 Hold - Call
$0.07 Hold - Call
$0.08 Hold - Call
$0.20 Decline
$0.21 Decline
$0.22 Decline
$0.23 Decline
$0.24 Decline
$0.25 Decline
$0.26 Decline
$0.29 Expired Card
$0.39 No Such Issuer
$0.41 RE-ENTER
$0.43 Serv Not Allowed
$0.44 Serv Not Allowed
$0.48 CVV Mismatch
$0.49 Card OK
$0.50 APPROVAL
$0.51 Prompt for Level II Data
$0.53 Prompt for Level 3 Data
$1.00 or more APPROVAL
$1.12 Decline
$1.13 Decline

Testing ACH
Checking account number Routing number
123456 325070760

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)

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
(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
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 instead when submitting encrypted CSC value by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from 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 from 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 PayTrace Virtual Terminal → Account → Security 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 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 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 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
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
masked_card_numberCredit card number with all digits masked and replaced with 'x' except last 4 digits.

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

Error with Keyed Sale

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 transactions, please check 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 any invalid Request or input Parameters.           

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, 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 a 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)
amountDollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
swipe or encrypted_swipeString 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 instead 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 instead when submitting encrypted CSC value by the PayTrace Clien-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled from 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 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 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 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 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
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 Sale

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 transactions, please check 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.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, 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 a 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 transactions made with PayTrace.

Request URL

Post
 /v1/transactions/sale/by_transaction

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
transaction_idA unique identifier for each transaction in the PayTrace system.

Note: It should be a reference of legitimate transaction with 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 instead when submitting encrypted CSC value by the PayTrace Client Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from 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 from 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 PayTrace Virtual Terminal → Account → Security 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
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.

A 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 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
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 Transaction Id

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 transactions, please check 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.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, 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 a 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)
amountDollar amount of the transaction. 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 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
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 value by the PayTrace Client Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from 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 from 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 PayTrace Virtual Terminal → Account → Security 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
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.

A 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 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
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

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 transactions, please check 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.

Declined Transaction Example

If a sale transaction is declined by the processing network due to any reason, 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 a HTTP status code - 400 Bad request.  Test data can be found here.


Authorization

An Authorization transaction verifies a customers 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 customers 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)
amountDollar 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 instead when submitting encrypted CSC value by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from 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 from 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 PayTrace Virtual Terminal → Account → Security 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.booleanOptional
custom_dbaOptional 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_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 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 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 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
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
masked_card_numberCredit card number with all digits masked and replaced with 'x' except last 4 digits.

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

Error with Keyed Authorization

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 transactions, please check 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 any invalid Request or input Parameters.     

Declined Transaction Example

If an Authorization transaction is declined by the processing network due to any reason, 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 a HTTP status code - 400 Bad request. Test data can be found here.


Swiped Authorization(Card Present)

Swiped Authorization can be performed when a Credit card is present.

This Method verifies a customers 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)
amountDollar amount of the transaction. Must be a positive number up to two decimal places.numberNo configuration settings applied.

Required
swipe or encrypted_swipeString 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 instead 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 instead when submitting encrypted CSC value 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 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 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_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_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 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 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 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
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 Authorization

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 transactions, please check 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.

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

Declined Transaction Example

If a Authorization transaction is declined by the processing network due to any reason, 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 a 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 transactions made with 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)
amountDollar 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: It should be a reference of legitimate transaction with 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 instead when submitting encrypted CSC value by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from 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 from 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 PayTrace Virtual Terminal → Account → Security 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
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.

A 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 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
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 Authorization By Transaction Id

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 transactions, please check 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.

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

Declined Transaction Example

If an authorization transaction is declined by the processing network due to any reason, 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 a 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)
amountDollar amount of the transaction. 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 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
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 value by the PayTrace Client-Side Encryption JavaScript Library.
stringThis attribute is only required if the "Required CSC" field is enabled from 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 from 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 PayTrace Virtual Terminal → Account → Security 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.booleanOptional
custom_dbaOptional 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_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 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 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 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
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 Authorization By Customer Id

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 transactions, please check 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 any invalid Request or input Parameters.    

Declined Transaction Example

If an authorization transaction is declined by the processing network due to any reason, 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 a 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 the payment. Unsettled and preauthorized transaction id should be provided for a successful capture.

If an amount parameter is not submitted, 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: It should be Unsettled and pre authorized transaction with PayTrace system to avoid any API errors.
numberRequired

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

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


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 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 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
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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

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

Declined Transaction Example

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

For example, if transaction is not captured, you will get a declined transaction response with a 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
Attribute Description Type Attribute Requirement
transaction_id A unique identifier for each transaction in the PayTrace system.

Note: It should be Unsettled transaction with PayTrace system to avoid any API errors.
number 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 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
transaction_id A unique identifier for each transaction in the PayTrace system. number

Error with Void Transaction

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 transactions, 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.

Declined Transaction Example

If a void transaction is declined by the processing network due to any reason, 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.  Following conditions must be fulfilled for the successful transaction.

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

Request URL

Post
 /v1/transactions/adjust

Request Attributes


Required Attributes
AttributeDescriptionTypeAttribute Requirement
amountDollar 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 with PayTrace system to avoid any API errors.
stringRequired

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 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 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 Adjust Transaction

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 transactions, please check 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 adjustment criteria (described as earlier), error response with a HTTP status code - 400 Bad request.  Test data can be found here.


Refund Transaction

A Refund transaction allows to issue a fund 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 Refund 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.  

Request URL

Post
 /v1/transactions/refund/keyed

Request Attributes


Required Attributes
Attribute Description Type Configuration
(Must provide if configured, results in an error when missing)
amount Dollar amount of the transaction. Must be a positive number up to two decimal places. number No configuration settings applied.

Required
credit_card For supported Schema, Click here Credit_Card Schema. Object No configuration settings applied.

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

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

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

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

Required if configured

Optional Attributes
Attribute Description Type Attributes Requirements
shipping_address For supported schema, Click here shipping_address Schema. object Optional
email Customer's email address where the Refunds receipt may be sent. string Optional
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string Optional
tax_amount 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 Optional
customer_reference_id 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. string Optional
discretionary_data Discretionary data details. For supported schema, Click here Discretionary_Data Schema object Optional


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 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
transaction_id A unique identifier for each transaction in the PayTrace system. number
external_transaction_id A unique identifier of the request from your system that will be returned in the response. string
masked_card_number Credit card number with all digits masked and replaced with 'x' except last 4 digits.

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

Error with Keyed Refund

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 transactions, 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.  


Swiped Refund(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/refund/swiped

Request Attributes


Required Attributes
Attribute Description Type Configuration
(Must provide if configured, results in an error when missing)
amount Dollar amount of the transaction. Must be a positive number up to two decimal places. number No configuration settings applied.

Required
swipe or encrypted_swipe 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 instead when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library.
string No configuration settings applied.

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

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

Required if configured
billing _address For supported Schema, Click here Billing_Address Schema. object This 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_id A unique identifier for this transaction in your accounting or inventory management system. string This attribute is only required if the "Require Invoice" field and "Required on Swiped" are enabled from PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

Optional Attributes
Attribute Description Type Attributes Requirements
shipping_address For supported schema, Click here shipping_address Schema. object Optional
email Customer's email address where the Refunds receipt may be sent. string Optional
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string Optional
tax_amount 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 Optional
customer_reference_id 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. string Optional
discretionary_data Discretionary data details. For supported schema, Click here Discretionary_Data Schema object Optional


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 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
transaction_id A unique identifier for each transaction in the PayTrace system. number
external_transaction_id A unique identifier of the request from your system that will be returned in the response. string

Error with Swiped Refund

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 transactions, 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.  

Declined Transaction Example

If a refund transaction is declined by the processing network due to any reason, 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 a 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 amount is submitted, specific amount will be refunded with the credit card used in the referred transaction.

Request URL

Post
 /v1/transactions/refund/for_transaction

Request Attributes


Required Attributes
Attribute Description Type Configuration
(Must provide if configured, results in an error when missing)
amount Dollar amount of the transaction. Must be a positive number up to two decimal places.

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

Required
transaction_id A unique identifier for each transaction in the PayTrace system.

Note: It should be a reference of legitimate transaction with PayTrace system in a past to avoid any API errors.
number No configuration settings applied.

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

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

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

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

Required if configured

Optional Attributes
Attribute Description Type Attributes Requirements
shipping_address For supported schema, Click here shipping_address Schema. object Optional
email Customer's email address where the Refund receipt may be sent. string Optional
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string Optional
tax_amount 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 Optional
customer_reference_id 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. string Optional
discretionary_data Discretionary data details. For supported schema, Click here Discretionary_Data Schema object Optional


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 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
transaction_id A unique identifier for each transaction in the PayTrace system. number
external_transaction_id A 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful transactions, 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.  


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
Attribute Description Type Configuration
(Must provide if configured, results in an error when missing)
amount Dollar amount of the transaction. Must be a positive number up to two decimal places. number No configuration settings applied.

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

Note: This id should be an existing customer id at PayTrace Vault to avoid API errors.
string No configuration settings applied.

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

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

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

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

Required if configured

Optional Attributes
Attribute Description Type Attributes Requirements
shipping_address For supported schema, Click here shipping_address Schema. object Optional
email Customer's email address where the Refund receipt may be sent. string Optional
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string Optional
tax_amount 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 Optional
customer_reference_id 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. string Optional
discretionary_data Discretionary data details. For supported schema, Click here Discretionary_Data Schema object Optional


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 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
transaction_id A unique identifier for each transaction in the PayTrace system. number
external_transaction_id A 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful transactions, please check 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 any 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

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 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 requirement of storing sensitive payment information.  Those customer Ids can be used with future transactions. When existing Customer Id is used for any transactions, 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 at 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 at 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.
checkCheck 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" is enabled from PayTrace Virtual Terminal → Account → Security 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 transactions receipt may be sent.stringOptional
phoneCustomer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxCustomer'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 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 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 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
customer_idA unique identifier for each customer in the PayTrace system, value will be same as provided with the request.string
masked_card_numberCredit card number with all digits masked and replaced with 'x' except last 4 digits.

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

Error with Create Customer Profile

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.  Test data can be found here.

Error Example

If provided customer id already exists in the database, you will get an error response with a 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 at 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 of legitimate transaction with 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
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 from PayTrace Virtual Terminal → Account → Security 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 transactions receipt may be sent.stringOptional
phoneCustomer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxCustomer'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 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 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 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
customer_idA unique identifier for each customer in the PayTrace system, value will be same as provided with the request.string

Error with Create Customer Profile

Error response will include a 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 on top of the invalid input parameter will result in an error.

To check any unsuccessful request, please check 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 any invalid Request or input Parameters.   

Error Example

If provided customer id already exists in the database, you will get an error response with a 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) of your customer with this method.

Encrypted values by the 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.
checkCheck 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" is enabled from PayTrace Virtual Terminal → Account → Security 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 transactions receipt may be sent.stringOptional
phoneCustomer's phone number (i.e. 555-555-5555, or 5555555555).stringOptional
faxCustomer'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 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 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 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
customer_idA unique identifier for each customer in the PayTrace system, value will be same as provided with the request.string
masked_card_numberCredit card number with all digits masked and replaced with 'x' except last 4 digits.

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

Error with Update Customer Profile

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.  Test data can be found here.

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

Error Example

If provided customer id already exists in the database, you will get an error response with a 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 a 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 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 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 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
customer_idA unique identifier for each customer in the PayTrace system, value will be same as provided with the request.string

Error with Delete Customer Profile

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.  Test data can be found here.

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

Error Example

If provided customer id doesn't exists in the database to update the profile, you will get an error response with a 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 profile 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 a existing customer profile stored in your Customer Database(Vault) at PayTrace.stringOptional
createdFor supported Schema, Click here Request_Creation_Record Schema.objectOptional
emailCustomer's email addressstringOptional
include_binIf set to true, this will return the first 6 and last 4 digits of the card number.booleanOptional


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 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 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
customersIt is an array of customer profiles.
For Customer Profile supported Schema, Click here Customer_Record Schema.
array

Error with Export Customer Profile

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.  Test data can be found here.

This Method will return an empty customers array in case of no customer records found. You will get an API error response with any invalid Request or input Parameters.             

Error Example

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


Level 3 Data

What is Level 3 data?

Level 3 data is an additional information that may be applied to enrich a transaction’s reporting value to both the merchant 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 brands 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 a 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: It should be a reference of approved and pending settlement transaction with PayTrace system to avoid any API errors.
numberRequired

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_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.numberOptional
national_tax_amountPortion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax.numberOptional
freight_amountFreight value should represent the portion of the transaction amount that was generated from shipping costs.numberOptional
duty_amountPortion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax.numberOptional
source_addressOnly zip is a required attributes.
For supported schema, Click here shipping_address Schema.
objectOptional
shipping_addressOnly zip 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_includedA boolean flag used to indicate if additional tax was included in this transaction. Set to
true - if additional tax was included
false - if no additional tax was applied.
numberOptional
line_itemsLine items is a collection of the product detail.
It is an array containing zero or more Line Items objects.
For supported schema, check out MasterCard_Line_Items Schema on the same page.
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 additional tax was included in this transaction. Possible values are:
true - if additional tax was included.
false - if no additional tax was applied.
booleanOptional
additional_tax_rateRate at which additional tax was assessed.numberOptional
amountDollar 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 to the customer. Generally always a debit or a factor that increased the transaction amount.
Possible values are D (net is a debit) and C (net is a credit).
stringOptional
descriptionOptional text describing the transaction, products, customers, or other attributes of the transaction.

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

Note: When discount_amount and discount_included is true, this parameter is required for successful request.
numberOptional
discount_includedA boolean flag used to indicate whether discount was applied to the transaction amount in reference to this specific line item record.booleanOptional
merchant_tax_idMerchant’s tax identifier used for tax reporting purposes.stringOptional
product_idYour unique identifier for the product.stringOptional
quantityItem count of the product in this order.numberOptional
tax_includedA boolean flag used to indicate whether a line item amount includes tax or not.booleanOptional
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 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 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 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 MasterCard Level 3 data

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

To check any unsuccessful add level 3 data request, please check 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 a HTTP status code - 400 Bad Request.


Add Level 3 Data with Visa

This Method can be used to add Level 3 data to any 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 of approved and pending settlement transaction with PayTrace system to avoid any API errors.
numberRequired

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_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.numberOptional
national_tax_amountPortion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax.numberOptional
merchant_tax_idMerchant’s tax identifier used for tax reporting purposes.stringOptional
customer_tax_idCustomer’s tax identifier used for tax reporting purposes.stringOptional
commodity_codeCommodity code that generally applies to each product included in the order. Commodity codes are generally assigned by your merchant service provider.stringOptional
discount_amountDiscount value should represent the amount discounted from the original transaction amount.numberOptional
freight_amountFreight value should represent the portion of the transaction amount that was generated from shipping costs.numberOptional
duty_amountPortion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax.numberOptional
source_addressOnly zip is a required attributes.
For supported schema, click here shipping_address Schema.
objectOptional
shipping_addressOnly zip 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_rateRate at which additional tax was assessed.numberOptional
line_itemsLine items is a collection of the product detail.
It is an array containing zero or more Line Items objects.
For supported schema, click here Visa_Line_Items Schema on the same page.
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_rateRate at which additional tax was assessed.numberOptional
amountDollar amount of the transaction. Must be a positive number up to two decimal places.numberOptional
commodity_codeCommodity code that 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: 35 characters max limit.
stringOptional
discount_amountDiscount 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: It should be a reference of approved and pending settlement transaction with 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 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 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 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 Visa Level 3 data

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 add level 3 data request, please check 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 a HTTP status code - 400 Bad Request.


Settle Transactions

This method can be used to initiate transactions settlement to your merchant service provider.

This request only works for terminal based payment processing networks.

Request URL

Post
/v1/transactions/settle

Request Attributes : None

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 settlement 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
transaction_count Total number of transactions included in the batch for this settlement request. number
net_amount This value is the net amount (sales minus refunds) of the initiated settlement batch. number
batch Batch schema that provides detail about the initiated batch for settlement.
Note : Only number Attribute will be returned.
For supported Schema, Click here Batch_Record Schema
object

Error with settlement

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 settlement request, please check 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 a 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, latest batch details will be returned.

By exporting a 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 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 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 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 values.number
status_messageStatus message about the request and provides additional information about the request execution end result.string
batchThis object contains details about the batch.
Note : For supported Schema, Click here Batch_Record Schema.
object

Error with Export Batch

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 export batch request, please check success and response_code parameter values.  Check out API Response Codes for possible values.

This method will always return successtrue.  All batch record values will be 0 or empty string except batch_number if batch_number doesn't exist.

Error Example

If batch_number 1 doesn't exist, you will get a response with a 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 batch summary details, your application will be able to determine the deposit and refunds.

Request URL

Post
 /v1/batches/export

Required Attributes
AttributeDescriptionTypeAttribute Requirement
start_dateStart date is used to indicate when to start searching for transactions or batches to export.
Must be a valid date formatted as MM/DD/YYYY.
stringRequired
end_dateEnd date is used to indicate when to end searching for transactions or batches to export.
Must be a valid date formatted as MM/DD/YYYY.
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 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 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 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
batchesIt 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful export batch request, please check 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 any invalid Request or input Parameters.          

Error Example

If no batch exists within a requested date range, you will get an error response with a 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 transactions 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 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.

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
transactionsIt 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful export batch 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.     

Error Example

If batch doesn't exist or no transaction exists, you will get an error response with a HTTP status code - 400 Bad Request.  Test data can be found here.

Export Transaction By Transaction Id

This method can be used to export a 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 be a reference of legitimate transaction with PayTrace system in a past 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 a 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, 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 object.

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
transactionsIt is an array of 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

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

Error Example

If provided transaction id does not exist,  you will get an error response with a 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 transactions 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_dateStart date is used to indicate when to start searching for transactions to export.
Must be a valid date formatted as MM/DD/YYYY.
stringRequired
end_dateEnd date is used to indicate when to end searching for transactions to export.
Must be a valid date formatted as MM/DD/YYYY.
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_idA unique identifier for each transaction in the PayTrace system.
Note:It should be a reference of legitimate transaction with PayTrace system in a past to avoid any API errors.
stringRequired
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 a 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, 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 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
transactionsIt 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

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

This Method will return an empty transactions array in case of no transaction record found.  You will get an API error response with any invalid Request or input Parameters. 

Error Example

If no transactions exists within a request date range, you will get a response with a HTTP status code - 200 OK.  Any invalid date will trigger an error response with 400 Bad Request.  Test data can be found here.


Recurring Payment

PayTrace API allows you to create and manage recurring payments with your existing customers stored at PayTrace customer database(Vault). Recurring 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) at PayTrace.

Request URL

Post
/v1/recurrence/create

Request Attributes

Required Attributes
Attribute Description Type Attribute Requirement
customer_id A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.

Note: This id should be an existing customer id at PayTrace Vault to avoid API errors.
string Required
recurrence Recurrence Payment detail. For supported Schema, Click here Recurrence_Record Schema. object Required
Optional Attributes
Attribute Description Type Attributes Requirements
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string Optional

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 transaction is created.  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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
recurrence For supported Schema, Click here Recurrence_Record Schema.
Note: Only id will be returned on successful creation of 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 any unsuccessful transactions, please check 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 any invalid Request or input Parameters.

Error Example

If customer_id - customerid123 does not exist in PayTrace vault, you will get an error response with a HTTP status code - 400 Bad request.


Update Recurring Payment

This Method allows you to modify existing recurring payment with recurring payment id.

Request URL

Post
/v1/recurrence/update

Request Attributes

Required Attributes
Attribute Description Type Attribute Requirement
recurrence Recurrence Payment detail. Only Id is required and remaining attributes are optional.
For supported Schema, Click here Recurrence_Record Schema.
object Required
Optional Attributes
Attribute Description Type Attributes Requirements
customer_id A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.
Note: This id should be an existing customer id at PayTrace Vault to avoid API errors.
string Optional

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 payment transaction is updated.  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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
recurrence For supported Schema, Click here Recurrence_Record Schema.
Note: Only id will be returned on successful update request of 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 any unsuccessful transactions, please check 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 any invalid Request or input Parameters.

Error Example

If recurrence id or customer_id does not exist in PayTrace vault, you will get an error response with a HTTP status code - 400 Bad request.


Delete Recurring Payment

This Method allows you to delete existing recurring payment with recurring payment id permanently.

Request URL

Post
/v1/recurrence/delete

Request Attributes

Required Attributes
Attribute Description Type Attribute Requirement
recurrence Recurrence Payment detail. Only Id is required.
For supported Schema, Click here Recurrence_Record Schema.
object 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 payment transaction is deleted.  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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
recurrence For supported Schema, Click here Recurrence_Record Schema.
Note: Only id will be returned on successful delete request of 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 any unsuccessful transactions, please check 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 any invalid Request or input Parameters with a 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
Attribute Description Type Attribute Requirement
recurrence Recurrence Payment detail. Only Id is required.
For supported Schema, Click here Recurrence_Record Schema.
object Required to find a specific recurring payment transaction
customer_id A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.

Note: This id should be an existing customer id at PayTrace Vault to avoid API errors.
string Required to find all recurring payments transaction for specific customer.

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 payment an export 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
recurrences An array of Recurrence Record objects.
For supported Schema, Click here Export_Recurrence_Record Schema.
Note:
If Request parameter is a recurrence id, you will get an array of single recurrence transaction record.
If 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 a HTTP status code and JSON body with error information.  Check out API Errors for more information.

To check any unsuccessful export request, please check 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 any invalid Request or input Parameters with a HTTP status code.

Error Example

If customer id or recurrance id does not exist in the PayTrace vault, you will get an error response with a HTTP status code - 400 Bad request.


Export A Single Recurring Payment

This Method can be used to export a most recent approved recurring payment transaction based on the specified customer profile.

Request URL

Post
/v1/recurrence/export_approved

Request Attributes

Required Attributes
Attribute Description Type Attribute Requirement
customer_id A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace.

Note: This id should be an existing customer id at PayTrace Vault to avoid API errors.
string 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 an export 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
created Transaction creation details.Only 'at' attribut will be used.
For supported Schema, Click here Response_Creation_Record Schema.
object
recurrence Recurrence Payment detail. Only Id will be returned on a successful request.
For supported Schema, Click here Recurrence_Record Schema.
object
approval_code This code is generated by the credit card issuer and returned with a successful transaction. string
amount Dollar amount of the transaction. Must be a positive number up to two decimal places. number
next_date The next date when recurring transaction is scheduled to occur. Format will be : MM/DD/YYYY. string
discretionary_data Recurrence payment discretionary data.
For supported Schema, check out Recurrence_Discretionary_Data Schema on the same page.
object
description Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. string
Recurrence_Discretionary_Data Schema
Attribute Description Type
TOTALCOUNT The total number of times the recurring transaction should be processed.
It will be 999 if the recurring transaction should be processed indefinitely.
string
CURRENTCOUNT The number of times this payment has been processed in context to total number of scheduled payment.
The payment will be completed when current count is equal to total count unless total count is set to 999(infinite).
string

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 any unsuccessful export requests, please check 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 any invalid Request or input Parameters with a HTTP status code.

Error Example

If customer id does not does not have any recurring transactions, you will get an error response with a HTTP status code - 400 Bad request.


Update Password

This method can be used to update a WebUser or a APIUser 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 PayTrace user, Check out this page PayTrace User Profiles.

Request URL

Post
/v1/password/change

Request Attributes

Required Attributes
Attribute Description Type Attribute Requirement
new_password A new password to be updated. string 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 password is updated.  You will need to verify the success and the response_code parameters.  Check out API Response Codes for possible values.

After successful password update request, User will be logged out immediately and required to use new password.

Response Attributes

Toggle the Attributes details
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message 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, error response will be returned.

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.

Error Example

If new password is similar to the last 5 passwords, you will get an error response with a 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 with your account, you will need to contact your Merchant Service Provider. They will be able to enable check processing for you with PayTrace.


Sale by account

Check or ACH (Automated Clearing House) Sale transactions can be performed with this method by providing 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)
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
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 Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transactions 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
discretionary_dataDiscretionary data details. For supported schema, Click here Discretionary_Data SchemaobjectOptionalobjectOptional

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 check 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 ach_code and ach_message parameters if check is processed by 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 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
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 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 a HTTP status code and JSON body with error information. Check out API Errors for more information.

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

Additional error information can be retrieved from response parameters ach_code and ach_message.  Test data can be found here.

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

Declined Transaction Example

With a declined check transactions, appropriate Response code will be returned in the error response.

You can get a declined transaction response only 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 a 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) at PayTrace.

Request URL

Post
 /v1/checks/sale/by_customer

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
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 with ACH details at PayTrace Vault to avoid API errors.
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 Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transactions 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
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.

A HTTP status code in the 2XX range does not indicate that a check transaction is processed. 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 ach_code and ach_message parameters if check is processed by 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 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
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 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 a HTTP status code and JSON body with error information. Check out API Errors for more information.

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

Additional error information can be retrieved from response parameters ach_code and ach_message.  Test data can be found here.

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

Declined Transaction Example

With a declined check transactions, 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 a 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
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 Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transactions 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
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.

A HTTP status code in the 2XX range does not indicate that a check 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 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
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 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 Hold

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 check transaction, please check success and response_code parameter values. Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters ach_code and ach_message.  Test data can be found here.

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

Declined Transaction Example

With a declined check transactions, appropriate Response code will be returned in the error response.

You can get a declined transaction response only when a check hold 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 a HTTP status code - 400 Bad request.  Test data can be found here.

Vault Hold

This Method allows you to process a check hold transaction with an existing Customer ID (Token) from your Customer Database(Vault) at PayTrace.  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_customer

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
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 at PayTrace Vault to avoid API errors.
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 Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transactions 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
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.

A HTTP status code in the 2XX range does not indicate that a check transaction is processed.  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 ach_code and ach_message parameters if 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 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
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 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 Hold

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 transaction, please check success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters ach_code and ach_message.  Test data can be found here.

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

Declined Transaction Example

With a declined check transactions, 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 a HTTP status code - 400 Bad request.  Test data can be found here.

Refund by account

This method can be used to issue a refund check by providing customer's checking account details.

Check processor Paya doesn't support check refund transactions.    

Request URL

Post
 /v1/checks/refund/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
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 Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transactions 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
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.

A HTTP status code in the 2XX range does not indicate that a check 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 ach_code and ach_message parameters if check is processed by 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 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
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 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 Refund

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 check transaction, please check success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters ach_code and ach_message. Test data can be found here.

Vault Refund

This method can be used to issue a refund check to a customer with an existing Customer ID (Token) from your Customer Database(Vault) at PayTrace.

Check processor Paya doesn't support check refund transactions.     

Request URL

Post
 /v1/checks/refund/by_customer

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
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 at PayTrace Vault to avoid API errors.
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 Attributes
AttributeDescriptionTypeAttributes Requirements
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transaction 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
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.

A HTTP status code in the 2XX range does not indicate that a check transaction is processed.  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 ach_code and ach_message parameters if 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 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
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 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 Refund

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 transaction, please check success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters ach_code and ach_message.  Test data can be found here.

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

Refund Transaction

This method can be used to issue a refund of settled check transaction. If amount is submitted, specific amount will be refunded to the check account used in the referred transaction.

Check processor Paya doesn't support check refund transactions.     

Request URL

Post
 /v1/checks/refund/by_transaction

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
check_transaction_idA unique identifier for each check transaction in the PayTrace system.

Note: It should be a settled check transaction id to avoid any API errors.
numberNo 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 from 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 PayTrace Virtual Terminal → Account → Security Settings page.

Required if configured

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

Note: If amount is not provided, transaction will be refunded with the original amount.
numberOptional
shipping_addressFor supported schema, click here shipping_address.objectOptional
emailCustomer's email address where the transaction 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
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.

A HTTP status code in the 2XX range does not indicate that a check 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 ach_code and ach_message parameters if check is processed by 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 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
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 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 Refund

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 check transaction, please check success and response_code parameter values.  Check out API Response Codes for possible values.

Additional error information can be retrieved from response parameters ach_code and ach_message.  Test data can be found here.

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

Fund Check

This method can be used to change the status of any hold(authorized) transactions into fund, to be settled. Unsettled and pre authorized check transaction id should be provided for a successful fund request.

Check processor Paya doesn't support check fund transactions.

Amount can be revised with the fund request if check is not processed by a real time processor.      

Request URL

Post
 /v1/checks/manage/fund

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
check_transaction_idA unique identifier for each check transaction in the PayTrace system.

Note: It should be an unsettled check transaction id to avoid any API errors.
numberNo configuration settings applied.

Required

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

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 check 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 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
check_transaction_idA unique identifier for each check transaction in the PayTrace system.number

Error with ACH Fund

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 check transaction, please check 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 any invalid Request or input Parameters.       

Void Check

This method can be used to change the status of any hold(pre authorized) transactions into void. Unsettled and pre authorized check transaction id should be provided for a successful void request.

Check processor Paya doesn't support check void transactions.

Amount can be revised with the void request if check is not processed by a real time processor.   

Request URL

Post
 /v1/checks/manage/void

Request Attributes


Required Attributes
AttributeDescriptionTypeConfiguration
(Must provide if configured, results in an error when missing)
check_transaction_idA unique identifier for each check transaction in the PayTrace system.

Note: It should be an unsettled check transaction id to avoid any API errors.
numberNo configuration settings applied.

Required

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

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 check transaction is processed. 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
check_transaction_idA unique identifier for each check transaction in the PayTrace system.number

Error with ACH Void

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 check transaction, please check 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 any invalid Request or input Parameters.    

Email Receipt

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

Request URL

Post
/v1/checks/email_receipt

Request Attributes


Required Attributes
Attribute Description Type Attribute Requirement
email An Email address where the receipt will be sent to. string Required
check_transaction_id A unique identifier for each check transaction in the PayTrace system.

Note: It should be a legitimate transaction with PayTrace system to avoid any API errors.
number 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 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
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status 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 requests, 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 check transaction id or Invalid email address is submitted, error response will be returned with a HTTP status code - 400 Bad request. Test data can be found here.


Export Check Transaction

This method can be used to export a specific check transaction details.

Request URL

Post
 /v1/checks/export/by_id

Required Attributes
Attribute Description Type Attribute Requirement
check_transaction_id A unique identifier for each check transaction in the PayTrace system.
Note: It should be a reference of legitimate transaction with PayTrace system in a past to avoid any API errors.
number Required

Optional Attributes
Attribute Description Type Attributes Requirements
check_type The check transaction type to find transactions.
Possible values : SALE, HOLD, REFUND,
VOID, SETTLED, PENDING.
string Optional
created For supported Schema, Click here Request_Creation_Record Schema. object Optional
customer_id A unique identifier for a existing customer profile stored in your Customer Database(Vault) at PayTrace. string Optional
including_text The text submitted will be used to locate transactions containing this text, to narrow down the export results. string Optional

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 check_trasancation detail object.

Response Attributes


Toggle the Attributes details
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
check_transactions It is an array of check transaction detail record object.
Note : For supported Schema, Click here Check_Transaction_Detail_Record Schema
array of objects

Error with Export Check Transaction

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 export transaction request, please check success and response_code parameter values.  Check out API Response Codes for possible values.

This Method will return an empty check_transactions array in case of no transaction record found.
You will get an API error response with any invalid Request or input Parameters.        

Error Example

If provided check transaction id does not exist, you will get an error response with a HTTP status code - 400 Bad Request. Test data can be found here.


Export Check Transactions with Date Range

This method can be used to export a set of check transaction details with a provided date range. You can optimize your search by providing optional parameters.

Request URL

Post
 /v1/checks/export/by_date_range

Required Attributes
Attribute Description Type Attribute Requirement
start_date Start date is used to indicate when to start searching for transactions to export.
Must be a valid date formatted as MM/DD/YYYY.
string Required
end_date End date is used to indicate when to end searching for transactions to export.
Must be a valid date formatted as MM/DD/YYYY.
string Required

Optional Attributes
Attribute Description Type Attributes Requirements
check_transaction_id A unique identifier for each check transaction in the PayTrace system.
Note: It should be a reference of legitimate transaction with PayTrace system in a past to avoid any API errors.
number optional
check_type The check transaction type to find transactions.
Possible values : SALE, HOLD, REFUND,
VOID, SETTLED, PENDING.
string Optional
created For supported Schema, Click here Request_Creation_Record Schema. object Optional
customer_id A unique identifier for a existing customer profile stored in your Customer Database(Vault) at PayTrace. string Optional
including_text The text submitted will be used to locate transactions containing this text, to narrow down the export results. string Optional

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 check_trasancations detail object.

Response Attributes


Toggle the Attributes details
Attribute Description Type
success This 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_code This code will show you the response code based on the request execution status. Check out API Response Codes for the possible values number
status_message Status message about the request and provides additional information about the request execution end result. string
check_transactions It is an array of request check transaction detail.
Note : For supported Schema, Click here Check_Transaction_Detail_Record Schema
array of objects

Error with Export Check Transaction

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 export transaction request, please check success and response_code parameter values.  Check out API Response Codes for possible values.

This Method will return an empty check_transactions array in case of no transaction record found.
You will get an API error response with any invalid Request or input Parameters.   

Error Example

If no transaction exists within a request date range, you will get a response with a HTTP status code - 200 OK.   Any invalid date will trigger an error response with 400 Bad Request. Test data can be found here.