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 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.
All API requests are made to https://api.paytrace.com and all requests are served over HTTPS using TLS 1.2.
The current version of JSON API is v1.
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. |
| 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. |
| 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.
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.
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.
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.
Please refer the code section Sample →
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 →
(Please provide the appropriate URL of 'YourPublicKeyFile.pem' if it is on different server.)
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 →
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.
<head> <!-- This is the PayTrace End-to-End Encryption library: --> <script src="https://api.paytrace.com/assets/e2ee/paytrace-e2ee.js"></script> </head>
<body> <input type="text" class="form-control pt-encrypt" id="ccNumber" name="ccNumber" placeholder="Credit card number"> <input type="text" class="form-control pt-encrypt" id="ccCSC" name="ccCSC" placeholder="Card security code"> </body>
<script> // This binds the form's submit event $(document).ready(function() { // do this first, or wrap in a try/catch to ensure the form is never un-hooked paytrace.hookFormSubmit('#myform'); // set the key from an AJAX call (in this case via a relative URL) paytrace.setKeyAjax('/YourPublicKeyfile.pem'); }); </script>
OR
<script> // set the key from an AJAX call $(document).ready(function() { paytrace.setKeyAjax('/YourPublicKeyfile.pem') ;// set the key from an AJAX call (in this case via a relative URL) }); $('#myform').submit(function(e) { e.preventDefault(); //To prevent the default action of the submit if ($(this).valid()) { //submit the valid form paytrace.submitEncrypted(this); } else { console.log("INVALID FORM. your code for further action here"); } return false; }); </script>
{
"amount":2.00,
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"12",
"expiration_year":"2020"
},
"encrypted_csc":"Xd46EqA9ohOD+YVjfSVZAK4/EuQ3RAcqmnfv5h0Tjhew84MARl6yhNdGHW6i+fYJnOQEuDOc3O5RfQqOe6BI8ZboNsmZ82wjPYHe8EiykMdVqNdHVg4xjQBdkexbgA9WLU5Boyc1TmbtJGVpnwDnrR90n0JQpUE/72MSq7evlFXRAIGFcdMyq+QpbLaGi4mI3Fio5L+yn5O0COj8aMD2NalyGFAQmw90dw/4he475o+sGd+2ueEsBHTrDSspfGIACl79lbkSLYa3BRfTkvHAccNRkiY65WftgRW4SGVhs29AD78gNu1kEk/HcrE1PGW1RVC/e2dPT0okKFm4v+cW/w==",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}
*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":1001,
"status_message":"Decryption failed."
}
Here is the list of all the Request and Response parameters being used by JSON API.
| 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 |
| integrator_id | A 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. | string | 12 |
| invoice_id* | A unique identifier for this transaction in your accounting or inventory management system. This attribute is only required if the "Require Invoice" field is enabled 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)
| 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 |
| 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! |
| 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 | - |
Here are the Schemas, used by JSON API
| Attribute | Description | Type | Attribute 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. | string | Required |
| expiration_month | 2-digit expiration month | string | Required |
| expiration_year | 2-digit or 4-digit expiration year | string | Required |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| name | CName that appears on the credit card. | string | Optional Note:Required for ACH payment methods |
| street_address | Street 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. | string | Required if configured |
| street_address2 | Second line of the Street Billing Address that is on file for the cardholder's account. | string | Optional |
| city | City of the Billing Address that is on file for the cardholder's account. | string | Optional |
| state | State of the Billing Address that is on file for the cardholder's account. | string | Optional |
| zip | ZIP 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. | string | Required if configured |
| country | 2-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. | string | Optional |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| name | Name of the person where the product is delivered. | string | Optional |
| street_address | Address where the product is delivered. | string | Optional |
| street_address2 | Second line of the address where the product is delivered. | string | Optional |
| city | City where the product is delivered. | string | Optional |
| state | State where the product is delivered. | string | Optional |
| zip | ZIP code where the product is delivered. | string | Optional |
| country | 2-digit ISO-3166-2 Country Code of where the product is delivered. | string | Optional |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| by | The user name of the PayTrace user who has created the customer you are trying to export. | string | Required |
| Attribute | Description | Type |
|---|---|---|
| through | PayTrace API or Virtual terminal that has originally requested the customer profile or transaction be created or processed. | string |
| at | The 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 |
| by | The PayTrace username who has created the transaction or customer profile you are trying to export. | string |
| from_ip | IP 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 |
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).
| Attribute | Description | Type |
|---|---|---|
| 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 |
| Attribute | Description | Type |
|---|---|---|
| customer_id | A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace. | string |
| credit_card | For supported Schema, Click here Credit_Card Schema. | object |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object |
| shipping_address | For supported schema, Click here shipping_address Schema. | object |
| check | Check account detail. For supported Schema, Click here Check Schema. Note: This object will be included ONLY when customer has a check data. | object |
| Customer's email address where the transactions receipt may be sent. | string | |
| phone | Customer's phone number (i.e. 555-555-5555, or 5555555555). | string |
| fax | Customer's fax number (i.e. 555-555-5555, or 5555555555). | string |
| created | Creation record information for the customer profile. For supported Schema, Click here Response_Creation_Record Schema. | object |
| discretionary_data | Discretionary_data details. For supported Schema, Click here Discretionary_Data Schema. | object |
This schema is associated with Export Transaction methods.
| Attribute | Description | Type |
|---|---|---|
| transaction_id | A unique identifier for each transaction in the PayTrace system. | string |
| credit_card | For supported Schema, Click here Credit_Card Schema. | object |
| transaction_type | The transaction type to find transactions. Possible values : SALE, AUTHORIZATION, REFUND, VOID, CAPTURE, FORCE, SETTLED, PENDING, DECLINED. | string |
| description | Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. | string |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number |
| invoice_id | A unique identifier for this transaction in your accounting or inventory management system. | string |
| shipping_address | For supported schema, click here shipping_address Schema. | object |
| billing_address | For supported Schema, Click here Billing_Address Schema. | object |
| receipt_emailed_to | Customer's email address where the Authorizations receipt may be sent. | string |
| 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 |
| customer_reference_id | Customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. It is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number. | string |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| status_code | A 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_message | A short message that shows current status of the transaction for the settlement. | string |
| created | Transaction creation details. For supported schema, click here Response_Creation_Record Schema. | object |
| settled | The 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_id | A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace. | string |
| discretionary_data | Discretionary_data details. For supported Schema, Click here Discretionary_Data Schema. | object |
| Attribute | Description | Type |
|---|---|---|
| number | This 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_express | American Express Card details. For supported schema, Click here Batch_Cards Schema. | object |
| diners_club | For supported schema, Click here Batch_Cards Schema. | object |
| discover | Discover Card details. For supported schema, Click here Batch_Cards Schema. | object |
| master_card | Master Card details. For supported schema, Click here Batch_Cards Schema. | object |
| private_label | For supported schema, Click here Batch_Cards Schema. | object |
| visa | Visa Card details. For supported schema, Click here Batch_Cards Schema. | object |
| Settled | Settled represents the date when the batch was settled. The date format will be: MM/DD/YYYY | string |
| Attribute | Description | Type |
|---|---|---|
| sales | Total number of sales (count) that were settled in the exported batch with specific card type. | number |
| collected | Total sum of sales amount that were settled in the exported batch with specific card type. | number |
| refunds | Total number of refunds(count) that were settled in the exported batch with specific card type. | number |
| refunded | Total sum of refund amounts that were settled in the exported batch with specific card type. | number |
| Attribute | Description | Type |
|---|---|---|
| number | A sequential number assigned to the settlement batch. | number |
| created | Batch creation details. Note: Only at attribute will be returned with a date. For supported schema, click here Response_Creation_Record Schema. | object |
| 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 |
| sales_count | Total number of sales included in a batch. | number |
| sales_amount | Total amount of sales included in a batch. | number |
| refund_count | Total number of refunds included in a batch. | number |
| refund_amount | Total amount of refunds included in a batch. | number |
| Attribute | Description | Type |
|---|---|---|
| transaction_id | A unique identifier for each transaction in the PayTrace system. | string |
| credit_card | For supported Schema, Click here Credit_Card Schema. | object |
| transaction_type | The transaction type to find transactions. Possible values : SALE, AUTHORIZATION, STR/FWD, REFUND, VOID, CAPTURE, FORCE, SETTLED, PENDING, DECLINED. | string |
| description | Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. | string |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number |
| invoice_id | A unique identifier for this transaction in your accounting or inventory management system. | string |
| shipping_address | For supported schema, Click here shipping_address Schema. | object |
| billing_address | For supported Schema, Click here Billing_Address Schema. | object |
| receipt_emailed_to | Customer's email address where the Authorizations receipt may be sent. | string |
| 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 |
| customer_reference_id | Customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. It is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number. | string |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| status_code | A 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_message | A short message that shows current status of the transaction for the settlement. | string |
| created | Transaction creation details. For supported schema, Click here Response_Creation_Record Schema. | object |
| settled | The 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_id | A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace. | string |
Only id will be a return paramter with Create, Update and Delete Methods for this schema.
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| id | A 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. | number | Required for Update, Delete and Export methods. |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Required for Create Method Optional for Update Method |
| customer_receipt | A 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. | boolean | Required for Create Method Optional for Update Method |
| frequency | The 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. | string | Required for Create Method Optional for Update Method |
| start_date | Date the recurring transaction should be processed for the first time. Format will be : MM/DD/YYYY. | string | Required for Create Method Optional for Update Method |
| total_count | The total number of times the recurring transaction should be processed. Use 999 if the recurring transaction should be processed indefinitely. | string | Required for Create Method Optional for Update Method |
| transaction_type | The type of transaction you wish to process. Possible values: Sale or Authorization. | string | Required for Create Method Optional for Update Method |
| type | The 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. | string | Optional for Create Method Required for Update Method if ACH/Check recurring payment |
| description | Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| Attribute | Description | Type |
|---|---|---|
| id | A 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 |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number |
| customer_id | A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace. | string |
| next_date | The next date when recurring transaction is scheduled to occur. Format will be : MM/DD/YYYY. | string |
| total_count | The total number of times the recurring transaction should be processed. It will be 999 if the recurring transaction should be processed indefinitely. | number |
| current_count | 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). | number |
| repeat_count | The number of the days after a decline the payment should be retried. | number |
| description | Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. | string |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| account_number | Checking account number for processing check transactions or managing customer profiles. | number | Required |
| routing_number | Routing number for processing check transactions or managing customer profiles. | number | Required |
| masked_account_number | Masked checking account number for processing check transactions or managing customer profiles. Note: This parameter will be returned with export check transaction requests instead of plain account number. | string | NA |
| masked_routing_number | Masked 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 | string | NA |
This schema is associated with Export Check Transaction methods.
| Attribute | Description | Type |
|---|---|---|
| check_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| check | Account detail. For supported Schema, Click here Check Schema. Note: Masked parameter will be used for check account details. | object |
| check_type | The check type to find transactions. Possible values : SALE, HOLD, REFUND, VOID, SETTLED, PENDING. | string |
| description | Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. | string |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number |
| invoice_id | A unique identifier for this transaction in your accounting or inventory management system. | string |
| shipping_address | For supported schema, click here shipping_address Schema. | object |
| billing_address | For supported Schema, Click here Billing_Address Schema. | object |
| receipt_emailed_to | Customer's email address where the Authorizations receipt may be sent. | string |
| 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 |
| customer_reference_id | Customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. It is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number. | string |
| status_code | A 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 |
| created | Transaction creation details. For supported schema, click here Response_Creation_Record Schema. | object |
| customer_id | A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace. | string |
| discretionary_data | Discretionary_data details. For supported Schema, Click here Discretionary_Data Schema. | object |
"credit_card":{ "number":"4111111111111111", "expiration_month":"12", "expiration_year":"2020" }
"billing_address":{ "name":"Steve Smith", "street_address":"8320 E. West St.", "street_address2":"", "city":"Spokane", "state":"WA", "zip":"85284" }
"shipping_address":{ "name":"Steve Smith", "street_address":"8320 E. West St.", "street_address2":"", "city":"Spokane", "state":"WA", "country":"USA" "zip":"85284" }
"created":{ "by":"sandbox123" }
"created":{ "through":"API", "at":"7/15/2016 9:56:53 AM", "by":"sandboxUser", "from_ip":"11.11.111.111" }
"discretionary_data":{ "Custom Discretionary Field Name1":"TestValue1", "Custom Discretionary Field Name2":"TestValue12" "Custom Discretionary Field Name3":"TestValue1", "Custom Discretionary Field Name4":"TestValue14", "Custom Discretionary Field Name5":"", "Custom Discretionary Field Name6":"TestValue16", }
{
"customer_id":"customerTest121",
"credit_card":{
"masked_number":"************1111",
"expiration_month":"12",
"expiration_year":"2020"
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284",
"country":"US"
},
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":"",
"country":"US"
},
"check":{
"account_number":123456,
"routing_number":325070760
},
"email":"",
"phone":"",
"fax":"",
"email":"",
"phone":"",
"fax":"",
"created":{
"at":"4/10/2015 12:39:57 AM",
"by":"sandbox123",
"from_ip":"11.111.111.11"
},
"discretionary_data":{
"Custom Discretionary Field Name1":"TestValue1",
"Custom Discretionary Field Name2":"TestValue12"
"Custom Discretionary Field Name3":"TestValue1",
"Custom Discretionary Field Name4":"TestValue14",
"Custom Discretionary Field Name5":"",
"Custom Discretionary Field Name6":"TestValue16",
}
}{ "transaction_id":"105968570", "credit_card":{ "masked_number":"************1111", "expiration_month":"12", "expiration_year":"2020" }, "transaction_type":"SALE", "description":"", "amount":20, "invoice_id":"1234567", "shipping_address":{ "name":"", "street_address":"", "street_address2":"", "city":"", "state":"", "county":"", "zip":"", "country":"" }, "billing_address":{ "name":"Steve Smith", "street_address":"8320 E. West St.", "street_address2":"", "city":"Spokane", "state":"WA", "zip":"85284", "country":"US" }, "receipt_emailed_to":"", "tax_amount":"8.10", "customer_reference_id":"PO123456", "approval_code":"VTLMC1", "approval_message":"EXACT MATCH - Approved and completed", "avs_response":"Full Exact Match", "csc_response":"Match", "status_code":"GB571", "status_message":"GB571", "created":{ "through":"API", "at":"4/10/2016 4:06:53 AM", "by":"sandbox123", "from_ip":"44.111.99.99" }, "settled":"4/10/2016 08:31:11 PM", "customer_id":"customer456" "discretionary_data":{ "Custom Discretionary Field Name1":"TestValue1", "Custom Discretionary Field Name2":"TestValue12" "Custom Discretionary Field Name3":"TestValue1", "Custom Discretionary Field Name4":"TestValue14", "Custom Discretionary Field Name5":"", "Custom Discretionary Field Name6":"TestValue16", } }
"batch":{ "number":"570", "visa":{ "sales":2, "collected":45, "refunds":0, "refunded":0 }, "master_card":{ "sales":2, "collected":32, "refunds":1, "refunded":5.70 }, "diners_club":{ "sales":0, "collected":0, "refunds":0, "refunded":0 }, "american_express":{ "sales":0, "collected":0, "refunds":0, "refunded":0 }, "discover":{ "sales":0, "collected":0, "refunds":0, "refunded":0 }, "private_label":{ "sales":0, "collected":0, "refunds":0, "refunded":0 } }
"CardType":{ "sales":2, "collected":45, "refunds":0, "refunded":0 }
{ "number":49, "created":{ "at":"7/14/2016" }, "transaction_count":4, "net_amount":77, "sale_count":4, "sales_amount":77, "refund_count":0, "refund_amount":0 }
{ "transaction_id":"105968570", "credit_card":{ "masked_number":"************1111", "expiration_month":"12", "expiration_year":"2020" }, "transaction_type":"SALE", "description":"", "amount":20, "invoice_id":"1234567", "shipping_address":{ "name":"", "street_address":"", "street_address2":"", "city":"", "state":"", "county":"", "zip":"" }, "billing_address":{ "name":"Steve Smith", "street_address":"8320 E. West St.", "street_address2":"", "city":"Spokane", "state":"WA", "zip":"85284" }, "receipt_emailed_to":"", "tax_amount":"4.99", "customer_reference_id":"1234abcd", "approval_code":"TAS370", "approval_message":"EXACT MATCH - Approved and completed", "avs_response":"Full Exact Match", "csc_response":"Match", "status_code":"GB49", "status_message":"GB49", "created":{ "through":"API", "at":"7/15/2016 9:56:53 AM", "by":"sandboxUser", "from_ip":"11.11.111.111" }, "settled":"7/15/2016 08:31:11 PM", "customer_id":"customer456" }
"recurrence":{ "id":"647914", "amount":4.00, "customer_receipt":true, "frequency":"3", "start_date":"08/03/2016", "total_count":"12", "transaction_type":"sale", "description":"Testing transaction for recurrence." }
{ "id":"708751", "amount":10, "customer_id":"customerId123", "next_date":"08/15/2016", "total_count":10, "current_count":10, "repeat_count":0, "description":"Recurring payment demo." }
"check":{ "account_number":123456, "routing_number":325070760 }
{ "check_transaction_id":9981619, "check":{ "masked_account_number":"************3456", "masked_routing_number":"************0760" }, "check_type":"SALE", "description":"", "amount":10, "invoice_id":"1234567", "shipping_address":{ "name":"", "street_address":"", "street_address2":"", "city":"", "state":"", "county":"", "zip":"", "country":"" }, "billing_address":{ "name":"Steve Smith", "street_address":"8320 E. West St.", "street_address2":"", "city":"Spokane", "state":"WA", "zip":"85284", "country":"US" }, "receipt_emailed_to":"", "tax_amount":1.10, "customer_reference_id":"PO123456", "created":{ "through":"API", "at":"1/10/2017 4:06:53 PM", "by":"sandbox123", "from_ip":"x.x.x.x" }, "customer_id":"customer456" "discretionary_data":{ "Custom Discretionary Field Name1":"TestValue1", "Custom Discretionary Field Name2":"TestValue12" "Custom Discretionary Field Name3":"TestValue1", "Custom Discretionary Field Name4":"TestValue14", "Custom Discretionary Field Name5":"", "Custom Discretionary Field Name6":"TestValue16", } }
Following sample codes are available on github.
| Language | Sample Link |
|---|---|
| C#.Net | https://github.com/PayTrace/api-demo/tree/master/dot_net |
| Php | https://github.com/PayTrace/api-demo/tree/master/php |
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 :
Post |  /oauth/token |
| Header | Value |
|---|---|
| Accept | */* |
| HTTP Protocol | HTTP/1.1 |
| Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| username | PayTrace API Username | string | Required |
| password | Password for PayTrace API | string | Required |
| grant_type | The grant type for this flow is password | string | Required |
A successful request returns a HTTP status code in the 2XX range with a JSON body.
| Attribute | Description | Type |
|---|---|---|
| access_token | The 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_type | The type of the token issued. | string |
| expires_in | The lifetime in seconds of the access token. | number |
| created_at | Token creation time in Epoch time format. | number |
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.
| Attribute | Description | Type |
|---|---|---|
| error | A unique identifier for error. Please refer Authentication Errors Summary to find out all values. | string |
| error_description | Error message providing details about the error. Please refer Authentication Errors Summary to find out all values. | string |
| errors | error_description |
|---|---|
| invalid_grant | The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
| invalid_token | Depending upon the token value, appropriate error message will be returned. -The access token was revoked -The access token expired. -The access token is invalid. |
| unsupported_grant_type | The authorization grant type is not supported by the authorization server. |
| invalid_resource_owner | The provided resource owner credentials are not valid, or resource owner cannot be found. |
| invalid_request | The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed. |
| invalid_client | Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method. |
| access_denied | The resource owner or authorization server denied the request. |
| invalid_scope | The requested scope is invalid, unknown, or malformed.' |
| server_error | The authorization server encountered an unexpected condition which prevented it from fulfilling the request. |
| temporarily_unavailable | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
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.
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.
Authentication format is: Bearer access_token
grant_type=password&username=YourUserName&password=YourPassword
Following response will be returned with HTTP Status code 200 OK
{
"access_token":"4656d6f6132333:4656d6f6132333:2b607b9a44720c9c3ca867653c7e6ef8b3f3802709c17f2a54402820d155f214",
"token_type":"bearer",
"expires_in":7200,
"created_at":1489710779
}Following error Response will be returned when sending incorrect user credentials with HTTP status code 401-Unauthorized.
{
"error":"invalid_grant",
"error_description":"The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}Authorization:Bearer 4656d6f6132333:4656d6f6132333:2b607b9a44720c9c3ca867653c7e6ef8b3f3802709c17f2a54402820d155f214
| 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 |
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.
| 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. |
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.
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.
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.
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.
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.
Here is a list of HTTP status code with PayTrace API.
| 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. |
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.
Following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968531,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"Match",
"external_transaction_id":""
}{
"errors":{
"errorCodeValue1":["Error Message 1"],
"errorCodeValue2":["Error Message 2"],
....
"errorCodeValueN":["Error Message N"],
}
}There can be N numbers of errorCodeValues.
{
"amount":2.00,
"credit_card":{
"number":"54545454545454",
"expiration_month":"14",
"expiration_year":"2020"
},
"csc":"999",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}Above Keyed sale request sample has invalid values for credit_card.number and credit_card.expiration_month.
Following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"35":[
"Please provide a valid Credit Card Number."
],
"43":[
"Please provide a valid Expiration Month."
]
},
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxx5454"
}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.
| Error Code | Error Message | Reason |
|---|---|---|
| 30 | Customer ID, xxxxx, was not found or is incomplete. | A customer ID is required when processing a request that references a stored customer. |
| 35 | Please provide a valid Credit Card Number. | All card numbers sent to PayTrace must pass the Mod 10 check. |
| 36 | Customer ID, xxxxxx, does not have a valid billing address. | If your account requires a billing address to process a transaction, PayTrace will check the referenced customer's profile. |
| 37 | Customer ID, xxxxxx, does not have a valid billing ZIP. | If your account requires a billing ZIP to process a transaction, PayTrace will check the referenced customer's profile. |
| 39 | Your PayTrace account is not set up to accept this card type. | All card types are 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. |
| 40 | An error occurred during the decryption process. | PayTrace supports encrypted card readers. This error is returned if an error occurs during the decryption process. |
| 43 | Please provide a valid Expiration Month. | All transactions and customer profiles must have a 2 digit expiration month. |
| 44 | Please provide a valid Expiration Year. | All transactions and customer profiles must have a 2 digit expiration year. |
| 45 | Please provide a valid Checking Account Number. | Required if creating a customer with out a card number or processing a check transaction. |
| 46 | Please provide a valid Transit Routing Number. | Required if creating a customer with out a card number or processing a check transaction. |
| 47 | Please provide an Amount that is less than your Sale Ceiling Amount. | All sales, authorizations, and forced sales must have a valid numeric amount that is less than your sale ceiling amount. |
| 48 | Please provide an Amount that is less than your Refund Ceiling Amount. | All refunds must have a valid numeric amount that is less than your refund ceiling amount. |
| 51 | Please provide a valid Amount. | All transactions must have a valid numeric amount. |
| 54 | Cash 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. |
| 55 | Cash Advances may only be processed through accounts set up in the TSYS/Vital network. | Cash Advances may only be processed if your merchant account is set up on the TSYS network. Only applies if ProcessTranx request includes CASHADVANCE~Y| parameter. |
| 56 | Cash Advances may not be processed to stored customers. | Cash advance transactions must be processed as face to face transactions. |
| 57 | Your PayTrace account is not set up to process Cash Advances. | In order to process Cash Advances, your PayTrace account must be configured to accept this type of payment. |
| 58 | Please provide a valid Transaction ID. | Void, capture, add level 3 data, and email receipt requests require a transaction ID that references a transaction in PayTrace's system. |
| 59 | Please provide a valid Check ID. | Manage Check and email receipt requests require a check ID that references a check in PayTrace's system. |
| 61 | The Customer ID that you provided was not found in the PayTrace records. | If a transaction is to be referenced to a stored customer profile, a valid customer ID must be provided. |
| 62 | Please provide a valid Photo ID. | Cash Advance requests require a photo ID to be provided. |
| 63 | Please provide a valid ID Expiration. | Cash Advance requests require an ID expiration date to be provided. |
| 64 | Please provide a valid Last 4 of Card. | Cash Advance requests require the last 4 digits of the card number to be provided. |
| 65 | Cash Advances may only be processed on Visa, MasterCard, and Discover cards. | Cash Advance transactions are only permitted on Visa, MasterCard, and Discover cards. |
| 80 | The Check ID that you provided was not found in the PayTrace records. It may already be voided or settled. | Only pending and held checks may be managed. |
| 81 | The Transaction ID that you provided was not found in the PayTrace records. It may be a voided a transaction or an unsettled transaction. | Only settled transactions sales may be refunded with a transaction ID. |
| 82 | Please provide a valid Batch Number. | If a batch number is present in an ExportBatch request, it must be a numeric value between 1 and 999 |
| 83 | This is not an approved transaction so it can not be captured. | Only approved authorizations may be captured. |
| 84 | This transactions approval code has expired as it was obtained more than 20 days ago. | Transactions must be captured with in 20 days of authorization. |
| 85 | The Transaction ID that you provided was not found in the PayTrace records. It may already be captured or settled. | Only approved authorizations that are currently not pending settlement may be captured. |
| 86 | The Transaction ID that you provided was not found in the PayTrace records. It may already be voided, settled, or an uncaptured authorization. | Only approved sales, authorizations, and refunds that have not been settlement may be voided. So, a declined sale, or a settled sale or refund may not be voided. |
| 87 | The Transaction ID that you provided was not found in the PayTrace records, and the receipt could not be emailed. | Only receipts with valid transaction IDs may be emailed. |
| 88 | The Transaction ID that you provided was not found in the PayTrace records, and level 3 data could not be added to the Visa transaction. | Only Visa sales that are currently pending settlement may have level 3 data added to them. |
| 89 | The Transaction ID that you provided was not found in the PayTrace records, and level 3 data could not be added to the MasterCard transaction. | Only MasterCard sales that are currently pending settlement may have level 3 data added to them. |
| 90 | The Transaction ID that you provided was not found in the PayTrace records, and the amount was not updated. | Only merchants using TSYS/Vital may update transaction amounts on non-Cash Advance transactions. Sales must be approved and pending settlement, refunds must be pending settlement, authorizations must be approved and unsettled, and forced sales must be pending settlement in order for their amounts to be updated to an amount less than or equal to the original transaction amount. |
| 110 | Please provide a valid value for Discretionary Title | Discretionary Data values must match the criteria that'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. |
| 114 | Please provide a valid Store & Forward Date. | Store & Forward transactions may be submitted with optional scheduled processing dates. |
| 115 | Please provide a valid Approval Code. | Forced sales must be processed with valid approval codes. |
| 116 | Please provide a valid Transaction Type. | Only valid transaction types are accepted, and all requests to ProcessTranx require a transaction type. |
| 117 | Please provide a valid Billing Name. | Optional field for transactions and customers must have correct format. |
| 118 | Please provide a valid Billing Address. | Optional field for transactions and customers must have correct format. May be required if configured in your security settings. |
| 119 | Please provide a valid Billing Address 2. | Optional field for transactions and customers must have correct format. |
| 120 | Please provide a valid Billing City. | Optional field for transactions and customers must have correct format. |
| 121 | Please provide a valid Billing State. | Optional field for transactions and customers must have correct format. |
| 122 | Please 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. |
| 123 | Please provide a valid Billing Country. | Optional field for transactions and customers must have correct format. |
| 124 | Please provide a valid Shipping Name. | Optional field for transactions and customers must have correct format. |
| 125 | Please provide a valid Shipping Address. | Optional field for transactions and customers must have correct format. |
| 126 | Please provide a valid Shipping Address 2. | Optional field for transactions and customers must have correct format. |
| 127 | Please provide a valid Shipping City. | Optional field for transactions and customers must have correct format. |
| 128 | Please provide a valid Shipping County. | Optional field for transactions and customers must have correct format. |
| 129 | Please provide a valid Shipping State. | Optional field for transactions and customers must have correct format. |
| 130 | Please provide a valid Shipping Zip Code. | Optional field for transactions and customers must have correct format. |
| 131 | Please provide a valid Shipping Country | Optional field for transactions and customers must have correct format. |
| 132 | Please provide a valid Phone Number. | Optional field for transactions and customers must have correct format. |
| 133 | Please provide a valid Source State. | Required for calculate shipping requests. |
| 134 | Please provide a valid Source Zip Code. | Required for calculate shipping requests. |
| 135 | Please provide a valid list of Shippers. | Required for calculate shipping requests. |
| 136 | Please provide a valid Weight. | Required for calculate shipping requests. |
| 137 | Please provide a valid Fax Number. | Optional field for transactions and customers must have correct format. |
| 139 | Please make sure the Shipping State and Shipping Zip are accurate. | Returned if errors are returned from shipping provider(s) during calculate shipping request. |
| 140 | … | Dynamic error(s) returned from shipping provider(s) may be returned from CalculateShipping requests. |
| 141 | Please provide a valid Email Address. | Optional field for transactions and customers must have correct format. Required to email a receipt. |
| 148 | Please provide a valid CSC. | Optional field for transactions and must have correct format. May be required if configured in your security settings. |
| 149 | Please provide a valid Invoice Number. | Optional field for transactions and must have correct format. |
| 150 | Please provide a valid Description. | Optional field for transactions and must have correct format. |
| 151 | Please provide a valid Tax Amount. | Optional field for transactions and must have correct format. |
| 152 | Please provide a valid Customer Reference. | Optional field for transactions and must have correct format. |
| 153 | This customer profile does not have an email address to send the receipt. | A customer profile must have an email address in order for recurring receipts to be emailed to the customer. |
| 160 | Please provide a valid Frequency. | A frequency is required to create a recurring payment. |
| 161 | Please provide a valid Transaction Count. | A transaction count is required to create a recurring payment. |
| 162 | Please provide a valid Start Date. | A start date is required to create a recurring payment. |
| 163 | Please provide a valid Next Date. | A next date is required to create a recurring payment. |
| 164 | Please provide a valid Repeat value. | An optional repeat value may be sent for recurring payments. |
| 165 | Please provide a valid Recurring Payment ID. | A recurring payment ID is required to update a recurring payment. |
| 169 | No recurring payments were found with this criteria. | Export recurring payments request returned no results. |
| 170 | No approved transactions were found for this customer. | Export recurring payment request returned no results. |
| 171 | Please provide a unique customer ID. | Each request to create a customer must contain a unique customer ID. |
| 172 | Please provide a Customer Password that is greater than 6 characters and less than 255 characters. | If you have access to the PayTrace shopping cart, you must provide a password when creating a customer. |
| 175 | Please provide a valid Start Date. | Start date for exporting transaction reports. |
| 176 | Please provide a valid End Date. | End date for exporting transaction reports. |
| 177 | Please provide a date range. | The end date must be past/greater than the start date. |
| 178 | Please provide a valid User. | User account for exporting transaction reports. |
| 179 | Please provide a valid number of Days. | The Days value will need to be between 1 and 999 in the request. |
| 180 | No transactions were found with these criteria. | Export transactions request returned no results. |
| 185 | No customers were found with these criteria. | Export customers request returned no results. |
| 190 | Please provide a valid National Tax Amount. | Optional field for level 3 data and must have correct format. |
| 191 | Please provide a valid Merchant Tax ID. | Optional field for level 3 data and must have correct format. |
| 192 | Please provide a valid Customer Tax ID. | Optional field for level 3 data and must have correct format. |
| 193 | Please provide a valid Commodity Code. | Optional field for level 3 data and must have correct format. |
| 194 | Please provide a valid Discount Amount. | Optional field for level 3 data and must have correct format. |
| 195 | Please provide a valid Freight Amount. | Optional field for level 3 data and must have correct format. |
| 196 | Please provide a valid Duty Amount. | Optional field for level 3 data and must have correct format. |
| 197 | Please provide a valid Additional Tax Amount. | Optional field for level 3 data and must have correct format. |
| 198 | Please provide a valid Additional Tax Rate. | Optional field for level 3 data and must have correct format. |
| 199 | Please provide a valid Additional Tax Indicator. | Optional field for level 3 data and must have correct format. |
| 200 | Please provide a valid Line Item record. | Required field for level 3 data and must have correct format. |
| 201 | Please provide a valid Line Item Commodity Code. | Optional field for level 3 data and must have correct format. |
| 202 | Please provide a valid Line Item Description. | Optional field for level 3 data and must have correct format. |
| 203 | Please provide a valid Line Item Product ID. | Optional field for level 3 data and must have correct format. |
| 204 | Please provide a valid Line Item Quantity. | Optional field for level 3 data and must have correct format. |
| 205 | Please provide a valid Line Item Measure. | Optional field for level 3 data and must have correct format. |
| 206 | Please provide a valid Line Item Unit Cost. | Optional field for level 3 data and must have correct format. |
| 207 | Please provide a valid Line Item Additional Tax Amount. | Optional field for level 3 data and must have correct format. |
| 208 | Please provide a valid Line Item Additional Tax Rate. | Optional field for level 3 data and must have correct format. |
| 209 | Please provide a valid Line Item Discount. | Optional field for level 3 data and must have correct format. |
| 210 | Please provide a valid Line Item Amount. | Optional field for level 3 data and must have correct format. |
| 211 | Please provide a valid Line Item Additional Tax Indicator. | Optional field for level 3 data and must have correct format. |
| 212 | Please provide a valid Line Item Discount Rate. | Optional field for level 3 data and must have correct format. |
| 213 | Please provide a valid Line Item Discount Indicator. | Optional field for level 3 data and must have correct format. |
| 214 | Please provide a valid Line Item Net Gross Indicator. | Optional field for level 3 data and must have correct format. |
| 215 | Please provide a valid Line Item Debit Credit Indicator. | Optional field for level 3 data and must have correct format. |
| 230 | Batch was not initiated as no transactions are pending settlement. | Returned if request to SettleTranx is sent when no transactions may be settled. |
| 231 | Batch was not initiated as another batch is in progress or pending. | Returned if request to SettleTranx is sent when another batch is being settled or the last batch is pending any settlement problems. |
| 700 | This transaction was not approved because the authorization network was not available. Please retry this transaction again. | If a response is not returned to PayTrace from the issuing bank with in 30 seconds, then a response is returned through the API advising of the authorization network being unavailable. |
| 710 | Dynamic response from the processing network | If a void request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 711 | Dynamic response from the processing network | If a capture request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 712 | Dynamic response from the processing network | If a refund request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 713 | Dynamic response from the processing network | If a forced sale request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 740 | PayTrace is unable to process this check as the check processor information is incomplete or the network returned an error. | In the event that you receive this error message, please contact PayTrace Support to determine if some of the check processor information on your account is incomplete. |
| 750 | PayTrace does not support this transaction type for this check processor. | Specific check processors only support certain transaction types. For example, Paya only supports sale and some instances of void requests. If a request is sent w/ a transaction type that is not supported by the check processor enabled on the PayTrace account, this error is returned. |
| 777 | PayTrace blocked this transaction because it is a duplicate, and it may be reprocessed in ### minute(s). | cell-content |
| 778 | PayTrace blocked this transaction because it exceeded the specified velocity filter. | PayTrace compares requests to process new transactions against specified velocity filters when velocity filters are established on specific PayTrace accounts. For more information about velocity filters, contact PayTrace Support. |
| 779 | BLOCKED - This card number has been blocked to prevent potential fraud. | 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. |
| 811 | The Transaction ID that you provided was not found. | Transaction ID isn't found on their account. |
| 812 | The Transaction ID that you provided was found but was not processed by you | Transaction ID exists on this account but the user only has permission to view their own transactions and this transaction was processed by another user. |
| 813 | The Transaction ID that you provided was found but the card type is not supported. | Transaction ID exists but the card number is corrupt or is no longer supported. |
| 816 | The Transaction ID that you provided could not be captured. Only uncpatured, approved authorizations can be captured. | Transaction ID exists but it's status can't be captured. |
| 817 | The Transaction ID that you provided could not be refunded. Only settled transactions can be refunded. Please try to void the transaction instead. | Transaction ID exists but it's status can't be refunded. |
| 818 | The Transaction ID that you provided could not be voided. Only transactions that are pending settlement or uncaptured authorizations can be voided. | Transaction ID exists but it's status can't be voided. |
| 867 | Please provide valid new passwords. | Passwords must be provided when processing a request to change your password. |
| 869 | Please provide new passwords that are unique to your previous 4 passwords. | New passwords must be unique to your 4 previous passwords. |
| 880 | This customer is schedule for recurring payment # xxxxx and may not be deleted. | Customers with pending recurring payments may not be deleted. |
| 900 | Please indicate that you agree with PayTrace's terms and conditions. | The TERMS parameter must be set to Y. |
| 950 | Unreferenced refunds are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept refunds to be processed with out referencing the previously processed transaction's ID |
| 951 | Forced Sales are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept forced sales to be processed. |
| 952 | Swiped/card present transactions are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept card present transactions. |
| 973 | The processor information for xxxxxx is incomplete. | An incomplete PayTrace account is not able to process requests. |
| 974 | Your PayTrace account is not set up to use the PayTrace API. | Your account must have access to the API in order to process through it. |
| 975 | Your PayTrace account is not set up to process recurring transactions. | Your account must have access to the recurring payments module in order to process recurring payments. |
| 976 | Your account is only set up to process Cash Advances and Voids. | Cash advance accounts may only process cash advances, voids, email receipt, export transactions, and update password requests. |
| 978 | Your 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. |
| 979 | Password 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. |
| 980 | Log in failed for insufficient permissions. | The user account must have permission/access to process an authorization. |
| 981 | Log in failed for insufficient permissions. | The user account must have permission/access to process a refund. |
| 982 | Log in failed for insufficient permissions. | The user account must have permission/access to process a void. |
| 983 | Log in failed for insufficient permissions. | The user account must have permission/access to process a capture. |
| 984 | Log in failed for insufficient permissions. | The user account must have permission/access to process a forced sale. |
| 985 | Log in failed for insufficient permissions. | The user account must have permission/access to create, update, or delete customers. |
| 986 | Log in failed for insufficient permissions. | The user account must have permission/access to create, update, or export a recurring payment. |
| 987 | Please provide a valid method or request to process. | Only valid methods are accepted for processing through the API. |
| 988 | Log in failed. | An unsuccessful log in attempt occurred because of an IP rule conflict. |
| 989 | Log in failed for insufficient permissions. | The user account must have permission/access to export transactions. |
| 990 | Please provide properly formatted parameters. | API request is not properly formatted as a JSON format. |
| 993 | xxxxxx is not a valid parameter name. | An invalid parameter was included in the request. Few parameters are case sensitive. For example: number as "NUMBER" , encrypted_csc as "ENCRYPTED_CSC" |
| 997 | PayTrace API only supports POST requests. | All integration API requests should be of POST type to adhere to PCI requirements |
| 998 | Log in failed. | An unsuccessful 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. |
| 999 | Log in failed for insufficient permissions. | The user account must have permission/access to process a sale. |
| 1000 | Decryption failed. | Encrypted request data should be encrypted with merchant account specific public key only. |
| 9102-185 | System error occurred, and a PayTrace specialist has been notified. Thank you for your patience. | Non-Specific Error. Please contact Developer Support for further information. |
{
"errors":{
"errorCodeValue1":["Error Message 1"],
"errorCodeValue2":["Error Message 2"],
....
"errorCodeValueN":["Error Message N"],
}
}There can be N numbers of errorCodeValues.
{
"errors":{
"35":[
"Please provide a valid Credit Card Number."
],
"43":[
"Please provide a valid Expiration Month."
],
"118":[
"Please provide a valid Billing Address."]
],
}
}For API Testing & Integration, Make sure to check following:
You can use our test data during initial integration and API testing phase.
| 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.
| Credit Card Type | CSC Number | Response |
|---|---|---|
| Visa | 999 | Approval |
| MasterCard | 998 | Approval |
| Discover | 996 | Approval |
| American Express | 9997 | Approval |
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 |
$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 |
| $11.11 | Partial Approval |
| $52.00 | Partial Approval |
| Checking account number | Routing number |
|---|---|
| 123456 | 325070760 |
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 can be performed when the card is NOT present.
Post | /v1/transactions/sale/keyed |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
| 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 | Optional |
| custom_dba | 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 | Optional |
| 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 | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| 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 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.
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.
{
"amount":2.00,
"credit_card":{
"number":"4111111111111111",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"csc":"999",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*Above sample request contains only minimum required parameters.
{
"amount":2.00,
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"encrypted_csc":"Xd46EqA9ohOD+YVjfSVZAK4/EuQ3RAcqmnfv5h0Tjhew84MARl6yhNdGHW6i+fYJnOQEuDOc3O5RfQqOe6BI8ZboNsmZ82wjPYHe8EiykMdVqNdHVg4xjQBdkexbgA9WLU5Boyc1TmbtJGVpnwDnrR90n0JQpUE/72MSq7evlFXRAIGFcdMyq+QpbLaGi4mI3Fio5L+yn5O0COj8aMD2NalyGFAQmw90dw/4he475o+sGd+2ueEsBHTrDSspfGIACl79lbkSLYa3BRfTkvHAccNRkiY65WftgRW4SGVhs29AD78gNu1kEk/HcrE1PGW1RVC/e2dPT0okKFm4v+cW/w==",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":79195294,
"approval_code":"TAS677",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxxxx1111"
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968526,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxxxx1111"
}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.
Post | /v1/transactions/sale/swiped |
| 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 |
| integrator_id | A 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. | 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 Clien-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 → 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 → 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 → Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
| 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 | Optional |
| custom_dba | 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 | Optional |
| 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 | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":4.00,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
{
"amount":4.00,
"encrypted_swipe":"nELVjn9xI5m/CDSThOgMSvaXuBjCg+J4fuTLbQRlVXtwRd4toMgcdHEv9SFUCXw/BmTRbN/Vb431eoW6JawR983M2TbpjEd7qgmE87Y6C2A/sjoQWfU6WQGXJI08TRZXxFtds6ksYqRckthKT89Ym8q6AuXX4UR1CH/jsA20TKGpEolA/XHfXMS72nNLMcNti0+m5W6oPik50m7qSZJl0xFxXNsgN8mrKzMGhkQHsnPGSKjN30jkAa2ne8rYfQuoZQ/M9FEZzQWUX7JlKcrlWufO54jtuSC+DeGR+6pCzUqXctaGeKhIC12BfGVGNcRQMtHVZadGqXyR708fjeJdqg==",
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":79223005,
"approval_code":"TAS212",
"approval_message":"APPROVAL TAS212 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968531,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_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.
Post | /v1/transactions/sale/by_transaction |
| 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 |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":4.00,
"transaction_id":105968529,
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":105968532,
"approval_code":"TAS569",
"approval_message":"ADDRESS MATCH - Approved and completed",
"avs_response":"Address Match Only",
"csc_response":"",
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968531,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":""
}A Vault Sale will allow you to process a transaction with an existing Customer ID (Token) from your Customer Database (Vault) at PayTrace.
Post | /v1/transactions/sale/by_customer |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":4.00,
"customer_id":"customerId121",
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":79223005,
"approval_code":"TAS212",
"approval_message":"APPROVAL TAS212 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968531,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}If Customer_id customerid123 does not exist in PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"35":[
"Please provide a valid Credit Card Number."
],
"43":[
"Please provide a valid Expiration Month."
]
},
"external_transaction_id":""
}
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 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.
Post | /v1/transactions/authorization/keyed |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
| 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 | Optional |
| 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 | Optional |
| 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 | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| 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 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.
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.
{
"amount":3.50,
"credit_card":{
"number":"4111111111111111",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"csc":"999",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Encrypted parameters are encrypted_number and encrypted_csc in this sample request.
{
"amount":3.50,
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"encrypted_csc":"Xd46EqA9ohOD+YVjfSVZAK4/EuQ3RAcqmnfv5h0Tjhew84MARl6yhNdGHW6i+fYJnOQEuDOc3O5RfQqOe6BI8ZboNsmZ82wjPYHe8EiykMdVqNdHVg4xjQBdkexbgA9WLU5Boyc1TmbtJGVpnwDnrR90n0JQpUE/72MSq7evlFXRAIGFcdMyq+QpbLaGi4mI3Fio5L+yn5O0COj8aMD2NalyGFAQmw90dw/4he475o+sGd+2ueEsBHTrDSspfGIACl79lbkSLYa3BRfTkvHAccNRkiY65WftgRW4SGVhs29AD78gNu1kEk/HcrE1PGW1RVC/e2dPT0okKFm4v+cW/w==",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":105968544,
"approval_code":"TAS955",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxxxx1111"
}Following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968528,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxxxx1111"
}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.
Post | /v1/transactions/authorization/swiped |
| 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 |
| integrator_id | A 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. | 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 → 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 → 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 → Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
| 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 | Optional |
| custom_dba | A 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 | Optional |
| 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 | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":2.50,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
{
"amount":2.50,
"encrypted_swipe":"nELVjn9xI5m/CDSThOgMSvaXuBjCg+J4fuTLbQRlVXtwRd4toMgcdHEv9SFUCXw/BmTRbN/Vb431eoW6JawR983M2TbpjEd7qgmE87Y6C2A/sjoQWfU6WQGXJI08TRZXxFtds6ksYqRckthKT89Ym8q6AuXX4UR1CH/jsA20TKGpEolA/XHfXMS72nNLMcNti0+m5W6oPik50m7qSZJl0xFxXNsgN8mrKzMGhkQHsnPGSKjN30jkAa2ne8rYfQuoZQ/M9FEZzQWUX7JlKcrlWufO54jtuSC+DeGR+6pCzUqXctaGeKhIC12BfGVGNcRQMtHVZadGqXyR708fjeJdqg==",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":105968540,
"approval_code":"TAS955",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968656,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_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.
Post | /v1/transactions/authorization/by_transaction |
| 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 |
| 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 |
| integrator_id | A 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. | 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. |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":4.00,
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":105968550,
"approval_code":"TAS390",
"approval_message":"ADDRESS MATCH - Approved and completed",
"avs_response":"Address Match Only",
"csc_response":"",
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968531,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_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.
Post | /v1/transactions/authorization/by_customer |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the Authorizations 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 |
| 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 | Optional |
| 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 | Optional |
| 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 | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":3.70,
"customer_id":"customerId120",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":105968551,
"approval_code":"TAS625",
"approval_message":"APPROVAL TAS212 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":105968531,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}If customer id customerid123 does not exist in PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"35":[
"Please provide a valid Credit Card Number."
],
"43":[
"Please provide a valid Expiration Month."
]
},
"external_transaction_id":""
}
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.
Post | /v1/transactions/authorization/capture |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| transaction_id | A 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. | number | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| amount | Dollar 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. | number | Optional |
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.
| 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 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.
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.
{
"transaction_id":105968543,
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":112,
"status_message":"Your transaction was successfully captured.",
"transaction_id":105968543,
"external_transaction_id":""
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":113,
"status_message":"Your transaction was not captured.",
"transaction_id":105968531,
"external_transaction_id":""
}If an unauthorized transaction id is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"816":[
"The Transaction ID that you provided could not be captured. Only uncaptured, approved authorizations can be captured."
]
},
"external_transaction_id":""
}
This method can be used to void any unsettled transaction.
Post | /v1/transactions/void |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 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.
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.
{
"transaction_id":105968551,
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":109,
"status_message":"Your transaction was successfully voided.",
"transaction_id":105968551
}Following error response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":110,
"status_message":"Your transaction was not successfully voided.",
"transaction_id":105968552
}If a settled transaction id is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"818":[
"The Transaction ID that you provided could not be be voided. Only uncaptured, Only transactions that are pending settlement can be voided."
]
}
}
If an invalid transaction id is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"811":[
"The Transaction ID that you provided was not found."
]
}
}
This method can be used to adjust a transaction amount. Following conditions must be fulfilled for the successful transaction.
Post | /v1/transactions/adjust |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Required |
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: It should be an Unsettled transaction with PayTrace system to avoid any API errors. | string | Required |
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.
| 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 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.
{
"transaction_id":105968552,
"amount":5.50
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":180,
"status_message":"Your transaction amount was successfully adjusted."
}If an amount is invalid or does not meet adjustment criteria (described as earlier), following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"51":[
"Please provide a valid Amount."
]
}
}
As per the VISA Card brand enhancement mandate, a Refund Authorization or "Purchase Return Authorization" enables a card issuer to authorize and validate a refund for a cardholder, as well as identify if the account doesn't exist or has been closed. At this time this feature is only available for Visa transactions however, we anticipate this feature will be added for the other card brands in the future. Updates will be made as other Card Brands begin supporting this feature.
Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with Refund requests.
A Keyed Refund Authorization can be performed when the card is NOT present.
This Method can be used to issue a credit back to the credit card holder's account.
Post | /v1/transactions/refundauth/keyed |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
A successful request returns a HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| 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 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.
{
"amount":2.50,
"credit_card":{
"number":"4111111111111111",
"expiration_month":"11",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"csc":"999",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Encrypted parameters are encrypted_number and encrypted_csc in this sample request.
{
"amount":2.50,
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"11",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"encrypted_csc":"Xd46EqA9ohOD+YVjfSVZAK4/EuQ3RAcqmnfv5h0Tjhew84MARl6yhNdGHW6i+fYJnOQEuDOc3O5RfQqOe6BI8ZboNsmZ82wjPYHe8EiykMdVqNdHVg4xjQBdkexbgA9WLU5Boyc1TmbtJGVpnwDnrR90n0JQpUE/72MSq7evlFXRAIGFcdMyq+QpbLaGi4mI3Fio5L+yn5O0COj8aMD2NalyGFAQmw90dw/4he475o+sGd+2ueEsBHTrDSspfGIACl79lbkSLYa3BRfTkvHAccNRkiY65WftgRW4SGVhs29AD78gNu1kEk/HcrE1PGW1RVC/e2dPT0okKFm4v+cW/w==",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":281700927,
"approval_code":"TAS677",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxxxx1111"
}This Method can be used when a credit card is present. It issues credit back to the credit card holder's account.
Post | /v1/transactions/refundauth/swiped |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
A successful request returns a HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"amount":3.25,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Encrypted parameter encrypted_swipe is prepended with encrypted_ in this sample request.
{
"amount":3.25,
"encrypted_swipe":"nELVjn9xI5m/CDSThOgMSvaXuBjCg+J4fuTLbQRlVXtwRd4toMgcdHEv9SFUCXw/BmTRbN/Vb431eoW6JawR983M2TbpjEd7qgmE87Y6C2A/sjoQWfU6WQGXJI08TRZXxFtds6ksYqRckthKT89Ym8q6AuXX4UR1CH/jsA20TKGpEolA/XHfXMS72nNLMcNti0+m5W6oPik50m7qSZJl0xFxXNsgN8mrKzMGhkQHsnPGSKjN30jkAa2ne8rYfQuoZQ/M9FEZzQWUX7JlKcrlWufO54jtuSC+DeGR+6pCzUqXctaGeKhIC12BfGVGNcRQMtHVZadGqXyR708fjeJdqg==",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":281701722,
"approval_code":"TAS806",
"approval_message":"APPROVAL TAS806 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"external_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.
Post | /v1/transactions/refundauth/for_transaction |
| 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 |
| integrator_id | A 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. | 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. 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
A successful request returns a HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
{
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction successfully refunded.",
"transaction_id":281702876,
"approval_code":"TAS857",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"",
"external_transaction_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.
Post | /v1/transactions/refundauth/to_customer |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
A successful request returns a HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
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.
| 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 |
| approval_code | This code is generated by the credit card issuer and returned with a successful transaction. | string |
| approval_message | Transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for the possible values. | string |
| csc_response | A unique string identifier returned by the card issuer on CSC verification. Check out CSC Response for possible values. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
{
"amount":4.75,
"customer_id":"customerId120",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":281703158,
"approval_code":"TAS865",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"",
"external_transaction_id":""
}If customer id customerid123 does not exist in a PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"35":[
"Please provide a valid Credit Card Number."
],
"43":[
"Please provide a valid Expiration Month."
]
},
"external_transaction_id":""
}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 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.
Post | /v1/transactions/refund/keyed |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
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.
| 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 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.
{
"amount":2.50,
"credit_card":{
"number":"4111111111111111",
"expiration_month":"11",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"csc":"999",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Encrypted parameters are encrypted_number and encrypted_csc in this sample request.
{
"amount":2.50,
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"11",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"encrypted_csc":"Xd46EqA9ohOD+YVjfSVZAK4/EuQ3RAcqmnfv5h0Tjhew84MARl6yhNdGHW6i+fYJnOQEuDOc3O5RfQqOe6BI8ZboNsmZ82wjPYHe8EiykMdVqNdHVg4xjQBdkexbgA9WLU5Boyc1TmbtJGVpnwDnrR90n0JQpUE/72MSq7evlFXRAIGFcdMyq+QpbLaGi4mI3Fio5L+yn5O0COj8aMD2NalyGFAQmw90dw/4he475o+sGd+2ueEsBHTrDSspfGIACl79lbkSLYa3BRfTkvHAccNRkiY65WftgRW4SGVhs29AD78gNu1kEk/HcrE1PGW1RVC/e2dPT0okKFm4v+cW/w==",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":105968553,
"external_transaction_id":"",
"masked_card_number":"xxxxxxxxxxxx1111"
}This Method can be used when a credit card is present. It issues credit back to the credit card holder's account.
Post | /v1/transactions/refund/swiped |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
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.
| 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 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.
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.
{
"amount":3.25,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Encrypted parameter encrypted_swipe is prepended with encrypted_ in this sample request.
{
"amount":3.25,
"encrypted_swipe":"nELVjn9xI5m/CDSThOgMSvaXuBjCg+J4fuTLbQRlVXtwRd4toMgcdHEv9SFUCXw/BmTRbN/Vb431eoW6JawR983M2TbpjEd7qgmE87Y6C2A/sjoQWfU6WQGXJI08TRZXxFtds6ksYqRckthKT89Ym8q6AuXX4UR1CH/jsA20TKGpEolA/XHfXMS72nNLMcNti0+m5W6oPik50m7qSZJl0xFxXNsgN8mrKzMGhkQHsnPGSKjN30jkAa2ne8rYfQuoZQ/M9FEZzQWUX7JlKcrlWufO54jtuSC+DeGR+6pCzUqXctaGeKhIC12BfGVGNcRQMtHVZadGqXyR708fjeJdqg==",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":105968557,
"external_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.
Post | /v1/transactions/refund/for_transaction |
| 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 |
| integrator_id | A 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. | 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. 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
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.
| 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 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.
{
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction successfully refunded.",
"transaction_id":105968559,
"external_transaction_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.
Post | /v1/transactions/refund/to_customer |
| 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 |
| integrator_id | A 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. | 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| 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 |
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.
| 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 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.
{
"amount":4.75,
"customer_id":"customerId120",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":105968560,
"external_transaction_id":""
}If customer id customerid123 does not exist in a PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"35":[
"Please provide a valid Credit Card Number."
],
"43":[
"Please provide a valid Expiration Month."
]
},
"external_transaction_id":""
}
This method can be used to send a transaction receipt in an email.
Post | /v1/transactions/email_receipt |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| An Email address to where the receipt will be sent to. Note: One additional email address may be included using a comma separated string. | string | Required | |
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: It should be a legitimate transaction with PayTrace system to avoid any API errors. | number | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 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.
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.
{
"transaction_id":105968551,
"email":"email@domain.com",
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":149,
"status_message":"The receipt for transaction ID 105968551 was successfully emailed to <requested Email> "
}If an invalid transaction id is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"87":[
"The Transaction ID that you provided was not found in the PayTrace records, and the receipt could not be emailed."
]
}
}
If an invalid email address is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"141":[
"Please provide a valid Email Address."
]
}
}
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.
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.
Post | /v1/customer/create |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| customer_id | A 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. | string | No configuration settings applied. Required |
| credit_card | For supported Schema, Click here Credit_Card Schema. | object | No configuration settings applied. Required only if check data is not provided. |
| check | Check account detail. For supported Schema, Click here Check Schema. | object | No configuration settings applied. Required only if credit_card data is not provided. |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the transactions receipt may be sent. | string | Optional | |
| phone | Customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | Customer's fax number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema. | object | Optional |
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.
| 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 |
| customer_id | A unique identifier for each customer in the PayTrace system, value will be same as provided with the request. | string |
| masked_card_number | Credit 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 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.
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.
{
"customer_id":"customerTest150",
"credit_card":{
"number":"4111111111111111",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Encrypted parameter is encrypted_number in this sample request.
{
"customer_id":"customerTest150",
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":160,
"status_message":"The customer profile for customerTest150/Steve Smith was successfully created",
"customer_id":"customerTest150",
"masked_card_number":"xxxxxxxxxxxx1111"
}If customer_id already exists in the PayTrace database(Vault), following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"171":[
"Please provide a unique customer ID."
]
},
"masked_card_number":"xxxxxxxxxxxx1111"
}
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.
Post | /v1/customer/create_from_transaction |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| customer_id | A 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. | string | 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address Schema. | object | Optional |
| Customer's email address where the transactions receipt may be sent. | string | Optional | |
| phone | Customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | Customer's fax number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
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.
| 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 |
| customer_id | A unique identifier for each customer in the PayTrace system, value will be same as provided with the request. | string |
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.
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.
{
"customer_id":"customer789",
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"Mark Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":160,
"status_message":"The customer profile for customer789/Mark Smith was successfully created",
"customer_id":"customer789"
}If customer_id already exists in the PayTrace database(Vault), following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"171":[
"Please provide a unique customer ID."
]
}
}
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.
Post | /v1/customer/update |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| customer_id | A unique identifier for a customer profile stored in your Customer Database(Vault) at PayTrace. | string | No configuration settings applied. Required |
| credit_card | For supported Schema, Click here Credit_Card Schema. | object | No configuration settings applied. Required only if check data is not provided. |
| check | Check account detail. For supported Schema, Click here Check Schema. | object | No configuration settings applied. Required only if credit_card data is not provided. |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, Click here shipping_address Schema. | object | Optional |
| Customer's email address where the transactions receipt may be sent. | string | Optional | |
| phone | Customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | Customer's fax number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| new_id | A new unique identifier for a customer profile that may be sent with a request to update a customer profile. | string | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema. | object | Optional |
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.
| 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 |
| customer_id | A unique identifier for each customer in the PayTrace system, value will be same as provided with the request. | string |
| masked_card_number | Credit 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 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.
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.
{
"customer_id":"customerTest121",
"credit_card":{
"number":"4111111111111111",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"Steve Smith New",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
},
"shipping_address":{
"name":"Steve Smith New",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"county":"",
"zip":"85284",
"country":"US"
},
"check":{
"account_number":123456,
"routing_number":325070760
},
"email":"",
"phone":"",
"fax":"",
"new_id":"customerTest121New"
}Encrypted parameter is encrypted_number in this sample request.
{
"customer_id":"customerTest121",
"credit_card":{
"encrypted_number":"htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjYu1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuAnoLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRboG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
"expiration_month":"12",
"expiration_year":"2020"
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"Steve Smith New",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
},
"shipping_address":{
"name":"Steve Smith New",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"county":"",
"zip":"85284",
"country":"US"
},
"check":{
"account_number":123456,
"routing_number":325070760
},
"email":"",
"phone":"",
"fax":"",
"new_id":"customerTest121New"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":161,
"status_message":"The customer profile for customerTest121New/Steve Smith New was successfully updated.",
"customer_id":"customerTest121New",
"masked_card_number":"xxxxxxxxxxxx1111"
}If new customer id already exists in the PayTrace database(Vault), following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Please provide a unique customer ID."
]
},
"masked_card_number":"xxxxxxxxxxxx1111"
}
This method can be used to delete any existing customer profile stored in PayTrace's PCI-compliant Customer Database(Vault) for your account.
Post | /v1/customer/delete |
| Attribute | Description | Type | Attribute Requirements |
|---|---|---|---|
| customer_id | A unique identifier for a existing customer profile stored in your Customer Database(Vault) at PayTrace. | string | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 |
| customer_id | A unique identifier for each customer in the PayTrace system, value will be same as provided with the request. | string |
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.
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.
{
"customer_id":"customerTest121",
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":162,
"status_message":"The customer profile for customerTest121/Steve Smith was successfully deleted.",
"customer_id":"customerTest121"
}If customer id customerTest150 doesn't exist in the PayTrace database(Vault), following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerTest150, was not found or is incomplete."
]
}
}
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.
Post | /v1/customer/export |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| customer_id | A unique identifier for a existing customer profile stored in your Customer Database(Vault) at PayTrace. | string | Optional |
| created | For supported Schema, Click here Request_Creation_Record Schema. | object | Optional |
| Customer's email address | string | Optional | |
| include_bin | If set to true, this will return the first 6 and last 4 digits of the card number. | boolean | Optional |
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.
| 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 |
| customers | It is an array of customer profiles. For Customer Profile supported Schema, Click here Customer_Record Schema. | array |
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.
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.
{
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
{
"success":true,
"response_code":161,
"status_message":"Your request has been successfully completed.",
"customers:"[
{
"customer_id":"customer456",
"credit_card":{
"masked_number":"************1111",
"expiration_month":"12",
"expiration_year":"2020"
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284",
"country":"US"
},
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":"",
"country":"US"
},
"check":{
"account_number":123456,
"routing_number":325070760
},
"email":"",
"phone":"",
"fax":"",
"created":{
"at":"4/10/2015 12:39:57 AM",
"by":"sandbox123",
"from_ip":"11.111.111.11"
},
"discretionary_data":{
"Custom Discretionary Field Name1":"TestValue1",
"Custom Discretionary Field Name2":"TestValue12"
"Custom Discretionary Field Name3":"",
"Custom Discretionary Field Name4":"",
"Custom Discretionary Field Name5":"",
"Custom Discretionary Field Name6":"TestValue16",
}
},
{.....},
{.....}
]
}If provided customer id doesn't exists in the PayTrace database(Vault), following response with an empty customers array will be returned with a HTTP status code 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"customers":[
]
}
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.
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
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.
Post | /v1/level_three/mastercard |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| transaction_id | A 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. | number | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| invoice_id | A unique identifier for this transaction in your accounting or inventory management system. | string | Optional |
| customer_reference_id | Customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. The customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number. | 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. | number | Optional |
| national_tax_amount | Portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax. | number | Optional |
| freight_amount | Freight value should represent the portion of the transaction amount that was generated from shipping costs. | number | Optional |
| duty_amount | Portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax. | number | Optional |
| source_address | Only zip is a required attributes. For supported schema, Click here shipping_address Schema. | object | Optional |
| shipping_address | Only zip and country are required attributes. For supported schema, Click here shipping_address Schema. | object | Optional |
| additional_tax_amount | Any tax generated from freight or other services associated with the transaction. | number | Optional |
| additional_tax_included | A 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. | boolean | Optional |
| line_items | Line 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/objects | Optional |
| Attribute | Description | Type | Attribute Requirements |
|---|---|---|---|
| additional_tax_amount | Any tax generated from freight or other services associated with the transaction. | number | Optional |
| additional_tax_included | A 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. | boolean | Optional |
| additional_tax_rate | Rate at which additional tax was assessed. | number | Optional |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Optional |
| debit_or_credit | Flag used to determine whether the line item amount was a debit or a credit to the customer. Generally always a debit or a factor that increased the transaction amount. Possible values are D (net is a debit) and C (net is a credit). | string | Optional |
| description | Optional text describing the transaction, products, customers, or other attributes of the transaction. Note: 35 characters max limit. | string | Optional |
| discount_amount | Discount value should represent the amount discounted from the original transaction amount. | number | Optional |
| discount_rate | Rate 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. | number | Optional |
| discount_included | A boolean flag used to indicate whether discount was applied to the transaction amount in reference to this specific line item record. | boolean | Optional |
| merchant_tax_id | Merchant’s tax identifier used for tax reporting purposes. | string | Optional |
| product_id | Your unique identifier for the product. | string | Optional |
| quantity | Item count of the product in this order. | number | Optional |
| tax_included | A boolean flag used to indicate whether a line item amount includes tax or not. | boolean | Optional |
| unit_of_measure | Unit of measure applied to the product and its quantity. Click here to find:Level 3 Unit of Measurement Codes. | string | Optional |
| unit_cost | Product amount per quantity. | number | Optional |
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.
| 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 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.
With an invalid transaction id or non eligible transaction, you will get an error response with a HTTP status code - 400 Bad Request.
{
"transaction_id":105968573,
"integrator_id":"xxxxxxxxxx",
"invoice_id":"inv1234",
"customer_reference_id":"PO123456",
"tax_amount":8.10,
"national_tax_amount":0.00,
"freight_amount":0.00,
"duty_amount":0.00,
"freight_amount":0.00,
"source_address":{
"zip":"99201"
},
"shipping_address":{
"zip":"85284",
"country":"US"
},
"additional_tax_amount":0.40,
"additional_tax_included":true,
"line_items":[
{
"additional_tax_amount":0.40,
"additional_tax_included":true,
"additional_tax_rate":0.08,
"amount":19.99,
"debit_or_credit":"D",
"description":"business services",
"discount_amount":3.27,
"discount_rate":0.01,
"discount_included":true,
"merchant_tax_id":"12-123456",
"product_id":"sku1245",
"quantity":4,
"tax_included":true,
"unit_of_measure":"EACH",
"unit_cost":5.24
},
{....}
]
}{
"additional_tax_amount":0.40,
"additional_tax_included":true,
"additional_tax_rate":0.08,
"amount":19.99,
"debit_or_credit":"D",
"description":"business services",
"discount_amount":3.27,
"discount_rate":0.01,
"discount_included":true,
"merchant_tax_id":"12-123456",
"product_id":"sku1245",
"quantity":4,
"tax_included":true,
"unit_of_measure":"EACH",
"unit_cost":5.24
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":170,
"status_message":"Visa/MasterCard enhanced data was successfully added to Transaction ID 105968573. 1 line item records were created."
}With an invalid transaction id or non eligible transaction, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"58":[
"Please provide a valid Transaction ID."
]
}
}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.
Post | /v1/level_three/visa |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| transaction_id | A 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. | number | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| invoice_id | A unique identifier for this transaction in your accounting or inventory management system. | string | Optional |
| customer_reference_id | Customer reference ID is only used for transactions that are identified as corporate or purchasing credit cards. The customer reference ID is an identifier that your customer may ask you to provide in order to reference the transaction to their credit card statement. Also known as a PO Number. | 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. | number | Optional |
| national_tax_amount | Portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax. | number | Optional |
| merchant_tax_id | Merchant’s tax identifier used for tax reporting purposes. | string | Optional |
| customer_tax_id | Customer’s tax identifier used for tax reporting purposes. | string | Optional |
| commodity_code | Commodity code that generally applies to each product included in the order. Commodity codes are generally assigned by your merchant service provider. | string | Optional |
| discount_amount | Discount value should represent the amount discounted from the original transaction amount. | number | Optional |
| freight_amount | Freight value should represent the portion of the transaction amount that was generated from shipping costs. | number | Optional |
| duty_amount | Portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value added tax. | number | Optional |
| source_address | Only zip is a required attributes. For supported schema, click here shipping_address Schema. | object | Optional |
| shipping_address | Only zip and country are required attributes. For supported schema, click here shipping_address Schema. | object | Optional |
| additional_tax_amount | Any tax generated from freight or other services associated with the transaction. | number | Optional |
| additional_tax_rate | Rate at which additional tax was assessed. | number | Optional |
| line_items | Line 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/objects | Optional |
| Attribute | Description | Type | Attribute Requirements |
|---|---|---|---|
| additional_tax_amount | Any tax generated from freight or other services associated with the transaction. | number | Optional |
| additional_tax_rate | Rate at which additional tax was assessed. | number | Optional |
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Optional |
| commodity_code | Commodity code that generally applies to each product included in the order. Commodity codes are generally assigned by your merchant service provider. | string | Optional |
| description | Optional text describing the transaction, products, customers, or other attributes of the transaction. Note: 35 characters max limit. | string | Optional |
| discount_amount | Discount value should represent the amount discounted from the original transaction amount. | number | Optional |
| product_id | Your unique identifier for the product. | string | Optional |
| quantity | Item count of the product in this order. | number | Optional |
| transaction_id | A 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. | number | Optional |
| unit_of_measure | Unit of measure applied to the product and its quantity. Click here to find: Level 3 Unit of Measurement Codes. | string | Optional |
| unit_cost | Product amount per quantity. | number | Optional |
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.
| 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 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.
With an invalid transaction id or non eligible transaction, you will get an error response with a HTTP status code - 400 Bad Request.
{
"transaction_id":105968571,
"integrator_id":"xxxxxxxxxx",
"invoice_id":"inv12345",
"customer_reference_id":"123abcd",
"tax_amount":4.99,
"national_tax_amount":1.72,
"merchant_tax_id":"3456defg",
"customer_tax_id":"3456test",
"commodity_code":"4321",
"discount_amount":0.99,
"freight_amount":0.75,
"duty_amount":0.32,
"source_address":{
"zip":"94947"
},
"shipping_address":{
"zip":"94948",
"country":"US"
},
"additional_tax_amount":0.4,
"additional_tax_rate":0.01,
"line_items":[
{
"additional_tax_amount":0,
"additional_tax_rate":0.08,
"amount":19.99,
"commodity_code":"123commodity",
"description":"plumbing",
"discount_amount":3.27
"product_id":"skucode123",
"quantity":4,
"unit_of_measure":"EACH",
"unit_cost":4.24
},
{....}
]
}{
"additional_tax_amount":0,
"additional_tax_rate":0.08,
"amount":19.99,
"commodity_code":"123commodity",
"description":"plumbing",
"discount_amount":3.27
"product_id":"skucode123",
"quantity":4,
"unit_of_measure":"EACH",
"unit_cost":4.24
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":170,
"status_message":"Visa/MasterCard enhanced data was successfully added to Transaction ID 105968571. 1 line item records were created."
}With an invalid transaction id or non eligible transaction, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"58":[
"Please provide a valid Transaction ID."
]
}
}This method can be used to initiate transactions settlement to your merchant service provider.
Post | /v1/transactions/settle |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 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.
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.
{
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":175,
"status_message":"Your transaction was successfully approved.",
"batch":{
"number":"570",
},
"transaction_count":2,
"net_amount":25"
}If no transactions are pending for settlement, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"230":[
"Batch was not initiated as no transactions are pending settlement."
]
}
}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.
Post | /v1/batches/export_one |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| batch_number | A batch number to find specific batch details. This value is the sequential number assigned to the batch. | number | Optional |
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.
| 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 |
| batch | This object contains details about the batch. Note : For supported Schema, Click here Batch_Record Schema. | object |
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.
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.
{
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"batch":{
"number":"49",
"visa":{
"sales":2,
"collected":45,
"refunds":0,
"refunded":0
},
"master_card":{
"sales":2,
"collected":32,
"refunds":1,
"refunded":5.70
},
"diners_club":{
"sales":0,
"collected":0,
"refunds":0,
"refunded":0
},
"american_express":{
"sales":0,
"collected":0,
"refunds":0,
"refunded":0
},
"discover":{
"sales":0,
"collected":0,
"refunds":0,
"refunded":0
},
"private_label":{
"sales":0,
"collected":0,
"refunds":0,
"refunded":0
},
"settled":"7/28/2016"
}
If batch_number 1 doesn't exist, following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"batch":{
"number":"1",
"visa":{
"sales":0,
"collected":0.0,
"refunds":0.0,
"refunded":0
},
"master_card":{
"sales":0,
"collected":0.0,
"refunds":0.0,
"refunded":0
},
"diners_club":{
"sales":0,
"collected":0.0,
"refunds":0.0,
"refunded":0
},
"american_express":{
"sales":0,
"collected":0.0,
"refunds":0.0,
"refunded":0
},
"discover":{
"sales":0,
"collected":0.0,
"refunds":0.0,
"refunded":0
},
"private_label":{
"sales":0,
"collected":0.0,
"refunds":0.0,
"refunded":0
},
"settled":""
}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.
Post | /v1/batches/export |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| start_date | Start 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. | string | Required |
| end_date | End 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. | string | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 |
| batches | It is an array of batch summary records. For supported Schema, Click here Batch_Summary_Record Schema | array of objects |
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.
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.
{
"start_date":"07/10/2016",
"end_date":"07/15/2016",
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"batches":[
{
"number":48,
"created":{
"at":"7/11/2016"
},
"transaction_count":5,
"net_amount":15,
"sale_count":3,
"sales_amount":30.5,
"refund_count":2,
"refund_amount":15.5
},
{
"number":49,
"created":{
"at":"7/14/2016"
},
"transaction_count":4,
"net_amount":77,
"sale_count":4,
"sales_amount":77,
"refund_count":0,
"refund_amount":0
},
{.....},
{.....}
]
}If no batch exists within a request date range, following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"180":[
"No transactions were found with these criteria.",
"No transactions were found with these criteria."
]
}
}This method can be used to export settled transactions details within a specific batch. This Method will return one or more transaction records.
Post | /v1/batches/transaction_list |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| batch_number | A batch number to export the transactions. This value is the sequential number assigned to the batch. | number | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 |
| transactions | It 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 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.
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.
{
"batch_number":50,
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"transactions":[
{
"transaction_id":"105968570",
"credit_card":{
"masked_number":"************1111",
"expiration_month":"12",
"expiration_year":"2020"
},
"transaction_type":"SALE",
"description":"",
"amount":20,
"invoice_id":"1234567",
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":""
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284"
},
"receipt_emailed_to":"",
"tax_amount":"4.99",
"customer_reference_id":"1234abcd",
"approval_code":"TAS370",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"status_code":"GB49",
"status_message":"GB49",
"created":{
"through":"API",
"at":"7/15/2016 9:56:53 AM",
"by":"sandboxUser",
"from_ip":"11.11.111.111"
},
"settled":"7/15/2016 08:31:11 PM",
"customer_id":"customer456"
},
{.....},
{.....}
]
}If batch doesn't exist or no transaction exists with request batch, following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"180":[
"No transactions were found with these criteria."
]
}
}This method can be used to export a specific credit card transaction details.
Post | /v1/transactions/export/by_id |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| 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. | string | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| transaction_type | The transaction type to find transactions. Possible values : SALE, AUTHORIZATION, STR/FWD, REFUND, VOID, CAPTURE, FORCE, SETTLED, PENDING, DECLINED. | 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 |
| include_bin | If set to true, this will return the first 6 and last 4 digits of the card number. | boolean | Optional |
| including_text | The text submitted will be used to locate transactions containing this text, to narrow down the export results. | string | Optional |
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.
| 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 |
| transactions | It is an array of transaction detail record object. Note : For supported Schema, Click here Transaction_Detail_Record Schema. | array of objects |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"transaction_id":105968573,
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"transactions":[
{
"transaction_id":"105968570",
"credit_card":{
"masked_number":"************1111",
"expiration_month":"12",
"expiration_year":"2020"
},
"transaction_type":"SALE",
"description":"",
"amount":20,
"invoice_id":"1234567",
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":"",
"country":""
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284",
"country":"US"
},
"receipt_emailed_to":"",
"tax_amount":"8.10",
"customer_reference_id":"PO123456",
"approval_code":"VTLMC1",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"status_code":"GB571",
"status_message":"GB571",
"created":{
"through":"API",
"at":"4/10/2016 4:06:53 AM",
"by":"sandbox123",
"from_ip":"44.111.99.99"
},
"settled":"4/10/2016 08:31:11 PM",
"customer_id":"customer456"
"discretionary_data":{
"Custom Discretionary Field Name1":"TestValue1",
"Custom Discretionary Field Name2":"TestValue12"
"Custom Discretionary Field Name3":"TestValue1",
"Custom Discretionary Field Name4":"TestValue14",
"Custom Discretionary Field Name5":"",
"Custom Discretionary Field Name6":"TestValue16",
}
}
],
"external_transaction_id":""
}If provided transaction id does not exist, following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"external_transaction_id":"",
"transactions":[
]
}
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.
Post | /v1/transactions/export/by_date_range |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| 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. | string | Required |
| transaction_type | The transaction type to find transactions. Possible values : SALE, AUTHORIZATION, STR/FWD, REFUND, VOID, CAPTURE, FORCE, SETTLED, PENDING, DECLINED. | 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 |
| include_bin | If set to true, this will return the first 6 and last 4 digits of the card number. | boolean | Optional |
| including_text | The text submitted will be used to locate transactions containing this text, to narrow down the export results. | string | Optional |
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.
| 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 |
| transactions | It 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_id | A unique identifier of the request from your system that will be returned in the response. | string |
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.
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.
{
"start_date":"04/10/2016",
"end_date":"04/15/2016",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"transactions":[
{
"transaction_id":"105968573",
"credit_card":{
"masked_number":"************5454",
"expiration_month":"12",
"expiration_year":"20"
},
"transaction_type":"SALE",
"description":"",
"amount":110,
"invoice_id":"inv1234",
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":"",
"country":""
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284",
"country":"US"
},
"receipt_emailed_to":"",
"tax_amount":"8.10",
"customer_reference_id":"PO123456",
"approval_code":"VTLMC2",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"status_code":"GB571",
"status_message":"GB571",
"created":{
"through":"API",
"at":"4/10/2016 4:07:53 AM",
"by":"sandbox123",
"from_ip":"44.111.99.99"
},
"settled":"4/10/2016 08:31:11 PM",
"customer_id":
"discretionary_data":{
"Custom Discretionary Field Name1":"TestValue1",
"Custom Discretionary Field Name2":"TestValue12"
"Custom Discretionary Field Name3":"TestValue1",
"Custom Discretionary Field Name4":"TestValue14",
"Custom Discretionary Field Name5":"",
"Custom Discretionary Field Name6":"TestValue16",
}
},
{.....},
{.....}
],
"external_transaction_id":""
}If provided transaction id does not exist, following response will be returned with a HTTP Status 400 Bad Request.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"external_transaction_id":"",
"transactions":[
]
}
If an invalid date range is sent, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"177":[
"Please provide a valid date range."
],
"180":[
"No transactions were found with these criteria."
]
},
"external_transaction_id":""
}
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.
This Method allows you to create a recurring payment with an existing customer from your Customer Database(Vault) at PayTrace.
Post | /v1/recurrence/create |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| recurrence | Recurrence Payment detail. For supported Schema, Click here Recurrence_Record Schema. | object | Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| description | Optional 255-character max text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
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.
| 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 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.
If customer_id - customerid123 does not exist in PayTrace vault, you will get an error response with a HTTP status code - 400 Bad request.
{
"customer_id":"customerId123",
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"amount":4.00,
"customer_receipt":true,
"frequency":"3",
"start_date":"08/03/2016",
"total_count":"12",
"transaction_type":"sale"
}
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":150,
"status_message":"The recurring transaction was successfully created.",
"recurrence":{
"id":"647914"
}
}If Customer_id customerid123 does not exist in PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
]
}
}This Method allows you to modify existing recurring payment with recurring payment id.
Post | /v1/recurrence/update |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| integrator_id | A 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. | string | No configuration settings applied. Required |
| recurrence | Recurrence Payment detail. Only Id is required and remaining attributes are optional. For supported Schema, Click here Recurrence_Record Schema. | object | Required |
| 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 |
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.
| 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 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.
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.
{
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"id":"647918",
"amount":2.00
}
}*Above sample request contains only minimum required parameters to update amount.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":151,
"status_message":"The recurring transaction was successfully updated.",
"recurrence":{
"id":"647918"
}
}If recurrence id does not exist, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"165":[
"Please provide a valid Recurring Payment ID."
],
"30":[
"Customer ID, , was not found or is incomplete."
],
"116":[
"Please provide a valid Transaction Type."
],
"160":[
"Please provide a valid Frequency."
],
"161":[
"Please provide a valid Transaction Count."
]
}
}This Method allows you to delete existing recurring payment with recurring payment id permanently.
Post | /v1/recurrence/delete |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| integrator_id | A 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. | string | No configuration settings applied. Required |
| recurrence | Recurrence Payment detail. Only Id is required. For supported Schema, Click here Recurrence_Record Schema. | object | Required |
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.
| 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 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.
{
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"id":"647917"
}
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":152,
"status_message":"The recurring transaction was successfully deleted.",
"recurrence":{
"id":"647917"
}
}This Method can be used to export a single recurring payment or all recurring payments for a specific customer.
Post | /v1/recurrence/export |
| 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 to find all recurring payments transaction for specific customer. |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
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.
| 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 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.
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.
To find all recurrence payment for specific customer.
{
"customer_id":"customerId123",
"integrator_id":"xxxxxxxxxx"
}OR
To find specific recurrence payment transaction.
{
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"id":"708751"
}
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":152,
"status_message":"The recurring transaction was successfully deleted.",
"recurrences":[
{
"id":"708751",
"amount":10,
"customer_id":"customerId123",
"next_date":"08/15/2016",
"total_count":10,
"current_count":10,
"repeat_count":0,
"description":"Recurring payment demo."
},
{.....},
{.....}
]
}If customer id does not exist, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"169":[
"No recurring payments were found with this criteria."
]
}
}This Method can be used to export a most recent approved recurring payment transaction based on the specified customer profile.
Post | /v1/recurrence/export_approved |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 |
| 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 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.
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.
{
"customer_id":"customerId123",
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":155,
"status_message":"This customer's most recent recurring transaction took place on 8/14/2016 12:31:16 AM.",
"created":{
"at":"8/14/2016 12:31:16 AM"
},
"approval_code":"TAS632",
"amount":10,
"next_date":"08/14/2016",
"discretionary_data":{
"TOTALCOUNT":"10",
"CURRENTCOUNT":"10"
},
"description":"Recurring payment demo.",
"recurrence":{
"id":"708751"
}
}If customer id does not have any recurring transactions, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"170":[
"No approved transactions were found for this customer."
]
}
}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.
Post | /v1/password/change |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| new_password | A new password to be updated. | string | Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 |
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.
If new password is similar to the last 5 passwords, you will get an error response with a HTTP status code - 400 Bad request.
{
"new_password":"NewPasswordValue",
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":100,
"status_message":"Your password was successfully updated."
}If a new password is similar to the last 5 passwords, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"869":[
"Please provide new passwords that are unique to your previous 5 passwords."
]
}
}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.
Check or ACH (Automated Clearing House) Sale transactions can be performed with this method by providing customer's key entered checking account details.
Post | /v1/checks/sale/by_account |
| 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 |
| check | Check account detail. For supported Schema, Click here Check Schema. | object | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object | Billing 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_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 |
| Attribute | Description | Type | Attributes Requirements | ||
|---|---|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address. | object | Optional | ||
| Customer's email address where the transactions 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 | object | Optional |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
With a declined check transactions, appropriate Response code will be returned in the error response.
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.
{
"amount":2.00,
"check":{
"account_number":123456,
"routing_number":325070760
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"John Doe",
"street_address":"1234 Main",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981619
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981619,
"ach_code":0,
"ach_message":""
}For real time check processors, following response will be returned with a HTTP Status 400 Bad Request.
Note: If a real time processor is Paya, ach_code will not be included.
{
"success":false,
"response_code":125,
"status_message":"Your check was NOT successfully processed.",
"check_transaction_id":981610,
"ach_code":0 or any other number,
"ach_message":""
}This Method allows you to process a check transaction with an existing Customer ID (Token) from your Customer Database(Vault) at PayTrace.
Post | /v1/checks/sale/by_customer |
| 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 with ACH details at PayTrace Vault to avoid API errors. | string | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object | Billing 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_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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address. | object | Optional |
| Customer's email address where the transactions 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 |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
With a declined check transactions, appropriate Response code will be returned in the error response.
For example, if a check transaction is not approved, you will get a declined transaction response with a HTTP status code - 400 Bad request.
{
"amount":2.00,
"customer_id":"customerId121",
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981620
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981620,
"ach_code":0,
"ach_message":""
}For real time check processors, following response will be returned with a HTTP Status 400 Bad Request.
Note: If a real time processor is Paya, ach_code will not be included.
{
"success":false,
"response_code":125,
"status_message":"Your check was NOT successfully processed.",
"check_transaction_id":981620,
"ach_code":0 or any other number,
"ach_message":""
}If Customer_id customerid123 does not exist or it doesn't have ACH account details in PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"45":[
"Please provide a valid Checking Account Number."
],
"46":[
"Please provide a valid Transit Routing Number."
]
}
}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.
Post | /v1/checks/hold/by_account |
| 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 |
| check | Check account detail. For supported Schema, Click here Check Schema. | object | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object | Billing 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_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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address. | object | Optional |
| Customer's email address where the transactions 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 |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
With a declined check transactions, appropriate Response code will be returned in the error response.
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.
{
"amount":2.00,
"check":{
"account_number":123456,
"routing_number":325070760
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"John Doe",
"street_address":"1234 Main",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981620
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981621,
"ach_code":0,
"ach_message":""
}For real time check processors, following response will be returned with a HTTP Status 400 Bad Request.
Note: If a real time processor is Paya, ach_code will not be included.
{
"success":false,
"response_code":125,
"status_message":"Your check was NOT successfully processed.",
"check_transaction_id":981625,
"ach_code":0 or any other number,
"ach_message":""
}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.
Post | /v1/checks/hold/by_customer |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object | Billing 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_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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address. | object | Optional |
| Customer's email address where the transactions 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 |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
With a declined check transactions, appropriate Response code will be returned in the error response.
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.
{
"amount":2.00,
"customer_id":"customerId121",
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":9981621
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":9981622,
"ach_code":0,
"ach_message":""
}For real time check processors, following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":125,
"status_message":"Your check was NOT successfully processed.",
"check_transaction_id":9981610,
"ach_code":0 or any other number,
"ach_message":""
}If Customer_id customerid123 does not exist or it doesn't have ACH account details in PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"45":[
"Please provide a valid Checking Account Number."
],
"46":[
"Please provide a valid Transit Routing Number."
]
}
}This method can be used to issue a refund check by providing customer's checking account details.
Post | /v1/checks/refund/by_account |
| 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 |
| check | Check account detail. For supported Schema, Click here Check Schema. | object | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object | Billing 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_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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address. | object | Optional |
| Customer's email address where the transactions 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 |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
{
"amount":2.00,
"check":{
"account_number":123456,
"routing_number":325070760
},
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"John Doe",
"street_address":"1234 Main",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":122,
"status_message":"Your check was successfully refunded.",
"check_transaction_id":981628
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":122,
"status_message":"Your check was successfully refunded.",
"check_transaction_id":981629,
"ach_code":0,
"ach_message":""
}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.
Post | /v1/checks/refund/by_customer |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| billing _address | For supported Schema, Click here Billing_Address Schema. | object | Billing 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_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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address. | object | Optional |
| Customer's email address where the transaction 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 |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
{
"amount":2.50,
"customer_id":"customerId121",
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":122,
"status_message":"Your check was successfully refunded.",
"check_transaction_id":9981631
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":122,
"status_message":"Your check was successfully refunded.",
"check_transaction_id":9981632,
"ach_code":0,
"ach_message":""
}If Customer_id customerid123 does not exist or it doesn't have ACH account details in PayTrace vault, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"30":[
"Customer ID, customerid123, was not found or is incomplete."
],
"45":[
"Please provide a valid Checking Account Number."
],
"46":[
"Please provide a valid Transit Routing Number."
]
}
}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.
Post | /v1/checks/refund/by_transaction |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| check_transaction_id | A unique identifier for each check transaction in the PayTrace system. Note: It should be a settled check transaction id to avoid any API errors. | number | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| 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 | Optional |
| shipping_address | For supported schema, click here shipping_address. | object | Optional |
| Customer's email address where the transaction 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 |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
| ach_code | This 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_message | A message generated by the real-time check processor. | string |
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.
{
"check_transaction_id":9981615,
"integrator_id":"xxxxxxxxxx"
}*Above sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":122,
"status_message":"Your check was successfully refunded.",
"check_transaction_id":9981632
}If it's a real time check processor - 2 additional parameters
{
"success":true,
"response_code":122,
"status_message":"Your check was successfully refunded.",
"check_transaction_id":9981635,
"ach_code":0,
"ach_message":""
}If check_transaction_id does not exist or it is not a settled transaction, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"80":[
"The Check ID that you provided was not found in the PayTrace record."
]
}
}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.
Post | /v1/checks/manage/fund |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| check_transaction_id | A unique identifier for each check transaction in the PayTrace system. Note: It should be an unsettled check transaction id to avoid any API errors. | number | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Optional |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
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.
{
"check_transaction_id":9981612,
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":124,
"status_message":"Your check was successfully managed.",
"check_transaction_id":9981612
}If check_transaction_id does not exist or it is not a settled transaction, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"80":[
"The Check ID that you have provided was not found in the PayTrace records. It may already be voided or settled."
]
}
}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.
Post | /v1/checks/manage/void |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| check_transaction_id | A unique identifier for each check transaction in the PayTrace system. Note: It should be an unsettled check transaction id to avoid any API errors. | number | No configuration settings applied. Required |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| amount | Dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Optional |
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.
| 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_transaction_id | A unique identifier for each check transaction in the PayTrace system. | number |
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.
{
"check_transaction_id":9981614,
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":124,
"status_message":"Your check was successfully managed.",
"check_transaction_id":9981614
}If check_transaction_id does not exist or it is not a settled transaction, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"80":[
"The Check ID that you have provided was not found in the PayTrace records. It may already be voided or settled."
]
}
}This method can be used to send a check transaction receipt in an email.
Post | /v1/checks/email_receipt |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
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.
| 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 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.
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.
{
"check_transaction_id":9981612,
"email":"email@domain.com",
"integrator_id":"xxxxxxxxxx"
}Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":149,
"status_message":"The receipt for transaction ID 9981612 was successfully emailed to <requested Email> "
}If an invalid check transaction id is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"87":[
"The Transaction ID that you provided was not found in the PayTrace records, and the receipt could not be emailed."
]
}
}If an invalid email address is submitted, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"141":[
"Please provide a valid Email Address."
]
}
}This method can be used to export a specific check transaction details.
Post | /v1/checks/export/by_id |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
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.
| 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 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.
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.
{
"check_transaction_id":9981619,
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"check_transactions":[
{
"check_transaction_id":9981619,
"check":{
"masked_account_number":"************3456",
"masked_routing_number":"************0760"
},
"check_type":"SALE",
"description":"",
"amount":5,
"invoice_id":"1234567",
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":"",
"country":""
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284",
"country":"US"
},
"receipt_emailed_to":"",
"tax_amount":"1.10",
"customer_reference_id":"PO123456",
"status_code":"Y",
"created":{
"through":"API",
"at":"1/10/2017 4:06:53 PM",
"by":"sandbox123",
"from_ip":"x.x.x.x"
},
"customer_id":"customer456"
"discretionary_data":{
"Custom Discretionary Field Name1":"TestValue1",
"Custom Discretionary Field Name2":"TestValue12"
"Custom Discretionary Field Name3":"TestValue1",
"Custom Discretionary Field Name4":"TestValue14",
"Custom Discretionary Field Name5":"",
"Custom Discretionary Field Name6":"TestValue16",
}
}
]
}If provided check transaction id does not exist, following response will be returned with a HTTP Status 400 Bad Request.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"check_transactions":[
]
}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.
Post | /v1/checks/export/by_date_range |
| 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 |
| integrator_id | A 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. | string | No configuration settings applied. Required |
| 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 |
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.
| 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 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.
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.
{
"start_date":"01/10/2017",
"end_date":"01/20/2017",
"integrator_id":"xxxxxxxxxx"
}*This sample request contains only minimum required parameters.
Following response will be returned with a HTTP Status 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"check_transactions":[
{
"check_transaction_id":9981619,
"check":{
"masked_account_number":"************3456",
"masked_routing_number":"************0760"
},
"check_type":"SALE",
"description":"",
"amount":5,
"invoice_id":"1234567",
"shipping_address":{
"name":"",
"street_address":"",
"street_address2":"",
"city":"",
"state":"",
"county":"",
"zip":"",
"country":""
},
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"street_address2":"",
"city":"Spokane",
"state":"WA",
"zip":"85284",
"country":"US"
},
"receipt_emailed_to":"",
"tax_amount":"1.10",
"customer_reference_id":"PO123456",
"status_code":"Y",
"created":{
"through":"API",
"at":"1/10/2017 4:06:53 PM",
"by":"sandbox123",
"from_ip":"x.x.x.x"
},
"customer_id":"customer456"
"discretionary_data":{
"Custom Discretionary Field Name1":"TestValue1",
"Custom Discretionary Field Name2":"TestValue12"
"Custom Discretionary Field Name3":"TestValue1",
"Custom Discretionary Field Name4":"TestValue14",
"Custom Discretionary Field Name5":"",
"Custom Discretionary Field Name6":"TestValue16",
}
},
{.....},
{.....}
]
}If provided check transaction id does not exist, following response will be returned with a HTTP Status 400 Bad Request.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"check_transactions":[
]
}If an invalid date range is sent, following error response will be returned with a HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"177":[
"Please provide a valid date range."
],
"180":[
"No transactions were found with these criteria."
]
}
}