The PayTrace API (Application Programming Interface) is a powerful software solution that enables any software developer to integrate the power of the PayTrace Payment Gateway into their proprietary software. Software developers may use the PayTrace API to add payment-processing functionality into their software through the seamless integration of HTTPS Post requests.
Through the power and efficiency of the PayTrace API, your software applications may process electronic payments in real-time and receive payment authorizations within 3 to 6 seconds. The PayTrace API is built to process transactions and recurring payments, store customer and transaction profiles and email receipts.
The PayTrace API uses HTTPS post with Requests and Responses. This API does NOT need to be installed or registered on a web server or on a client's computer which is running the software application. Integrating with the PayTrace API is quick and easy with our 5-star Support.
JSON API is designed as a REST API (Representational State Transfer). It has predictable responses and dedicated URLs for each method. This API utilizes OAuth 2.0 for authentication and authorization. It has HTTP verbs and HTTP response codes to provide the integrators and developers the fastest and most secure methods to integrate with our platform. JSON will be returned in all responses from the API, including errors with PayTrace defined error codes.
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 the JSON API is v1.
Here are the steps you will need to follow to start integrating with the PayTrace API.
| 1 | In order to obtain your integrator_id and begin testing your integration, you will need to sign up for a Sandbox Account. To request a sandbox account, fill out the Sandbox Request Form located here: Sandbox Request Form Once completed, your integrator_id and sandbox credentials will be provided to you within 1 business day. |
| 2 | After receiving your sandbox credentials, you will need to configure your account to match your anticipated production account. In order to do so, you will need to login to PayTrace and select the Security Settings tab under the Account Tab. For more information regarding PayTrace’s Security Settings please see the Account Security settings here. |
| 3 | Refer to our API integration documentation provided in this knowledge base to 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 API errors, Check out the PayTrace Virtual Terminal → integration → API log. Look at the API Log for more details.  |
| 7 | Once you are done with your testing phase, you can go live by requesting an active account from the preferred PayTrace Reseller. |
| 8 | To go live, you must have a PayTrace Professional account with the API Module enabled. The aforementioned user credentials can be used in the PayTrace Virtual Terminal to create a PayTrace API user account to use with the API. Please Note: PayTrace uses the API user credentials instead of an API key for Authentication. |
| 9 | Once your integration is complete, we recommend that your users use their API User Account credentials with your integration. |
| 10 | Don't forget to take a look at the PayTrace Virtual Terminal→Account→Security settings(as shown in step 2 above) to configure the additional mandatory parameters for your individual live account. After configuring any additional parameters in the Security Settings, you must also send those additional parameters to avoid API errors. Please look at your Account Security Settings for the API. |
Please Note: If you do not see the Account → Security Settings option in the PayTrace Virtual Terminal, please contact your Account Administrator to enable this Account option in the Virtual Terminal.
Here is the list of all of the Request and Response parameters being used by the JSON API.
| Attribute | Description | Data Type | Length |
|---|---|---|---|
| amount | The 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 in the 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. For Amex cards, the CSC is found on the front of the card. Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. This attribute is only required if the "Required CSC" field is enabled in the PayTrace Virtual Terminal→ Account → Security Settings page. | 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 in the PayTrace Vault to avoid API errors. | string Data Format | 1-25 |
| hpf_token | A one time nonce representing the senstitive credit card data collected by the Protect.js UI. | string | 1-50 |
| enc_key | Unique cipher key provided by the Protect.js UI. | string | 1-50 |
| emv_data | A string of data from a credit card chip provided by the IDTech EMV card reader. This field is also used for FallBack Swipe data in the event that a fallback is triggered. | string | 255+ |
| end_date | The end date is used to indicate when to end searching for transactions to export. It must be a valid date formatted as MM/DD/YYYY. | string | 10 |
| integrator_id | A unique ID to correlate an API consumer calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | string | 12 |
| invoice_id* | A unique identifier for this transaction in your accounting or inventory management system. This attribute is only required if the "Require Invoice" field is enabled in PayTrace Virtual Terminal → Account → Security Settings page. | string Data Format | 1-50 |
| new_password | A new password to be updated. | string Data Format | 7-50 |
| start_date | The start date is used to indicate when to start searching for transactions to export. It must be a valid date formatted as MM/DD/YYYY. | string | 10 |
| swipe or encrypted_swipe | A string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2. Use encrypted_swipe when submitting encrypted swipe values by the PayTrace Client-Side Encryption JavaScript Library. | string Data Format | 255+ |
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: This should be in reference to a legitimate transaction within the PayTrace system, processed in the past to avoid any API errors. | number | 1-9 |
* Request parameters are configurable from the PayTrace Virtual Terminal → Account → Security Settings page. Request parameters must be provided with the request (If request parameters are configured in the PayTrace Virtual Terminal) or API errors will occur.
| Attribute | Description | Data Type | Length |
|---|---|---|---|
| batch_number | A batch number used to find specific batch details. This value is the sequential number assigned to the batch. | number | 1-3 |
| created | Transaction created date or batch created date or customer creation details. For supported Schema, Click here Request_Creation_Record Schema. | object | - |
| custom_dba | An 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 max, alpha-numeric character text describing the transactions, 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 | A flag that must be set to true in order to support partial authorization and balance amounts in transaction responses. PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer. | boolean | - |
| fax | The 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 | The 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 | The customer's shipping address detail. For supported schema, click here Shipping_Address Schema. | object | - |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | 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 that the request was successful and no were no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean | - |
| response_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 |
| emv_details | An array containing details of the EMV transaction. For emv_details supported Schema, Click here emv_details Schema. | array of an object/objects | - |
| 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 | The credit card number with all digits masked and replaced with 'x' except the last 4 digits. This parameter will be returned in the JSON response only when the Credit Card number is one of the request parameters. | string Data Format | 15, 16, 19 |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as what is provided with the request. | string Data Format | 1-25 |
| customers | An array of customer profiles. For Customer profile supported Schema, Click here Customer_Record Schema. | array of an object/objects | - |
| batch | This object contains details about the batch. Note: For the supported Schema, Click here Batch_Record Schema | object | - |
| batches | An array of batch summary records. For the supported Schema, Click here Batch_Summary_Record Schema | array of objects | - |
| recurrence | For the supported Schema, Click here Recurrence_Record Schema. Note: Only the id will be returned on the successful creation of a recurring payment. | object | - |
| recurrences | An array of Recurrence Record objects. This parameter is used with the Export recurring transactions method. For supported Schema, Click here Export_Recurrence_Record Schema. Note: If the Request parameter is a recurrence id, you will get an array of single recurrence transaction records. If the Request parameter is a customer id, you will get an array of one or more transaction records. | array of objects | - |
| transactions | An array of transaction detail records within a batch report. Note: The transaction records will not include discretionary data. For supported Schema, Click here Transaction_Record Schema. An array of transaction detail record objects for the given date range or a single transaction. Note: These transaction details contains discretionary data. For supported Schema, Click here Transaction_Detail_Record Schema | array of objects | - |
| created | Transaction/Batch/Customer record creation details. For supported Schema, Click here Response_Creation_Record Schema. | object | - |
| next_date | The next date when a recurring transaction is scheduled to occur. The 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 | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | 1-12 |
| discretionary_data | Discretionary_data details. For the supported Schema, Click here Discretionary_Data Schema. | object | - |
Here are the Schemas, used by the JSON API
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| number or encrypted_number or masked_number* | The customer's credit card number must be a valid credit card number that your PayTrace account is set up to accept. Use the encrypted_number attribute when submitting encrypted credit card numbers by the PayTrace Client-Side Encryption JavaScript Library Note: masked_number* is a response attribute that is returned with the Export Customer Profile (Vault) and Reporting API methods. | 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 | Name 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 | The 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 PayTrace 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 to be delivered. | string | Optional |
| street_address | Address where the product is to be delivered. | string | Optional |
| street_address2 | The second line of the address where the product is delivered. | string | Optional |
| city | City where the product is to be delivered. | string | Optional |
| state | State where the product is to be delivered. | string | Optional |
| zip | ZIP code where the product is to be 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 originally requested the customer profile or transaction be created or processed. | string |
| at | The date and time when the transaction was first processed or the customer profile was created or batch was initiated/processed. The format will be a general date (i.e. MM/DD/YYYY HH:MM: SS) | string |
| by | The PayTrace username who created the transaction or customer profile you are trying to export. | string |
| from_ip | The IP address of the computer that originally requested the customer profile or transaction be created or processed. The format will be a standard IP address (I.e. 111.111.111.111). | string |
Note:
Please make sure you have discretionary data defined with your merchant account. Check out Discretionary Data for more details.
* Please replace the attribute names with your account-specific discretionary data field names (Titles).
| 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 the supported schema, Click here Credit_Card Schema. | object |
| billing _address | For the supported schema, Click here Billing_Address Schema. | object |
| shipping_address | For the supported schema, Click here shipping_address Schema. | object |
| check | Check the account detail. For the supported Schema, Click here Check Schema. Note: This object will be included ONLY when the customer has check data. | object |
| Customer's email address where the transaction 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 the supported Schema, Click here Response_Creation_Record Schema. | object |
| discretionary_data | Discretionary_data details. For the 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 the supported Schema, Click here Credit_Card Schema. | object |
| transaction_type | The transaction type. 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 | The dollar amount of the transaction. This 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 the supported schema, click here shipping_address Schema. | object |
| billing_address | For the supported Schema, Click here Billing_Address Schema. | object |
| receipt_emailed_to | Customer's email address where the Authorization receipt may be sent. | string |
| tax_amount | A portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string |
| customer_reference_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 | A 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 the current status of the transaction.Possible values that status contains : -GB or Settled indicates the transaction has been settled, and the batch number will be appended to the status. -Y indicates the transaction will be settled that evening. -N indicates the transaction was voided or declined. | string |
| status_message | A short message that shows the 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: This parameter can only be used as a request parameter for some methods. | number |
| american_express | American Express Card details. For the supported schema, Click here Batch_Cards Schema. | object |
| diners_club | For the supported schema, Click here Batch_Cards Schema. | object |
| discover | Discover Card details. For the supported schema, Click here Batch_Cards Schema. | object |
| master_card | Master Card details. For the supported schema, Click here Batch_Cards Schema. | object |
| private_label | For the supported schema, Click here Batch_Cards Schema. | object |
| visa | Visa Card details. For the 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 | The total number of sales (count) that were settled in the exported batch with a specific card type. | number |
| collected | The total sum of the sales amounts that were settled in the exported batch with a specific card type. | number |
| refunds | The total number of refunds(count) that were settled in the exported batch with a specific card type. | number |
| refunded | The total sum of refund amounts that were settled in the exported batch with a specific card type. | number |
| Attribute | Description | Type |
|---|---|---|
| number | A sequential number assigned to the settlement batch. | number |
| created | Batch creation details. Note: Only the at attribute will be returned with a date. For supported schema, click here Response_Creation_Record Schema. | object |
| transaction_count | The 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 | The total number of sales included in a batch. | number |
| sales_amount | The total amount of sales included in a batch. | number |
| refund_count | The total number of refunds included in a batch. | number |
| refund_amount | The 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 the 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 transactions, products, customers, or other attributes of the transaction. | string |
| amount | The dollar amount of the transaction. This 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 the supported schema, Click here shipping_address Schema. | object |
| billing_address | For the supported Schema, Click here Billing_Address Schema. | object |
| receipt_emailed_to | The customer's email address where the Authorization receipt may be sent. | string |
| tax_amount | A 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 the current status of the transaction. The possible values that this status may contain: -GB or Settled indicates the transaction has been settled, and the batch number will be appended to the status. -Y indicates the transaction will be settled that evening. -N indicates the transaction was voided or declined. | string |
| status_message | A short message that shows the 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. The 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 |
id will be the only 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 a successful recurring payment is created, updated or deleted. | number | Required for Update, Delete and Export methods. |
| amount | The dollar amount of the transaction. This 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 the Customer's registered email. false - Default value. Not to send the transaction receipt. true - to send the transaction receipt. Note: Returns an error if the flag is set to true and no email address is registered with the customer profile. | boolean | Required for Create Method Optional for Update Method |
| frequency | The billing cycle of the recurring transaction. Possible values are : 1 - annually 8 - semi-annually A - trimesterly 2 - quarterly 9 - bi-monthly 3 - monthly 4 - bi-weekly 7 - 1st and 15th 5 - weekly 6 - daily. | string | Required for Create Method Optional for Update Method |
| start_date | The date the recurring transaction should be processed for the first time. The 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 transaction. The default value is "C" which represents credit card. The 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 returned when a successful recurring payment is created, updated or deleted. | number |
| amount | The dollar amount of the transaction. This 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 a recurring transaction is scheduled to occur. The 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 the total number of the scheduled payments. The payment will be completed when the current count is equal to the total count unless the total count is set to 999 (infinite). | number |
| repeat_count | The number of the days after a decline that 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 | The checking account number for processing check transactions or managing customer profiles. | number | Required |
| routing_number | The routing number for processing check transactions or managing customer profiles. | number | Required |
| masked_account_number | A masked checking account number for processing check transactions or managing customer profiles. Note: This parameter will be returned with export check transaction requests instead of the plain account number. | string | NA |
| masked_routing_number | A masked Routing number for processing check transactions or managing customer profiles. Note: This parameter will be returned with export check transaction requests instead of the plain routing number | 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: A masked parameter will be used for check account details. | object |
| check_type | The check type. 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 | The dollar amount of the transaction. This 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 the supported schema, click here shipping_address Schema. | object |
| billing_address | For the supported Schema, Click here Billing_Address Schema. | object |
| receipt_emailed_to | The customer's email address where the Authorization receipt may be sent. | string |
| tax_amount | The 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 | The 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 the current status of the transaction. Possible values this status may contain: -GB or Settled indicates the transaction has been settled, and the batch number will be appended to the status. -Y indicates the transaction will be settled that evening. -N indicates the transaction was voided or declined. | string |
| created | Transaction creation details. For the 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 the supported Schema, Click here Discretionary_Data Schema. | object |
| Attribute | Description | Type |
|---|---|---|
| AID | EMV Tag data provided by EMV Reader | string |
| TVR | EMV Tag data provided by EMV Reader | string |
| IAD | EMV Tag data provided by EMV Reader | string |
| TSI | EMV Tag data provided by EMV Reader | string |
| ARC | EMV Tag data provided by EMV Reader | string |
"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", } }
"emv_details":{ "AID":"A0000000031010", "TVR":"8000000000", "IAD":"06010A03A0B000", "TSI":"6800", "ARC":"00" }
The following sample code is available in 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 of the requests. The PayTrace JSON API uses OAuth 2.0 for Authentication and Authorization.
OAuth 2.0 provides a "password" grant type that can be used to exchange a username and password for an access token directly. If you decide not to use any of the 3rd party OAuth 2. 0 libraries, the following steps are needed :
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 an 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 |
The error responses will include an HTTP status code and JSON body. In general, code 4XX and 5XX ranges indicate some failure for an authentication token request.
Specific JSON error responses will be returned to provide authentication error details. Here is the Authentication error Response attributes detail. Check out API Errors for HTTP status codes.
| Attribute | Description | Type |
|---|---|---|
| error | A unique identifier for an error. Please refer to Authentication Errors Summary to find all values. | string |
| error_description | An error message providing details about the error. Please refer to Authentication Errors Summary to find 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, the appropriate error message will be returned. -The access token was revoked. -The access token expired. -The access token is invalid. |
| unsupported_grant_type | The authorization grant type is not supported by the authorization server. |
| invalid_resource_owner | The provided resource owner credentials are not valid, or resource owner cannot be found. |
| invalid_request | The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed. |
| invalid_client | Client authentication failed due to an unknown client, no client authentication included, or unsupported authentication method. |
| access_denied | The resource owner or authorization server denied the request. |
| invalid_scope | The requested scope is invalid, unknown, or malformed. |
| server_error | The authorization server encountered an unexpected condition which prevented it from fulfilling the request. |
| temporarily_unavailable | The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
For example, If you pass incorrect API user credentials, you will get an error Response with the appropriate error and error description with an HTTP status code 401-unauthorized.
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
The 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
}The 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. |
| 165 | Your transaction was successfully approved and customer profile is created. | Returned when the request to process a sale transaction generates an approved transaction and customer profile is created. |
| 167 | Your transaction was successfully approved. However, the requested customer profile could not be created. | Returned when the request to process a sale transaction generates an approved transaction, however the requested customer profile already exists and thus could not be created. |
| 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"
}The additional errors object will be included when an input parameter is missing or invalid.
Here are the API error codes and associated messages with possible scenarios.
| 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 validated before being saved or used. By default, all accounts are able to process Visa, MasterCard, and Diner's Club cards. Accounts must be set up to accept American Express, Discover, and JCB cards in order for PayTrace to accept them. |
| 40 | An error occurred during the decryption process. | PayTrace supports encrypted card readers. This error is returned if an error occurs during the decryption process. |
| 43 | Please provide a valid Expiration Month. | All transactions and customer profiles must have a 2 digit expiration month. |
| 44 | Please provide a valid Expiration Year. | All transactions and customer profiles must have a 2 digit expiration year. |
| 45 | Please provide a valid Checking Account Number. | Required if creating a customer without a card number or processing a check transaction. |
| 46 | Please provide a valid Transit Routing Number. | Required if creating a customer without a card number or processing a check transaction. |
| 47 | Please provide an Amount that is less than your Sale Ceiling Amount. | All sales, authorizations, and forced sales must have a valid numeric amount that is less than your sale ceiling amount. |
| 48 | Please provide an Amount that is less than your Refund Ceiling Amount. | All refunds must have a valid numeric amount that is less than your refund ceiling amount. |
| 51 | Please provide a valid Amount. | All transactions must have a valid numeric amount. |
| 53 | Capture Amount can not exceed 30% of the original authorized amount. | All transactions must have a valid numeric amount. |
| 54 | Cash Advances may only be processed as Sales. | Cash Advances must be processed as Sale transaction types. It only applies if ProcessTranx request includes CASHADVANCE~Y| parameter. |
| 55 | Cash Advances may only be processed through accounts set up in the TSYS/Vital network. | Cash Advances may only be processed if your merchant account is set up on the TSYS network. It only applies if ProcessTranx request includes CASHADVANCE~Y| parameter. |
| 56 | Cash Advances may not be processed to stored customers. | Cash advance transactions must be processed as face to face transactions. |
| 57 | Your PayTrace account is not set up to process Cash Advances. | In order to process Cash Advances, your PayTrace account must be configured to accept this type of payment. |
| 58 | Please provide a valid Transaction ID. | Void, capture, add level 3 data, and email receipt requests require a transaction ID that references a transaction in PayTrace's system. |
| 59 | Please provide a valid Check ID. | Manage Check and email receipt requests require a check ID that references a check-in PayTrace's system. |
| 61 | The Customer ID that you provided was not found in the PayTrace records. | If a transaction is to be referenced to a stored customer profile, a valid customer ID must be provided. |
| 62 | Please provide a valid Photo ID. | Cash Advance requests require a photo ID to be provided. |
| 63 | Please provide a valid ID Expiration. | Cash Advance requests require an ID expiration date to be provided. |
| 64 | Please provide a valid Last 4 of Card. | Cash Advance requests require the last 4 digits of the card number to be provided. |
| 65 | Cash Advances may only be processed on Visa, MasterCard, and Discover cards. | Cash Advance transactions are only permitted on Visa, MasterCard, and Discover cards. |
| 80 | The Check ID that you provided was not found in the PayTrace records. It may already be voided or settled. | Only pending and held checks may be managed. |
| 81 | The Transaction ID that you provided was not found in the PayTrace records. It may be a previously voided transaction or an unsettled transaction. | Only settled sales transactions may be refunded with a transaction ID. |
| 82 | Please provide a valid Batch Number. | If a batch number is present in an ExportBatch request, it must be a numeric value between 1 and 999. |
| 83 | This is not an approved transaction so it can not be captured. | Only approved authorizations may be captured. |
| 84 | This transaction's approval code has expired as it was obtained more than 20 days ago. | Transactions must be captured within 20 days of authorization. |
| 85 | The Transaction ID that you provided was not found in the PayTrace records. It may already be captured or settled. | Only approved authorizations that are currently not pending settlement may be captured. |
| 86 | The Transaction ID that you provided was not found in the PayTrace records. It may already be voided, settled, or an uncaptured authorization. | Only approved sales, authorizations, and refunds that have not been settlement may be voided. A declined sale, a settled sale or a refunded sale may not be voided. |
| 87 | The Transaction ID that you provided was not found in the PayTrace records, and the receipt could not be emailed. | Only receipts with valid transaction IDs will be emailed. |
| 88 | The Transaction ID that you provided was not found in the PayTrace records, and level 3 data could not be added to the Visa transaction. | Only Visa sales that are currently pending settlement will have level 3 data added to them. |
| 89 | The Transaction ID that you provided was not found in the PayTrace records, and level 3 data could not be added to the MasterCard transaction. | Only MasterCard sales that are currently pending settlement will have level 3 data added to them. |
| 90 | The Transaction ID that you provided was not found in the PayTrace records, and the amount was not updated. | Only merchants using TSYS/Vital may update transaction amounts on non-Cash Advance transactions. Sales must be approved and pending settlement, refunds must be pending settlement, authorizations must be approved and unsettled, and forced sales must be pending settlement in order for their amounts to be updated to an amount less than or equal to the original transaction amount. |
| 110 | Please provide a valid value for Discretionary Title | Discretionary Data values must match the criteria that are specified in the Virtual Terminal. "Discretionary Title" in the response message is replaced with the actual title of the discretionary data element that needs an appropriate value. |
| 114 | Please provide a valid Store & Forward Date. | Store & Forward transactions may be submitted with optional scheduled processing dates. |
| 115 | Please provide a valid Approval Code. | Forced sales must be processed with valid approval codes. |
| 116 | Please provide a valid Transaction Type. | Only valid transaction types are accepted, and all requests to ProcessTranx require a transaction type. |
| 117 | Please provide a valid Billing Name. | Optional field for transactions and customers that must have the correct format. |
| 118 | Please provide a valid Billing Address. | Optional field for transactions and customers that must have the correct format. May be required if configured in your security settings. |
| 119 | Please provide a valid Billing Address 2. | Optional field for transactions and customers that must have the correct format. |
| 120 | Please provide a valid Billing City. | Optional field for transactions and customers that must have the correct format. |
| 121 | Please provide a valid Billing State. | Optional field for transactions and customers that must have the correct format. |
| 122 | Please provide a valid Billing Zip Code. | Optional field for transactions and customers that must have the correct format. May be required if configured in your security settings. |
| 123 | Please provide a valid Billing Country. | Optional field for transactions and customers that must have the correct format. |
| 124 | Please provide a valid Shipping Name. | Optional field for transactions and customers that must have the correct format. |
| 125 | Please provide a valid Shipping Address. | Optional field for transactions and customers that must have the correct format. |
| 126 | Please provide a valid Shipping Address 2. | Optional field for transactions and customers that must have the correct format. |
| 127 | Please provide a valid Shipping City. | Optional field for transactions and customers that must have the correct format. |
| 128 | Please provide a valid Shipping County. | Optional field for transactions and customers that must have the correct format. |
| 129 | Please provide a valid Shipping State. | Optional field for transactions and customers that must have the correct format. |
| 130 | Please provide a valid Shipping Zip Code. | Optional field for transactions and customers that must have the correct format. |
| 131 | Please provide a valid Shipping Country | Optional field for transactions and customers that must have the correct format. |
| 132 | Please provide a valid Phone Number. | Optional field for transactions and customers that must have the correct format. |
| 133 | Please provide a valid Source State. | Required for calculating shipping requests. |
| 134 | Please provide a valid Source Zip Code. | Required for calculating shipping requests. |
| 135 | Please provide a valid list of Shippers. | Required for calculating shipping requests. |
| 136 | Please provide a valid Weight. | Required for calculating shipping requests. |
| 137 | Please provide a valid Fax Number. | Optional field for transactions and customers that must have the correct format. |
| 139 | Please make sure the Shipping State and Shipping Zip are accurate. | Returned if errors are returned from the shipping provider(s) during the calculation of the shipping request. |
| 140 | … | Dynamic error(s) returned from shipping provider(s) may be returned from CalculateShipping requests. |
| 141 | Please provide a valid Email Address. | Optional field for transactions and customers that must have the correct format. Required to email a receipt. |
| 148 | Please provide a valid CSC. | Optional field for transactions that must have the correct format. May be required if configured in your security settings. |
| 149 | Please provide a valid Invoice Number. | Optional field for transactions and that must have the correct format. |
| 150 | Please provide a valid Description. | Optional field for transactions and that must have the correct format. |
| 151 | Please provide a valid Tax Amount. | Optional field for transactions and that must have the correct format. |
| 152 | Please provide a valid Customer Reference. | Optional field for transactions and that must have the correct format. |
| 153 | This customer profile does not have an email address to send the receipt. | A customer profile must have an email address in order for the recurring receipts to be emailed to the customer. |
| 160 | Please provide a valid Frequency. | A frequency is required to create a recurring payment. |
| 161 | Please provide a valid Transaction Count. | A transaction count is required to create a recurring payment. |
| 162 | Please provide a valid Start Date. | The start date is required to create a recurring payment. |
| 163 | Please provide a valid Next Date. | The next date is required to create a recurring payment. |
| 164 | Please provide a valid Repeat value. | An optional repeat value may be sent for recurring payments. |
| 165 | Please provide a valid Recurring Payment ID. | A recurring payment ID is required to update a recurring payment. |
| 169 | No recurring payments were found with this criteria. | Export recurring payments request returned no results. |
| 170 | No approved transactions were found for this customer. | Export recurring payment request returned no results. |
| 171 | Please provide a unique customer ID. | Each request to create a customer must contain a unique customer ID. |
| 172 | Please provide a Customer Password that is greater than 6 characters and less than 255 characters. | If you have access to the PayTrace shopping cart, you must provide a password when creating a customer. |
| 175 | Please provide a valid Start Date. | The start date for exporting transaction reports. |
| 176 | Please provide a valid End Date. | End date for exporting transaction reports. |
| 177 | Please provide a date range. | The end date must be passed/greater than the start date. |
| 178 | Please provide a valid User. | The user account for exporting transaction reports. |
| 179 | Please provide a valid number of Days. | The number of days value will need to be between 1 and 999 in the request. |
| 180 | No transactions were found with these criteria. | Export transactions request returned no results. |
| 185 | No customers were found with these criteria. | Export customers request returned no results. |
| 190 | Please provide a valid National Tax Amount. | Optional field for level 3 data that must have the correct format. |
| 191 | Please provide a valid Merchant Tax ID. | Optional field for level 3 data that must have the correct format. |
| 192 | Please provide a valid Customer Tax ID. | Optional field for level 3 data that must have the correct format. |
| 193 | Please provide a valid Commodity Code. | Optional field for level 3 data that must have the correct format. |
| 194 | Please provide a valid Discount Amount. | Optional field for level 3 data that must have the correct format. |
| 195 | Please provide a valid Freight Amount. | Optional field for level 3 data that must have the correct format. |
| 196 | Please provide a valid Duty Amount. | Optional field for level 3 data that must have the correct format. |
| 197 | Please provide a valid Additional Tax Amount. | Optional field for level 3 data that must have the correct format. |
| 198 | Please provide a valid Additional Tax Rate. | Optional field for level 3 data that must have the correct format. |
| 199 | Please provide a valid Additional Tax Indicator. | Optional field for level 3 data that must have the correct format. |
| 200 | Please provide a valid Line Item record. | A required field for level 3 data that must have the correct format. |
| 201 | Please provide a valid Line Item Commodity Code. | Optional field for level 3 data that must have the correct format. |
| 202 | Please provide a valid Line Item Description. | Optional field for level 3 data that must have the correct format. |
| 203 | Please provide a valid Line Item Product ID. | Optional field for level 3 data that must have the correct format. |
| 204 | Please provide a valid Line Item Quantity. | Optional field for level 3 data that must have the correct format. |
| 205 | Please provide a valid Line Item Measure. | Optional field for level 3 data that must have the correct format. |
| 206 | Please provide a valid Line Item Unit Cost. | Optional field for level 3 data that must have the correct format. |
| 207 | Please provide a valid Line Item Additional Tax Amount. | Optional field for level 3 data that must have the correct format. |
| 208 | Please provide a valid Line Item Additional Tax Rate. | Optional field for level 3 data that must have the correct format. |
| 209 | Please provide a valid Line Item Discount. | Optional field for level 3 data that must have the correct format. |
| 210 | Please provide a valid Line Item Amount. | Optional field for level 3 data that must have the correct format. |
| 211 | Please provide a valid Line Item Additional Tax Indicator. | Optional field for level 3 data that must have the correct format. |
| 212 | Please provide a valid Line Item Discount Rate. | Optional field for level 3 data that must have the correct format. |
| 213 | Please provide a valid Line Item Discount Indicator. | Optional field for level 3 data that must have the correct format. |
| 214 | Please provide a valid Line Item Net Gross Indicator. | Optional field for level 3 data that must have the correct format. |
| 215 | Please provide a valid Line Item Debit Credit Indicator. | Optional field for level 3 data that must have the correct format. |
| 230 | Batch was not initiated as no transactions are pending settlement. | Returned if request to SettleTranx is sent when no transactions may be settled. |
| 231 | Batch was not initiated as another batch is in progress or pending. | Returned if request to SettleTranx is sent when another batch is being settled or the last batch is pending any settlement problems. |
| 300 | Invalid Chip Read. Please reinsert card. | Returned if Card reader had technical issues reading the card. Reattempt the transaction by reinserting the chip into the reader. |
| 301 | Invalid Chip attempts exceeded. Please attempt swipe. | Returned after 3 consecutive invalid card reads prompting a Fallback. Reattempt transaction by Swiping card. |
| 302 | Empty Candidate. Please attempt swipe. | Returned if card reader had technical issues reading card prompting a Fallback. Reattempt transaction by Swiping card. |
| 303 | Card reader error. Please reinsert card. | Returned if card reader had technical issues reading card prompting a Fallback. Reattempt transaction by Swiping card. |
| 335 | Chip data Corrupted. | Returned if EMV chip encryption fails or if the card is read incorrectly. |
| 370 | The transaction has been terminated by the reader, please try again. | Returned if Card reader terminates the transaction for reasons other than prompting a Fallback. Reattempt the transaction by reinserting the chip into the reader. |
| 700 | This transaction was not approved because the authorization network was not available. Please retry this transaction again. | If a response is not returned to PayTrace from the issuing bank within 30 seconds, then a response is returned through the API advising of the authorization network being unavailable. |
| 710 | Dynamic response from the processing network | If a void request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 711 | Dynamic response from the processing network | If a capture request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 712 | Dynamic response from the processing network | If a refund request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 713 | Dynamic response from the processing network | If a forced sale request is unsuccessfully processed by the processing network, this error response will contain the message returned from the processor. |
| 740 | PayTrace is unable to process this check as the check processor information is incomplete or the network returned an error. | In the event that you receive this error message, please contact PayTrace Support to determine if some of the check processor information on your account is incomplete. |
| 750 | PayTrace does not support this transaction type for this check processor. | Specific check processors only support certain transaction types. For example, Paya only supports sale requests and some instances of void requests. If a request is sent w/ a transaction type that is not supported by the check processor enabled on the PayTrace account, this error is returned. |
| 777 | PayTrace blocked this transaction because it is a duplicate, and it may be reprocessed in ### minute(s). | cell-content |
| 778 | PayTrace blocked this transaction because it exceeded the specified velocity filter. | PayTrace compares requests to process new transactions against specified velocity filters when velocity filters are established on specific PayTrace accounts. For more information about velocity filters, contact PayTrace Support. |
| 779 | BLOCKED - This card number has been blocked to prevent potential fraud. | This occurs when 4 consecutive not-approved transactions are processed within a 24-hour time frame to the same card number. Voided transactions within the same 24-hour period count towards this. |
| 811 | The Transaction ID that you provided was not found. | The transaction ID isn't found on the account. |
| 812 | The Transaction ID that you provided was found but was not processed by you | Transaction ID exists on this account but the user only has permission to view their own transactions and this transaction was processed by another user. |
| 813 | The Transaction ID that you provided was found but the card type is not supported. | Transaction ID exists but the card number is corrupt or is no longer supported. |
| 816 | The Transaction ID that you provided could not be captured. Only uncaptured, approved authorizations can be captured. | Transaction ID exists but its status can't be captured. |
| 817 | The Transaction ID that you provided could not be refunded. Only settled transactions can be refunded. Please try to void the transaction instead. | Transaction ID exists but its status can't be refunded. |
| 818 | The Transaction ID that you provided could not be voided. Only transactions that are pending settlement or uncaptured authorizations can be voided. | Transaction ID exists but its status can't be voided. |
| 819 | Refund amount can not exceed the original settled amount. Previous refunds against this transaction count towards the original transaction amount. | Total refund amount, including all previous attempts, is larger than the Transaction's settlement amount. |
| 867 | Please provide valid new passwords. | Passwords must be provided when processing a request to change your password. |
| 869 | Please provide new passwords that are unique to your previous 4 passwords. | New passwords must be unique to your 4 previous passwords. |
| 880 | This customer is scheduled for recurring payment # xxxxx and may not be deleted. | Customers with pending recurring payments may not be deleted. |
| 900 | Please indicate that you agree with PayTrace's terms and conditions. | The TERMS parameter must be set to Y. |
| 950 | Unreferenced refunds are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept refunds to be processed without referencing the previously processed transaction's ID. |
| 951 | Forced Sales are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept forced sales to be processed. |
| 952 | Swiped/card present transactions are not permitted for Optimal Payments accounts. | This error only applies to merchants using Optimal Payments. Optimal Payments does not accept card present transactions. |
| 961 | No payment fields found with the provided token. | Returned when Protect Tokenized data is not found within the PayTrace system or Provided Token or enc_key is corrupted. |
| 970 | param is missing or the value is empty: value | Returned when required Protect.js or EMV parameters are not provided within the API request or if they have empty values. |
| 971 | Please provide a valid integrator_id. | Returned when Integrator Id is not provided or when Provided Integrator Id is not registered with PayTrace. |
| 973 | The processor information for xxxxxx is incomplete. | An incomplete PayTrace account is not able to process requests. |
| 974 | Your PayTrace account is not set up to use the 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 receipts, export transactions, and update password requests. |
| 977 | Your PayTrace account is not set up to process EMV transactions. | EMV transactions may only be processed by accounts that are set up to process EMV transactions. Please contact PayTrace or your reseller for more information. |
| 978 | Your account is not set up to process checks. | Check transactions may only be processed by accounts that are set up to process Check transactions. Please contact PayTrace or your reseller for more information. |
| 979 | Password is expired. Please log in to the virtual terminal to reset the password. | Passwords must be changed at least once every 90 days. Reminders are emailed 14, 7, 1, and 0 days before the password expires. |
| 980 | Log in failed for insufficient permissions. | The user account must have permission/access to process an authorization. |
| 981 | Log in failed for insufficient permissions. | The user account must have permission/access to process a refund. |
| 982 | Log in failed for insufficient permissions. | The user account must have permission/access to process a void. |
| 983 | Log in failed for insufficient permissions. | The user account must have permission/access to process a capture. |
| 984 | Log in failed for insufficient permissions. | The user account must have permission/access to process a forced sale. |
| 985 | Log in failed for insufficient permissions. | The user account must have permission/access to create, update, or delete customers. |
| 986 | Log in failed for insufficient permissions. | The user account must have permission/access to create, update, or export a recurring payment. |
| 987 | Please provide a valid method or request to process. | Only valid methods are accepted for processing through the API. |
| 988 | Log in failed. | An unsuccessful login attempt occurred because of an IP rule conflict. |
| 989 | Log in failed for insufficient permissions. | The user account must have permission/access to export transactions. |
| 990 | Please provide properly formatted parameters. | The API request is not properly formatted as a JSON format. |
| 993 | xxxxxx is not a valid parameter name. | An invalid parameter was included in the request. Some parameters are case sensitive. For example: number as "NUMBER" , 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 login attempt occurred. With either of the following reasons. 1. The account is disabled. 2. Four consecutive unsuccessful log in attempts will disable a user's account. |
| 999 | Log in failed for insufficient permissions. | The user account must have permission/access to process a sale. |
| 1001 | Decryption failed. | Encrypted request data should be encrypted with the merchant account-specific public key only. |
| 9102-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:
The following test data can be used to test while in your sandbox environment. Note, using this data in a live environment will only result in declines.
| Credit Card Type | Credit Card Number | *Expiration MM/YY |
|---|---|---|
| Visa | 4012000098765439 | 12/24 |
| MasterCard | 5499740000000057 | 12/24 |
| Discover | 6011000993026909 | 12/24 |
| American Express | 371449635392376 | 12/24 |
*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 |
To receive notifications whenever PayTrace creates an incident, updates an incident, resolves an incident or changes a component status, sign up for our Status Page. Notifications are available via webhook, text and email.
To stay up to date with PayTrace product updates & features, webinar schedules & registration, payment industry jib jab, plus random contributions of PayTracer culture, talent, and in-house happenings, we encourage you to subscribe to our Blog.
The PayTrace Encryption Library supports client-side encryption of sensitive data, reduces merchant's and integrator's exposure to PCI-compliance verification. Sensitive data can be encrypted at the user's web browser using The PayTrace JavaScript Encryption Library. The encrypted data can only be decrypted by PayTrace. The merchant or the integrator has no access to the original sensitive data.
The sensitive data is encrypted before the web form is submitted and until it is received at PayTrace's secure server. The RSA public/private key pair is used to encrypt sensitive credit card data. The public key corresponds to your PayTrace account and it will be used to encrypt the sensitive data. Only PayTrace can decrypt the encrypted data with the private key.
The following steps are required to utilize The PayTrace Client-Side Encryption Library in a web form.
A public key, as described above, must be completed before moving forward.
Please refer to 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 the encrypted values using the name attribute on the server. Please refer to 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 →
Once you have received the encrypted values, you will then submit them using an API Request. In order to prompt the API to accept the encrypted values, you will need to prepend encrypted_ to the Number and CSC parameters within the request.
For example, the credit card number will be encrypted_number, the CSC will be encrypted_csc and the swipe will be encrypted_swipe to send the encrypted values to the API.
Please refer to the Keyed Sale request using the encrypted_number and the encrypted_csc in the code section.
<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"
}
}*The above sample request contains only the minimum parameters that are required.
The following response will be returned with a HTTP Status 400 Bad Request.
{
"success":false,
"response_code":1001,
"status_message":"Decryption failed."
}In today’s world, security and PCI compliance play important roles in protecting cardholders and delivering cash flow for businesses.
Protect.js uses an iframe to create PayTrace hosted fields when collecting sensitive-payment information. This allows you to control the UI and UX of your checkout process so that cardholder data never touches your servers.
You can quickly start accepting secure payments and storing cardholders’ payment information by embedding a few lines of code within your existing checkout flow. While achieving the highest level of PCI-Compliance, SAQ-A.
Protect.js places PayTrace Hosted Payment fields, within an iframe, on your webform. This will allow your customers to enter their sensitive credit card information directly into PayTrace while ensuring your server does not handle any sensitive data. Once this information has been captured, Protect.js will then return a one time use hpf_token (nonce) and enc_key. The nonce and enc_key can then be submitted via an API request in order to process transactions or create customer profiles.
The following steps are required to utilize The PayTrace Protect.js Library in a web form.
Please refer to the code section Sample →
This step allows the PTPayment object to become available when the Protect library script is sourced in the web application. See available PTPayment methods below:
| Method | Description |
|---|---|
| process | Validates and tokenizes Hosted Payment Field Data |
| setup | Initializes the Protect.js Hosted Payment Fields within iframe using the clientkey in step 3. Styling options can be statically applied during the setup call. For more information regarding our styling options, see Styling Options. |
| validate | Validates Hosted Payment Field input prior to tokenizing data. Takes function as an arguement. See example 5.1 |
| reset | Clears Hosted Payment Fields and resets Protect.js to its beginning state. |
Make OAuth authorization call to the JSON API to get an API AUTH TOKEN. This token will be used as the authorization bearer access token to authorize the application to use PayTrace's API. The token should be kept secret and should never be added to client side code. This token is valid for 2 hours.
See Authentication for a reference on how to generate an Oauth Token.
Using the API AUTH TOKEN from step two as the authorization header, make a JSON API POST request to: https://api.paytrace.com/v1/payment_fields/token/create to get a PROTECT AUTH TOKEN (clientKey).
The clientkey will be used to authorize the application to use Protect.js. This key is valid for 20 minutes.
Please refer to the code section for request and response samples→
Please refer to the code section for Sample→
By this point, you should be able to see the Protect.js iframe rendered on your webpage. See example below:
To improve the look and feel of Protect.js, styling options can be statically applied during the setup call. For more information regarding our Styling option, see Protect.js Styling.
The process method will tokenize the sensitive data in the payment fields. The method returns a http promise that will either be fulfilled (resolved) or rejected. If it is rejected, the possible reasons are: network error, internal error, or the fields did not pass validation.
PTPayment.validate will validate the payment fields and allow you to re-prompt your customers to enter valid information.
Dynamic styling can then be used to better control your customer experience when invalid input is entered. For more information regarding our Styling options, see Styling Options.
For a list of potential validation errors, see Validation Error Responses below.
Please refer to the code section for Sample→
The tokenization process also validates the sensitive data payment fields
Dynamic styling can then be used within the error handling to better control your customer experience when invalid input is entered. For more information regarding our Styling options, see Styling Options.
For a list of potential validation errors, see Validation Error Responses below.
Please refer to the code section for Sample→
If for any reason the users input fails the Protect.js validation, the appropriate Response code will be returned in the error response.
| Response Code | Description | Reason |
|---|---|---|
| 35 | Please provide a valid Credit Card Number. | The Credit card Number was invalid or not provided. |
| 43 | Please provide a valid Expiration Month. | The expiration Month was invalid or not provided. |
| 44 | Please provide a valid Expiration Year. | The expiration Year was invalid or not provided. |
| 148 | Please provide a valid CSC. Must be 3 to 4 digits. | The CSC/CVV value was invalid. |
| 400 | Varies based on validation error | In the case that an error occurs in which a general use case is not covered, this response code will be thrown with a description indicating the field that it detected a problem with. |
Once you have received the hpf_token (nonce) and enc_key, you will then submit these values using an API Request and the Oauth token from Step 2. API methods that are meant to be used with the Protect.js UI are listed within their appropriate request categories and begin with the keyword Protect.
| Method | Description |
|---|---|
| Protect Sale | Processes a Sale transaction using the Protect.js UI. |
| Protect Sale and Create Customer | Processes a Sale transaction and creates a customer profile, upon transaction approval, using the Protect.js UI. |
| Protect Authorization | Processes an Authorization using the Protect.js UI. |
| Create Customer Profile Using Protect.js | Stores your customer's billing and payment information, in PayTrace's PCI-compliant Customer Database (Vault), using the Protect.js UI. |
| Update Customer Profile Using Protect.js | Modifies an existing customer profile, stored in PayTrace's PCI-compliant Customer Database (Vault), using the Protect.js UI. |
<!-- This is the PayTrace Protect.js library: -->
<script src='https://protect.paytrace.com/js/protect.min.js'></script>
<!-- The JS Library then adds the iframe using this div container tag during setup -->
<div id='pt_hpf_form'><!--iframe sensitive data payment fields inserted here--></div>
grant_type=password&username=YourUserName&password=YourPassword
POST
URL='https://api.paytrace.com/v1/payment_fields/token/create'
Content-Type: application/json
Authorization: Bearer "Auth Token in Step 2"
<script>
// Minimal Protect.js setup call
PTPayment.setup({
authorization: { clientKey: <clientKey> }
}).then(function(instance){
//use instance object to process and tokenize sensitive data payment fields.
});
</script>
// this can be any event we chose. We will use the submit event and stop any default event handling and prevent event handling bubbling.
document.getElementById("ProtectForm").addEventListener("submit",function(e){
e.preventDefault();
e.stopPropagation();
// To trigger the validation of sensitive data payment fields within the iframe before calling the tokenization process:
PTPayment.validate(function(validationErrors) {
if (validationErrors.length >= 1) {
if (validationErrors[0]['responseCode'] == '35') {
// Handle validation Errors here
// This is an example of using dynamic styling to show the Credit card number entered is invalid
PTPayment.style({'cc': {'border_color': 'red'}});
}
} else {
// no error so tokenize
instance.process()
.then( (r) => submitPayment(r) )
.catch( (err) => handleError(err) );
}
});// end of PTPayment.validate
});// end of add event listener submit
OR
// this can be any event we chose. We will use the submit event and stop any default event handling and prevent event handling bubbling.
document.getElementById("ProtectForm").addEventListener("submit",function(e){
e.preventDefault();
e.stopPropagation();
// The tokenization process also validates the sensitive data payment fields
PTPayment.process() //call tokenization
.then( (r) => submitPayment(r) )
// submit nonce and cipher key to PayTrace Protect Servers to tokenize sensitive data payment fields
.catch( (err) => handleError(err) );
// handle unsuccessful tokenization failures
});// end of add event listener submit
{
"success": true,
"message": {
"hpf_token": "f519084b-db08-4e82-8670-9e690d9897cc",
"enc_key": "84jkunZs5Ae4_tNaW3QtIIjaE08wyg70oJfA-gtm6aY="
}
}
{
"message": "Field Validation Error(s)",
"reason": [
{ "description": "Please provide a valid Credit Card Number.", "responseCode": "35" },
{ "description": "Please provide a valid Expiration Month.", "responseCode": "43" }
]
}
Protect.js allows you to style the Hosted Payment Fields to best fit your website. Styling can be applied either statically, during the setup method call, or dynamically during runtime.
The following options are available during the Protect.js setup phase.
Please refer to the code section for an example of Static Styling
| Field | Description |
|---|---|
| code | CSC Input field |
| cc | Credit card number input field |
| exp | Expiration date Input field |
| body | Body of the iframe NOTE: Only background_color can be modified |
| Option | Description | Acceptable Values |
|---|---|---|
| background_color | Background color of the text box or iframe | CSS keyword or hexadecimal color value Default color is 'white' |
| border_color | Color of textbox border | CSS keyword or hexadecimal color value Default color is 'black' |
| border_style | Border style of the text box | CSS keyword Default style is 'solid' |
| font_color | Font color of input data | CSS keyword or hexadecimal color value Default color is 'black' |
| font_size | Font size of input data | CSS units |
| height | Height of text box | CSS units Will default to font_size if not provided |
| input_border_radius (New) | Border radius of text box | CSS units |
| input_border_width (New) | Border width of text box | CSS units |
| input_font (New) | Font of input data | CSS keyword Can include several font names for fallback options |
| input_font_weight (New) | Font weight of input data | CSS keyword or font-weight value Default font-weight is 'normal' or 400 |
| input_margin (New) | Margin around text box border | CSS units (top, right, bottom, left) |
| input_padding (New) | Padding between input data and text box border | CSS units (top, right, bottom, left) |
| label_border_color (New) | Border color around payment field label | CSS keyword or hexadecimal color value Default color is 'black' |
| label_border_radius (New) | Border radius around payment field label | CSS units |
| label_border_style (New) | Border style around payment field label | CSS keyword Default style is 'solid' |
| label_border_width (New) | Border width around payment field label | CSS units |
| label_color | Color of payment field label | CSS keyword or hexadecimal color value Default color is 'black' |
| label_font (New) | Font of payment field label | CSS keyword Can include several font names for fallback options |
| label_font_weight (New) | Font weight of payment field label | CSS keyword or font-weight value Default font-weight is 'normal' or 400 |
| label_margin (New) | Margin around payment field label border | CSS units (top, right, bottom, left) |
| label_padding (New) | Padding between payment field label and payment field label border | CSS units (top, right, bottom, left) |
| label_size | Size of payment field label | CSS units |
| label_width (New) | Width of payment field label | CSS units |
| padding_bottom (New) | Padding added below input text box | CSS units |
| type | Payment field input boxes can be defined as text or a dropdown NOTE: Only available for Expiration Month and Year sensitive data field input boxes | 'dropdown' or 'textbox' Default type is 'dropdown' |
| width | Width of text box | CSS units |
The following PTPayment methods can be used to style the Project.js Payment fields during runtime. To utilize these methods, you will need to implement them within the .then method once the promise has resolved.
Please refer to the code section for examples of dynamic Styling
| Method | Description |
|---|---|
| style | Allows you to modify any of the input field styling options. |
| theme | Allows you to adjust where the labels are displayed around the payment field input boxes. Available Options: 'above the line', 'horizontal', 'below the line', 'label-extended-top'(New) or 'label-none'(New) The default theme is 'above the line' if a theme is not defined. Labels will be right justified against the input fields with the 'horizontal' theme. The 'label-extended-top' theme places the security code on its own line below the expiration date. The 'label-none' theme removes the labels completely and only displays the input boxes. NOTE: May require you to adjust the size of the div container via CSS. |
| getControl | Allows you to customize the label text for the input fields The default labels are CC Number, Expiration and Security Code if custom labels are not defined. The control types are: securityCode, creditCard, expiration. |
PTPayment.setup({ styles: { 'code': { 'font_color':'#5D99CA', 'border_color':'#EF9F6D', 'border_style':'dotted', 'font_size':'13pt', 'input_border_radius':'10px', 'input_border_width':'2px', 'input_font':'serif, cursive, fantasy', 'input_font_weight':'700', 'input_margin':'5px 0px 5px 20px', 'input_padding':'0px 5px 0px 5px', 'label_color':'#5D99CA', 'label_size':'16px', 'label_width':'150px', 'label_font':'sans-serif, arial, serif', 'label_font_weight':'bold', 'label_margin':'5px 0px 0px 20px', 'label_padding':'2px 5px 2px 5px', 'label_border_style':'dotted', 'label_border_color':'#EF9F6D', 'label_border_radius':'10px', 'label_border_width':'2px', 'background_color':'white', 'height':'25px', 'width':'110px', 'padding_bottom':'2px' }, 'cc': { 'font_color':'#5D99CA', 'border_color':'#EF9F6D', 'border_style':'solid', 'font_size':'13pt', 'input_border_radius':'20px', 'input_border_width':'2px', 'input_font':'Times New Roman, arial, fantasy', 'input_font_weight':'400', 'input_margin':'5px 0px 5px 0px', 'input_padding':'0px 5px 0px 5px', 'label_color':'#5D99CA', 'label_size':'16px', 'label_width':'150px', 'label_font':'Times New Roman, sans-serif, serif', 'label_font_weight':'light', 'label_margin':'5px 0px 0px 0px', 'label_padding':'0px 5px 0px 5px', 'label_border_style':'solid', 'label_border_color':'#EF9F6D', 'label_border_radius':'20px', 'label_border_width':'2px', 'background_color':'white', 'height':'25px', 'width':'320px', 'padding_bottom':'0px' }, 'exp': { 'font_color':'#5D99CA', 'border_color':'#EF9F6D', 'border_style':'dashed', 'font_size':'12pt', 'input_border_radius':'0px', 'input_border_width':'2px', 'input_font':'arial, cursive, fantasy', 'input_font_weight':'400', 'input_margin':'5px 0px 5px 0px', 'input_padding':'0px 5px 0px 5px', 'label_color':'#5D99CA', 'label_size':'16px', 'label_width':'150px', 'label_font':'arial, fantasy, serif', 'label_font_weight':'normal', 'label_margin':'5px 0px 0px 0px', 'label_padding':'2px 5px 2px 5px', 'label_border_style':'dashed', 'label_border_color':'#EF9F6D', 'label_border_radius':'0px', 'label_border_width':'2px', 'background_color':'white', 'height':'25px', 'width':'85px', 'padding_bottom':'2px', 'type':'dropdown' }, 'body': { 'background_color':'white' } }, authorization: { 'clientKey': clientKey } }).then(function(instance){ //use instance object to process and tokenize sensitive data payment fields. });
//PTPayment.getControl examples PTPayment.getControl("securityCode").label.text("CSC"); PTPayment.getControl("creditCard").label.text("CC"); PTPayment.getControl("expiration").label.text("Exp Date"); //PTPayment.theme examples PTPayment.theme('horizontal'); PTPayment.theme('above the line'); PTPayment.theme('below the line'); PTPayment.theme('label-none'); PTPayment.theme('label-extended-top'); //PTPayment.style examples PTPayment.style({'cc': {'border_style': 'dashed'}}); PTPayment.style({'code': {'label_color': 'red'}}); PTPayment.style({'exp': {'type': 'textbox'}});
Add secure EMV functionality to your applications with PayTrace’s semi-integrated EMV solution. By simply plugging in a few extra lines of code, you will gain access our secure-encrypted keyboard emulated EMV device.
PayTrace’s EMV 2.0 allows the host application to acquire secure-encrypted card information from the ID TECH Augusta EMV reader. The card data is encrypted at the point of interaction, ensuring that sensitive cardholder data is never exposed to your environment. This will add a layer of security to your card-present chip transactions and enable merchants to qualify for Level III interchange rates using PayTrace EMV 2.0.
PayTrace EMV 2.0 uses a customized encryption and configuration file. Only PayTrace authorized distributors can securely configure the ID Tech Augusta device to work with our service. For more information regarding these authorized distributors, please see the PayTrace Recommended Hardware page.
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/emv |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| emv_data | A string of data from a credit card chip provided by the IDTech EMV card reader. This field is also used for FallBack Swipe data in the event that a fallback is triggered. See Fallback for more information regarding Fallback swipes | 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 when submitting an encrypted CSC value with the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Require CSC" field and "Required on Swiped" are enabled within the PayTrace Virtual Terminal → Account → Settings page. Required if configured |
| billing _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 within the 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 within the PayTrace Virtual Terminal → Account → Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, click here shipping_address Schema. | object | Optional |
| A customer's email address where the Authorization receipt will be sent. | string | Optional | |
| description | Optional 255 character max length text describing the transactions, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 | The value that is sent to the cardholder’s issuer that overrides the business name stored within the PayTrace system. Custom DBA values are only used with requests to process sales or authorizations through accounts on the TSYS/Vital, Heartland, and Trident networks. | string | Optional |
| enable_partial_authorization | This flag must be set to true in order to support partial authorizations and balance amounts in transaction responses. PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer. | boolean | Optional |
| discretionary_data | Discretionary data details. For the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with the avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that 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 |
| emv_details | For the supported schema, Click here EMV_Details Schema. | 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, check the success and response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a sale transaction is declined by the processing network, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"emv_data":"DFEE25020203DFEE26022201DFEE120A62994997060000A00021DFEF5D134761CCCCCCCC0010D2212201CCCCCCCCCCCCCC572011075635C199B5AE46FB3238EACFAFC67FEE20DF89906C2D14C694107E4E30DCDFEF5B084761CCCCCCCC00105A1021710493D36CD03AE81FD809E226C3155F201A554154205553412F5465737420436172642030342020202020205F24032212315F25031903015F280208405F2A0208405F2D02656E5F3401015F570100500B56495341204352454449544F07A000000003101082021C008407A00000000310108C159F02069F03069F1A0295055F2A029A039C019F37048E0A00000000000000001F008D178A029F02069F03069F1A0295055F2A029A039C019F37049C01009F02060000000000009F03060000000000009F13009F1E0834543330313733329F20009F34031F00029F360200839F37049D53D32A9F38009F3901059F4D009F4F009F530152950580000000009B0268008A025A3399009F5B009F4005F000F0A0019F0607A00000000310109F33036028C89F3501219F1A0208409F26081458EFBEADAEAED49F2701809F100706010A03A0B000DFEF5720494420544543482041756775737461205553422D4B422056312E30332E303135",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":301806687,
"approval_code":"TAS232",
"approval_message":"APPROVAL TAS232 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"emv_details":{
"AID":"A0000000031010",
"TVR":"8000000000",
"IAD":"06010A03A0B000",
"TSI":"6800",
"ARC":"00"
},
"external_transaction_id":""
}The following error response will be returned with an HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":301809160,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}An EMV Authorization can be performed when a Credit card is present.
This method verifies a customer's credit card information and places a hold on the amount requested. A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.
Post | /v1/transactions/authorization/emv |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| emv_data | A string of data from a credit card chip provided by the IDTech EMV card reader. This field is also used for FallBack Swipe data in the event that a fallback is triggered. See Fallback for more information regarding Fallback swipes | 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 values 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 within the 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 within the 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 within the PayTrace Virtual Terminal → Account → Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| The customer's email address where the Authorization receipt will be sent. | string | Optional | |
| description | Optional 255 character max length text describing the transactions, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 | This flag must be set to true in order to support partial authorizations and balance amounts in the transaction responses. PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer. | boolean | Optional |
| discretionary_data | Discretionary data details. For the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
Additional Verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The 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 |
| emv_details | For the supported schema, Click here EMV_Details Schema. | 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, check the success and response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values.
If an Authorization transaction is declined by the processing network, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":2.50,
"emv_data":"DFEE25020203DFEE26022201DFEE120A62994997060000A00021DFEF5D134761CCCCCCCC0010D2212201CCCCCCCCCCCCCC572011075635C199B5AE46FB3238EACFAFC67FEE20DF89906C2D14C694107E4E30DCDFEF5B084761CCCCCCCC00105A1021710493D36CD03AE81FD809E226C3155F201A554154205553412F5465737420436172642030342020202020205F24032212315F25031903015F280208405F2A0208405F2D02656E5F3401015F570100500B56495341204352454449544F07A000000003101082021C008407A00000000310108C159F02069F03069F1A0295055F2A029A039C019F37048E0A00000000000000001F008D178A029F02069F03069F1A0295055F2A029A039C019F37049C01009F02060000000000009F03060000000000009F13009F1E0834543330313733329F20009F34031F00029F360200839F37049D53D32A9F38009F3901059F4D009F4F009F530152950580000000009B0268008A025A3399009F5B009F4005F000F0A0019F0607A00000000310109F33036028C89F3501219F1A0208409F26081458EFBEADAEAED49F2701809F100706010A03A0B000DFEF5720494420544543482041756775737461205553422D4B422056312E30332E303135",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":301810184,
"approval_code":"TAS673",
"approval_message":"APPROVAL TAS673 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"emv_details":{
"AID":"A0000000031010",
"TVR":"8000000000",
"IAD":"06010A03A0B000",
"TSI":"6800",
"ARC":"00"
},
"external_transaction_id":""
}The following error response will be returned with an HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":301810734,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}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/emv |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| emv_data | A string of data from a credit card chip provided by the IDTech EMV card reader. This field is also used for FallBack Swipe data in the event that a fallback is triggered. See Fallback for more information regarding Fallback swipes | 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 when submitting encrypted CSC values 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 within the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| billing _address | For the 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 within the 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 within the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| The customer's email address where the Refunds receipt will be sent. | string | Optional | |
| description | Optional 255 character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that 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 is 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, check the success and response_code parameter values. Check out API Response Codes for possible values.
If a refund transaction is declined by the processing network, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":3.25,
"emv_data":"DFEE25020203DFEE26022201DFEE120A62994997060000A0002DDFEF5D134761CCCCCCCC0010D2212201CCCCCCCCCCCCCC57201A3D0538BD9DEE0D2047E2C6A4BAFB8DBC8C8AEE8B281B77C0BC8480F38DD234DFEF5B084761CCCCCCCC00105A105601707C5A0DAE0AF2284B2D7496A7B75F201A554154205553412F5465737420436172642030342020202020205F24032212315F25031903015F280208405F2A0208405F2D02656E5F3401015F570100500B56495341204352454449544F07A000000003101082021C008407A00000000310108C159F02069F03069F1A0295055F2A029A039C019F37048E0A00000000000000001F008D178A029F02069F03069F1A0295055F2A029A039C019F37049C01009F02060000000000009F03060000000000009F13009F1E0834543330313733329F20009F34031F00029F3602008A9F3704F456ACCA9F38009F3901059F4D009F4F009F530152950580000000009B0268008A025A3399009F5B009F4005F000F0A0019F0607A00000000310109F33036028C89F3501219F1A0208409F26081192E0F86A9D70459F2701809F100706010A03A0B000DFEF5720494420544543482041756775737461205553422D4B422056312E30332E303135",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":301811813,
"approval_code":"TAS897",
"approval_message":"APPROVAL TAS897 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}An EMV fallback transaction occurs when a customer attempts to use an EMV (chip) card, at an EMV chip terminal, but the chip is unable to be read due to technical issues. The Terminal will then “fall back” to the magnetic strip technology in order to continue the transaction as a swiped transaction.
When the card reader experiences a Technical issue, it will provide a value in place of the normal EMV chip data. When the API receives this value, it will respond with one of the following API error Codes which indicate how to proceed with the transaction.
| Type | Description | Error code | Error Message |
|---|---|---|---|
| No Chip | The card has no chip and can only be swiped. Note: No Error code or message provided | - | - |
| Technical | The chip is damaged or cannot be read. This will prompt your customer to reattempt the chip read. | 300 | Invalid Chip Read. Please reinsert the card. |
| Technical | The chip is damaged or cannot be read and must be swiped. Note: Only prompts after 3 unsuccessful chip reads | 301 | Invalid Chip attempts exceeded. Please re-attempt the swipe. |
| Empty Candidate | The EMV terminal does not have applications in common with the EMV card and must be swiped. | 302 | Empty Candidate. Please attempt to swipe. |
| Technical | The Card reader failed to read the chip. This will prompt your customer to reattempt the chip read. | 303 | Card reader error. Please reinsert card. |
After receiving a response from the PayTrace API that indicates a Fallback has been triggered, the customer should be prompted to proceed according to the API error message received within the response. The new value provided by the chip reader should then be sent within the emv_data field and resubmitted using the same EMV API request method used for the original attempt.
The following emv_data values will prompt the API to respond with the appropriate EMV Fallback responses. In order to complete the transaction, use the appropriate Fallback Swipe emv_data values after the fallback response has been provided.
| Type | Description | emv_data Value |
|---|---|---|
| Technical | Prompts to retry inserting the chip due to a technical error | DFEF6102F220 |
| Technical | Prompts to swipe the card due to too many failed chip insert attempts | DFEF6102F222 |
| Empty Candidate | Prompts to swipe the card due to empty candidate card read | DFEF6102F221 |
No Chip Fallback Swipe Value:
02E300801E0025009292;4259********0890=2202*************?*548979D445DA7143316A17895BC86FABC1F9BB794B24424223708FB02865A1B7FD6611B518A1A2F7FF2D226008BDD7B500000000000000000000000000000000000000003932385439363636393362994900A9000080007B34CE03Empty Candidate Fallback Swipe Value:
DFEE250250059F390180DFEE238201D602CA01801F402400B39B%*5413********0011^UAT USA/TEST CARD 10 ^2212************?*;5413********0011=2212************?*B7F09688FC1E2B3CB957390EB0EB1C64CBF3235C4E92320D21D9BBB4D20C745DA8776A1DD6D8C776B74DFC84860FF4018D40936D059665C359B151EF032F52F6B3DEBEEE2EB149626951C72A7F07D04129CDD5F96ABEDD44438CA5A4E718C6ECB8DEA14E42FB84E4AA2B2636ECCDAFCA00000000000000000000000000000000000000000000000000000000000000000000000000000000393335543038373430306299499706000060002378E603Technical Fallback Swipe Value:
DFEE250230029F390180DFEE238201FC02F001801F452500B39B%*4761********0267^UAT USA/TEST CARD 05 ^2212*****************?*;4761********0267=2212*************?*F8C00132E9679248B45A08C64C66D53C3DC832ACCF8E979749FE8EDF50EB58822E3F3626B9FACFD0988ED4DF3C350993D1FBF14A4E46F6FC065E07DDE762E6A1C94FDFD42B1EDEFBDEE878E1EBF1073A1710FE82C6A8C99F63D75DDDC8C4FF40D0591C7BFB966FA90138FAC27804C7AB195E71435A9E0AA7BDCCE874CA118492000000000000000000000000000000000000000000000000000000000000000000000000000000003934345433303137333162994997060000C0000773D903{
"amount":1.00,
"emv_data":"FEF6102F221",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"302":[
"Empty Candidate. Please attempt swipe."
],
"external_transaction_id":""
}{
"amount":1.00,
"emv_data":"DFEE250250059F390180DFEE238201D602CA01801F402400B39B%*5413********0011^UAT USA/TEST CARD 10 ^2212************?*;5413********0011=2212************?*B7F09688FC1E2B3CB957390EB0EB1C64CBF3235C4E92320D21D9BBB4D20C745DA8776A1DD6D8C776B74DFC84860FF4018D40936D059665C359B151EF032F52F6B3DEBEEE2EB149626951C72A7F07D04129CDD5F96ABEDD44438CA5A4E718C6ECB8DEA14E42FB84E4AA2B2636ECCDAFCA00000000000000000000000000000000000000000000000000000000000000000000000000000000393335543038373430306299499706000060002378E603",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":101,
"status_message":"Your transaction was successfully approved.",
"transaction_id":303770877,
"approval_code":"VTLMC1",
"approval_message":"APPROVAL VTLMC1 - Approved and completed",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}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.
A Keyed Sale can be performed when the card is NOT present.
Post | /v1/transactions/sale/keyed |
| Attribute | Description | Type | Configuration (This must be provided if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This 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 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 | The CSC is the 3 or 4 digit code found on the signature line of the credit card. The CSC is found on the front of AMEX cards. Use encrypted_csc when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page. Required if configured |
| billing _address | For the supported Schema, Click here Billing_Address Schema. | object | This object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_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 the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| The customer's email address where the Authorization 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 | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 | The 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 | This flag must be set to true in order to support partial authorizations and balance amounts in the transaction responses. PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer. | boolean | Optional |
| discretionary_data | Discretionary data details. For the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values: true/false. True indicates the request was successful and there were no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request which 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 | The 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 which will be returned in the response. | string |
| masked_card_number | A credit card number with all digits masked and replaced with 'x' except the last 4 digits. This parameter will be returned in the JSON response only when the Credit Card number is one of the request parameters. | string |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a sale transaction is declined by the processing network due to any reason, the appropriate Response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad Request. Test data can be found here.
{
"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"
}
}* The above sample request contains only the 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"
}
}* The Above sample request contains only the minimum required parameters.
The following response will be returned with an 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"
}The following error response will be returned with an 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 | The 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 | A string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2. Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client Side Encryption JavaScript Library. | string | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 when submitting encrypted CSC values 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 the 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 the 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional Verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | |
| status_message | A status message about the request that 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 | A transaction approval message from the processing networks. | string |
| avs_response | A unique string identifier returned by the AVS. Check out AVS Response for 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 |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a sale transaction is declined by the processing network due to any reason, the appropriate Response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}* The above sample request contains the minimum required parameters.
{
"amount":4.00,
"encrypted_swipe":"nELVjn9xI5m/CDSThOgMSvaXuBjCg+J4fuTLbQRlVXtwRd4toMgcdHEv9SFUCXw/BmTRbN/Vb431eoW6JawR983M2TbpjEd7qgmE87Y6C2A/sjoQWfU6WQGXJI08TRZXxFtds6ksYqRckthKT89Ym8q6AuXX4UR1CH/jsA20TKGpEolA/XHfXMS72nNLMcNti0+m5W6oPik50m7qSZJl0xFxXNsgN8mrKzMGhkQHsnPGSKjN30jkAa2ne8rYfQuoZQ/M9FEZzQWUX7JlKcrlWufO54jtuSC+DeGR+6pCzUqXctaGeKhIC12BfGVGNcRQMtHVZadGqXyR708fjeJdqg==",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an 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 transaction made within PayTrace.
Post | /v1/transactions/sale/by_transaction |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The 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: The transaction ID should be a reference to a legitimate transaction with the PayTrace system in the past to avoid API errors. | number | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal→ Account → Security Settings page. Required if configured |
| billing _address | For the supported Schema, Click here Billing_Address Schema. | object | This object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_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 in the 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 |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | An optional 255-character max-length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional Verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.
| 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 the 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 possible values. | number |
| status_message | A status message about the request that 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 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 |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from response parameters avs_response and csc_response. Check out AVS and CSC response for possible values.
If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"transaction_id":105968529,
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an 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 | The dollar amount of the transaction. This 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 in the PayTrace Vault to avoid API errors. | string | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the 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 in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, click here shipping_address Schema. | object | Optional |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"customer_id":"customerId121",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an 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 the Customer_id customerid123 does not exist in PayTrace vault, the following error response will be returned with an 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 Protect Sale will allow you to process a transaction using the token and encryption key created when using the Protect.js UI.
Post | /v1/transactions/sale/pt_protect |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| hpf_token | A one time nonce representing the senstitive credit card data collected by the Protect.js UI. | string | No configuration settings applied. Required |
| enc_key | Unique cipher key provided by the Protect.js UI. | string | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, click here shipping_address Schema. | object | Optional |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"hpf_token":"c4d65578-4a5a-4369-8840-dceebb7fa002",
"enc_key":"Jy75EHB6AeA5mt-Xi1CvPUGrqe9lqwpr1Krxn2SWL1w=",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":319057089,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}If the hpf_token or the enc_key do not exist within PayTrace or have been expired, the following error response will be returned with an HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"961":[
"No payment fields found with the provided token."
],
"external_transaction_id":""
}This method will allow you to process a transaction and create a customer profile upon the transaction approval using the token and encryption key created when using the Protect.js UI.
Post | /v1/transactions/sale/pt_protect_customer |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| hpf_token | A one time nonce representing the sensitive credit card data collected by the Protect.js UI. | string | No configuration settings applied. Required |
| enc_key | Unique cipher key provided by the Protect.js UI. | string | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | string | 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 not be an existing customer ID in the PayTrace Vault to avoid API errors. | 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 in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, click here shipping_address Schema. | object | Optional |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request. | string |
| external_transaction_id | A unique identifier of the request from your system that will be returned in the response. | string |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a transaction is approved but the provided customer id already exists in the database, A customer profile will not be created. When this occurs, you will receive an HTTP status code in the 2XX range with a JSON body. Unlike with a sucessfull response, you will receive a response code of 167 with a status_message stating "Your transaction was successfully approved. However, the requested customer profile could not be created." Check out API Response Codes for other possible values.
If a sale transaction attempt is declined by the processing network due to any reason, the appropriate response code will be returned in the error response. A customer profile will not be created if the transaction has been declined.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":10.00,
"hpf_token":"20cf37c4-ff0f-4ff1-a918-e82c6324103d",
"enc_key":"YYO05e8xTRmYd1BtuW9TRQfSSKqsKlvaRZkXyHaE4nc=",
"integrator_id":"xxxxxxxxxx",
"customer_id":"NewCustomer1",
"csc":"999",
"billing_address":{
"name":"Steve Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":165,
"status_message":"Your transaction was successfully approved and customer profile was created.",
"transaction_id":321203124,
"approval_code":"VTLMC1",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"customer_id":"NewCustomer1",
"external_transaction_id":""
}The following error response will be returned with an HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":321208726,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"NO Match",
"external_transaction_id":""
}If the transaction is approved but the provided customer id already exists in the database, A customer profile will not be created. When this occurs, you will receive an HTTP status code in the 2XX range with a JSON body.
{
"success":true,
"response_code":167,
"status_message":"Your transaction was successfully approved. However, the requested customer profile could not be created.",
"transaction_id":321212432,
"approval_code":"VTLMC1",
"approval_message":"EXACT MATCH - Approved and completed",
"avs_response":"Full Exact Match",
"csc_response":"Match",
"customer_id":"NewCustomer1",
"external_transaction_id":""
}An Authorization transaction verifies a customer's credit card information and places a hold on the amount requested. A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.
Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with Authorization.
Keyed Authorization can be performed when the card is NOT present.
This Method verifies a customer's credit card information and places a hold on the amount requested. A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.
Post | /v1/transactions/authorization/keyed |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This 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 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the 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" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled from the 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 |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The 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 | An 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 | This flag must be set to true in order to support partial authorizations and balance amounts in the transaction responses. PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer. | boolean | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and has no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 | The 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 | The credit card number with all digits masked and replaced with 'x' except the last 4 digits. This parameter will be returned in JSON response only when the Credit Card number is one of the request parameters. | string |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and the esponse_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If an Authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if the transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"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"
}
}*The above sample request contains the minimum required parameters.
The 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"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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"
}The following response will be returned with an 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"
}A Swiped Authorization can be performed when a credit card is present.
This Method verifies a customer's credit card information and places a hold on the amount requested. A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.
Post | /v1/transactions/authorization/swiped |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| swipe or encrypted_swipe | A string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2. Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library. | 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 when submitting encrypted CSC values 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 the 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 the PayTrace Virtual Terminal → Account → Settings page. Required if configured |
| invoice_id | A unique identifier for the 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 the 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 |
| A customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 | This flag must be set to true in order to support partial authorizations and balance amounts in transaction responses. PARTIALAMOUNT and BALANCEAMOUNT are only returned if this flag is set to true and a transaction is partially approved or a balance response is provided by the card issuer. | boolean | Optional |
| discretionary_data | Discretionary data details. For supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional Verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 | A 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values.
If an Authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":2.50,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
{
"amount":2.50,
"encrypted_swipe":"nELVjn9xI5m/CDSThOgMSvaXuBjCg+J4fuTLbQRlVXtwRd4toMgcdHEv9SFUCXw/BmTRbN/Vb431eoW6JawR983M2TbpjEd7qgmE87Y6C2A/sjoQWfU6WQGXJI08TRZXxFtds6ksYqRckthKT89Ym8q6AuXX4UR1CH/jsA20TKGpEolA/XHfXMS72nNLMcNti0+m5W6oPik50m7qSZJl0xFxXNsgN8mrKzMGhkQHsnPGSKjN30jkAa2ne8rYfQuoZQ/M9FEZzQWUX7JlKcrlWufO54jtuSC+DeGR+6pCzUqXctaGeKhIC12BfGVGNcRQMtHVZadGqXyR708fjeJdqg==",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an 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 transaction made within 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 | The dollar amount of the transaction. This 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: This should be a reference to a legitimate transaction within the PayTrace system in the past to avoid 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 when submitting an 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 the PayTrace Virtual Terminal→ Account → Security Settings page. Required if configured |
| billing _address | For the supported Schema, Click here Billing_Address Schema. | object | This object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured. |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| A customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with the avs_response and the csc_response. Check out AVS and CSC response for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 | The 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 |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from response parameters avs_response and csc_response. Check out AVS and CSC response for possible values.
If an authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an 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 | The dollar amount of the transaction. This 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 within the PayTrace Vault to avoid API errors. | string | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 when submitting the encrypted CSC value by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled in the 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" are enabled in the 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 the 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 |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | An optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The 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 | An 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 | This 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with the avs_response and the csc_response. Check out AVS and CSC response for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and there were no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 | The 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If an authorization transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":3.70,
"customer_id":"customerId120",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an 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 the customer id customerid123 does not exist in the PayTrace vault, the following error response will be returned with an 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 will allow you to process an authorization on the requested amount using the token and encryption key created when using the Protect.js UI.
A Capture request can be submitted later to convert this authorization into a Sale, that can be settled for payment.
Post | /v1/transactions/authorization/pt_protect |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| hpf_token | A one time nonce representing the senstitive credit card data collected by the Protect.js UI. | string | No configuration settings applied. Required |
| enc_key | Unique cipher key provided by the Protect.js UI. | string | No configuration settings applied. Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, click here shipping_address Schema. | object | Optional |
| The customer's email address where the Authorization receipt may be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
Additional verification can be performed with avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates the request was successful and there are no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 |
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and the response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters avs_response and csc_response. Check out AVS and CSC response for possible values. Test data can be found here.
If a sale transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":4.00,
"hpf_token":"c4d65578-4a5a-4369-8840-dceebb7fa002",
"enc_key":"Jy75EHB6AeA5mt-Xi1CvPUGrqe9lqwpr1Krxn2SWL1w=",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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":""
}The following error response will be returned with an HTTP Status 400 Bad Request.
{
"success":false,
"response_code":102,
"status_message":"Your transaction was not approved.",
"transaction_id":319057089,
"approval_code":"",
"approval_message":" DECLINE - Do not honor",
"avs_response":"0",
"csc_response":"",
"external_transaction_id":""
}If the hpf_token or the enc_key do not exist within PayTrace or have been expired, the following error response will be returned with an HTTP status code 400 Bad Request.
{
"success":false,
"response_code":1,
"status_message":"One or more errors has occurred.",
"errors":{
"961":[
"No payment fields found with the provided token."
],
"external_transaction_id":""
}This method can be used to convert any preauthorized transaction into a Sale, to be settled for payment. The unsettled and preauthorized transaction ID that should be provided for a successful capture.
If an amount parameter is not submitted, the transaction will be captured with the original authorized amount.
Post | /v1/transactions/authorization/capture |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: The transaction should be unsettled and a pre authorized transaction within the PayTrace system to avoid any API errors. | 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 | The dollar amount of the transaction. Must be a positive number up to two decimal places. Note: The amount must be less than or equal to the original authorization amount. | number | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates the request was successful and had no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_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 | A 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If a capture of a transaction request is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if the transaction is not captured, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"transaction_id":105968543,
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":112,
"status_message":"Your transaction was successfully captured.",
"transaction_id":105968543,
"external_transaction_id":""
}The following error response will be returned with an 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, the following error response will be returned with an 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 an Unsettled transaction with the 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_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 | A 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If a void transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if a void transaction is not successful, you will get a declined transaction response with a HTTP status code - 400 Bad request. Test data can be found here.
{
"transaction_id":105968551,
"integrator_id":"xxxxxxxxxx"
}The following response will be returned with an 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, the following error response will be returned with an 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, the following error response will be returned with an 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. The following conditions must be fulfilled for a successful transaction.
Post | /v1/transactions/adjust |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| amount | The 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 within the PayTrace system to avoid any API errors. | string | Required |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is successful. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
For example, If an amount is invalid or does not meet the adjustment criteria (described earlier), an error response will be returned with an HTTP status code of - 400 Bad request. Test data can be found here.
{
"transaction_id":105968552,
"amount":5.50
}The following response will be returned with an 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 the adjustment criteria (described earlier), the following error response will be returned with an 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 | The 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the 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" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled from the 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 |
| The customer's email address where the Refunds receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The 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 an HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A 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 | The 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 the last 4 digits. This parameter will be returned in the JSON response only when the Credit Card number is one of the request parameters. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check any unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
{
"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"
}
}*The above sample request contains the 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"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 | The 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 | The string data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2. Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library. | 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 when submitting encrypted CSC values 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 the 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 the 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 the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| The customer's email address where the Refunds receipt will 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 | The 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 an HTTP status code in the 2XX range with a JSON body.
Using this method, the VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA, Refund transactions will be processed as regular Refunds and will not contain Authorization data.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If a refund transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if the transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":3.25,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the 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"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 the amount is submitted, a 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 | The dollar amount of the transaction. Must be a positive number up to two decimal places. Note: If the amount is not provided, the transaction will be refunded with the original amount. | number | No configuration settings applied. Required |
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: It should be a reference to a legitimate transaction within the PayTrace system in the past, to avoid any API errors. | 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled in the 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" are enabled in the 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 the 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 |
| The customer's email address where the Refund receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 an HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | A status message about the request that 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 | The 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
{
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 | The dollar amount of the transaction. This 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 in the 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the 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" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| The customer's email address where the Refund receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The 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 an HTTP status code in the 2XX range with a JSON body.
Using this method, VISA Refund transaction responses will contain Authorization data much like that of a Sale or Authorization Request. Non-VISA Refund transactions will be processed as regular Refunds and will not contain Authorization data.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | Status message about the request that 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 | The 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
{
"amount":4.75,
"customer_id":"customerId120",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 the customer ID customerid123 does not exist in a PayTrace vault, the following error response will be returned with an 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 a merchant to issue a refund back to a customer's credit card account.
Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with Refund requests.
Keyed Refunds can be performed when the card is NOT present.
This method can be used to issue a credit back to the credit card holder's account.
Post | /v1/transactions/refund/keyed |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| billing _address | For the 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 the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the 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 the supported schema, Click here shipping_address Schema. | object | Optional |
| A customer's email address where the Refund receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The 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.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | A status message about the request that 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 the last 4 digits. This parameter will be returned in the JSON response when the Credit Card number is included in the request parameters. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
{
"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"
}
}*The above sample request contains the 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"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 a 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 | The 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 | A string of data from a credit card magnetic stripe which should conform to the ISO/IEC 7813 specification using Track 1 and Track 2. Use encrypted_swipe when submitting encrypted swipe value by the PayTrace Client-Side Encryption JavaScript Library. | 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 when submitting encrypted CSC values 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 in the 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 in the 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 in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For the supported schema, Click here shipping_address Schema. | object | Optional |
| The customer's email address where the Refunds receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If a refund transaction is declined by the processing network due to any reason, the appropriate response code will be returned in the error response.
For example, if the transaction is not approved, you will get a declined transaction response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"amount":3.25,
"swipe":"%B4012881888818888^Demo/Customer^2412101001020001000000701000000?;4012881888818888=24121010010270100001?",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the 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"
}*The above sample request contains the minimum required parameters..
The following response will be returned with an 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 the amount is submitted, the specific amount will be refunded to 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 | The dollar amount of the transaction. This must be a positive number up to two decimal places. Note: If the amount is not provided, the transaction will be refunded with the original amount. | number | No configuration settings applied. Required |
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: It should be a reference to a legitimate transaction within the PayTrace system in a past to avoid any API errors. | 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled from the 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" are enabled in the 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 in the 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 |
| The customer's email address where the Refund receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is refunded. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
{
"transaction_id":105968532,
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 | The dollar amount of the transaction. This 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 in the 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 when submitting encrypted CSC values by the PayTrace Client-Side Encryption JavaScript Library. | string | This attribute is only required if the "Required CSC" field is enabled in the 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" are enabled in the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled in the 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 |
| The customer's email address where the Refund receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction is approved. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_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 | The status message about the request that 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
{
"amount":4.75,
"customer_id":"customerId120",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":106,
"status_message":"Your transaction was successfully refunded.",
"transaction_id":105968560,
"external_transaction_id":""
}If the customer ID customerid123 does not exist in a PayTrace vault, the following error response will be returned with an 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 a PCI-compliant Customer Database (Vault) for your account. You can store a customer's billing and payment information in this database with your customer ID (token). This database can eliminate your application requirements for storing sensitive payment information. The customer IDs can be used with future transactions. When an existing Customer ID is used for transactions, the associated billing and payment information from the database will be used.
You can manage your customer profiles using various create, update, delete and export methods in your PayTrace database (Vault).
Encrypted values by the PayTrace Client-Side Encryption JavaScript Library can be used with all customer Profile methods.
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 in the 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 | The checking 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" are enabled from the 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 |
| The customer's email address where the transaction receipt will be sent. | string | Optional | |
| phone | The customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is created. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customer_id | A unique identifier for each customer in the PayTrace system, the value must be the same as provided with the request. | string |
| masked_card_number | The credit card number with all digits masked and replaced with 'x' except for the last 4 digits. Note:This parameter will be returned in the JSON response when the Credit Card number is one of the request parameters. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful requests check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If provided customer id already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"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"
}
}*The above sample request contains the 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"
}
}*The above sample request contains the minimum required parameters.
Following response will be returned with an 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 the customer_id already exists in the PayTrace database (Vault), the following error response will be returned with an 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 in the 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 to a legitimate transaction within the PayTrace system processed in the 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" are enabled from the 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 |
| The customer's email address where the transaction receipt will be sent. | string | Optional | |
| phone | The customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is created. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
Any duplicate customer ID or an invalid Transaction ID, as well as an invalid input parameter, will result in an error.
To check for unsuccessful requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If provided customer id already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"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"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 the customer_id already exists in the PayTrace database (Vault), the following error response will be returned with an 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) for 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 | The checking 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" are enabled in the 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 |
| The customer's email address where the transaction receipt will be sent. | string | Optional | |
| phone | The customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is Updated. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request. | string |
| masked_card_number | The credit card number with all digits masked and replaced with 'x' except the last 4 digits. Note: This parameter will be returned in JSON response only when the Credit Card number is one of the request parameters. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the provided customer ID already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"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"
}The 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"
}The following response will be returned with an 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 a new customer ID already exists in the PayTrace database (Vault), the following error response will be returned with an 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 an 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is deleted. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If provided the customer ID doesn't exist in the database to update the profile, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"customer_id":"customerTest121",
"integrator_id":"xxxxxxxxxx"
}The following response will be returned with an 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 the customer ID customerTest150 doesn't exist in the PayTrace database (Vault), the following error response will be returned with an 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 profiles 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 an existing customer profile stored in your Customer Database (Vault) at PayTrace. | string | Optional |
| created | For the supported Schema, Click here Request_Creation_Record Schema. | object | Optional |
| The customer's email address. | string | Optional | |
| include_bin | If set to true, this will return the first 6 and last 4 digits of the credit card number. | boolean | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is exported. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customers | An array of customer profiles. For Customer Profile supported Schema, Click here Customer_Record Schema. | array |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the provided customer ID customerTest150 is not an existing customer profile, you will get an empty customer array in a response with an HTTP status code - 200 OK request. Test data can be found here.
{
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the 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 the provided customer ID doesn't exist in the PayTrace database (Vault), the following response with an empty customer array will be returned with an HTTP status code 200 OK.
{
"success":true,
"response_code":1,
"status_message":"Your request has been successfully completed.",
"customers":[
]
}This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault). You can assign a customer Id (token) with this method.
Post | /v1/customer/pt_protect_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 in the PayTrace Vault to avoid API errors. | string | No configuration settings applied. Required |
| hpf_token | A one time nonce representing the senstitive credit card data collected by the Protect.js UI. | string | No configuration settings applied. Required |
| enc_key | Unique cipher key provided by the Protect.js UI. | 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 | This object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address Schema. | object | Optional |
| The customer's email address where the transaction receipt will be sent. | string | Optional | |
| phone | The customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is created. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
Any duplicate customer ID or invalid Protect Token, as well as an invalid input parameter, will result in an error.
To check for unsuccessful requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If provided customer id already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"customer_id":"customer789",
"hpf_token":"e369847e-3027-4174-9161-fa0d4e98d318",
"enc_key":"lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=",
"integrator_id":"xxxxxxxxxx",
"billing_address":{
"name":"Mark Smith",
"street_address":"8320 E. West St.",
"city":"Spokane",
"state":"WA",
"zip":"85284"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 the customer_id already exists in the PayTrace database (Vault), the following error response will be returned with an 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) for your customer with this method.
Post | /v1/customer/pt_protect_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. Note: This ID should not be an existing customer ID in the PayTrace Vault to avoid API errors. | string | No configuration settings applied. Required |
| hpf_token | A one time nonce representing the senstitive credit card data collected by the Protect.js UI. | string | No configuration settings applied. Required |
| enc_key | Unique cipher key provided by the Protect.js UI. | 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 | This object is only required if the "Require Billing Address" and/or "Require Billing ZIP" are enabled from the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements |
|---|---|---|---|
| shipping_address | For supported schema, click here shipping_address Schema. | object | Optional |
| The customer's email address where the transaction receipt will be sent. | string | Optional | |
| phone | The customer's phone number (i.e. 555-555-5555, or 5555555555). | string | Optional |
| fax | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a customer profile is created. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| customer_id | A unique identifier for each customer in the PayTrace system, the value will be the same as provided with the request. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the provided customer ID already exists in the database, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"customer_id":"customer789",
"hpf_token":"e369847e-3027-4174-9161-fa0d4e98d318",
"enc_key":"lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=",
"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"
},
"email":"",
"phone":"",
"fax":"",
"new_id":"customerTest151New"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":161,
"status_message":"The customer profile for customerTest151New/Steve Smith New was successfully updated.",
"customer_id":"customerTest151New"
}If the customer_id already exists in the PayTrace database (Vault), the following error response will be returned with an 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."
]
}
}Level 3 data is additional information that may be applied to enrich a transaction’s reporting value to both the merchants and the customers. Generally, merchant service providers offer reduced or qualified pricing for transactions that are processed with Level 3 data.
Level 3 data can be added to any approved and unsettled Sale transaction with Visa or MasterCard. Some level 3 data, specifically enhanced data such as Invoice and Customer Reference ID, may overlap with data provided with the base transaction. Enhanced data, when applied, will always overwrite such data that may already be stored with the transaction.
Level 3 data consists of enhanced data and 1 or more line item records. This information is intended to describe the details of the transaction and the products or services rendered. However, defaults may be applied in the event when some data is missing or unknown. Skipped parameters will be replaced with PayTrace defaults.
Please make sure to set Level 3 defaults with your PayTrace Virtual Terminal Account before moving forward to add level 3 data methods.
Level 2 and 3 data is additional information that can be sent through with your transactions that can help qualify (keep processing rates low) certain types of credit cards. Level 2 and 3 data typically can help when accepting Business Cards, Purchasing Cards, Corporate Cards, or Government (GSA) Cards.
In most cases when you accept these types of cards, the dollar amount of the transaction is larger than if you were to accept a consumer/personal credit card. When the dollar amounts of the transactions go up, the risk associated with the card brands funding them goes up. This results in a higher processing rate due to the higher risk. However, level 2 and 3 data helps provide additional information about the merchant, customer, and transaction to help meet the card brand's criteria for reaching a lower processing rate. This additional information is not required to process or get funded for your transactions. However, providing this information helps reduce the risk associated with the funding of the transactions by the card brands, which results in lower processing rates.
For more information about specific level 2 and 3 information, click here
This method can be used to add Level 3 data to any approved and unsettled sale transaction with MasterCard.
You can add single or multiple line items as needed.
Post | /v1/level_three/mastercard |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| transaction_id | A unique identifier for each transaction in the PayTrace system. Note: This ID should reference a transaction that has been approved and is pending settlement within the PayTrace system to avoid any API errors. | 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 | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | number | Optional |
| national_tax_amount | The portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT). | number | Optional |
| freight_amount | The freight value should represent the portion of the transaction amount that was generated from shipping costs. | number | Optional |
| duty_amount | The portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT). | number | Optional |
| source_address | Only zip is a required attribute. For the supported schema, Click here shipping_address Schema. | object | Optional |
| shipping_address | Only zip and country are required attributes. For the 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 an additional tax was included in the transaction. Set to true - if an additional tax was included. Set to false - if no additional tax was applied. | boolean | Optional |
| line_items | Line items are a collection of product detail. It is an array containing zero or more Line Item objects. For supported schema, check out MasterCard_Line_Items Schema on the same page. | an array of an object/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 an additional tax was included in the transaction. Set to true - if an additional tax was included. Set to false - if no additional tax was applied. | boolean | Optional |
| additional_tax_rate | The rate at which additional tax was assessed. | number | Optional |
| amount | The 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 transaction. Generally, this is always a debit or there is a factor that increased the transaction amount. Possible values are D (net is a debit) and C (net is a credit). | 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 | The discount value should represent the amount discounted from the original transaction amount. | number | Optional |
| discount_rate | The rate at which a discount was applied to the transaction in reference to this specific line item. Note: When discount_amount and discount_included are true, this parameter is required for a successful request. | number | Optional |
| discount_included | A boolean flag used to indicate whether a discount was applied to the transaction amount in reference to the specific line item record. | boolean | Optional |
| merchant_tax_id | The 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 the 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 | The 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a Level 3 data is added. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | That status message about the request and provides additional information about the request execution end result. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful add level 3 data requests, check the success and response_code parameter values. Check out API Response Codes for possible values.
You will get an error response if a transaction is not eligible to add level 3 data. Test data can be found here.
With an invalid transaction ID or non-eligible transaction, you will get an error response with an 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
}The following response will be returned with an 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 an ineligible transaction, the following error response will be returned with an 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 an 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 to a transaction that is approved and pending settlement within the 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 | The 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 | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | number | Optional |
| national_tax_amount | The portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT). | number | Optional |
| merchant_tax_id | The merchant’s tax identifier used for tax reporting purposes. | string | Optional |
| customer_tax_id | The customer’s tax identifier used for tax reporting purposes. | string | Optional |
| commodity_code | The 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 | The discount value should represent the amount discounted from the original transaction amount. | number | Optional |
| freight_amount | The freight value should represent the portion of the transaction amount that was generated from shipping costs. | number | Optional |
| duty_amount | The portion of the original transaction amount that is national tax. Generally only applicable to orders shipped to countries with a national or value-added tax (VAT). | number | Optional |
| source_address | Zip is a required attribute. For supported schema, click here shipping_address Schema. | object | Optional |
| shipping_address | 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 | The rate at which additional tax was assessed. | number | Optional |
| line_items | Line items are a collection of product details. It is an array containing zero or more Line Items objects. For supported schema, click here Visa_Line_Items Schema on the same page. | an array of an object/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 | The rate at which additional tax was assessed. | number | Optional |
| amount | The dollar amount of the transaction. Must be a positive number up to two decimal places. | number | Optional |
| commodity_code | The commodity code 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: There is a max character limit of 35. | string | Optional |
| discount_amount | The 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: The transaction ID should be a reference to a transaction that is approved and pending settlement within the PayTrace system to avoid any API errors. | 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that Level 3 data was added. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful add level 3 data requests, please check the success and response_code parameter values. Check out API Response Codes for possible values.
You will get an error response if a transaction is not eligible for level 3 data. Test data can be found here.
With an invalid transaction ID or ineligible transaction, you will get an error response with an 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
}The following response will be returned with an 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 ineligible transaction, the following error response will be returned with an 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 transaction 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a settlement request is successful. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | Status message about the request and provides additional information about the request execution end result. | string |
| transaction_count | The 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 | The batch schema that provides details about the initiated batch for settlement. Note: Only the number Attribute will be returned. For supported Schema, Click here Batch_Record Schema | object |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful settlement requests, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If no transactions are pending for settlement, you will get an error response with an HTTP status code - 400 Bad request. Test data can be found here.
{
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 settlement, the following error response will be returned with an 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, the latest batch details will be returned.
By exporting the 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that an export batch request is successful. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| batch | This object contains details about the batch. Note: For the supported Schema, Click here Batch_Record Schema. | object |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export batch requests, please check the success and response_code parameter values. Check out API Response Codes for possible values.
This method will always return success true. All batch record values will be 0 or an empty string except for the batch_number if the batch_number doesn't exist.
If batch_number 1 doesn't exist, you will get a response with an HTTP status code - 200 OK request. All Batch record values will be 0 or empty string except batch_number. Test data can be found here.
{
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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, the following response will be returned with an 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 the batch summary details, your application will be able to determine the deposits and refunds.
Post | /v1/batches/export |
| Attribute | Description | Type | Attribute Requirement |
|---|---|---|---|
| start_date | The start date is used to indicate the beginning date used to search for transactions or batches to export. This must be a valid date formatted as MM/DD/YYYY. | string | Required |
| end_date | The end date is used to indicate the ending date used to search for transactions or batches to export. This must be a valid date formatted as MM/DD/YYYY. | string | Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | string | No configuration settings applied. Required |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that an export batch request is successful. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request and provides additional information about the request execution end result. | string |
| batches | This is an array of batch summary records. For supported Schema, Click here Batch_Summary_Record Schema | array of objects |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export batch requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If no batch exists within a requested date range, you will get an error response with an HTTP status code - 400 Bad Request. Test data can be found here.
{
"start_date":"07/10/2016",
"end_date":"07/15/2016",
"integrator_id":"xxxxxxxxxx"
}The following response will be returned with an 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 requested date range, the following response will be returned with an 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 transaction 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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that an export report request is successful. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values. Test data can be found here.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | A status message about the request that provides additional information about the request execution end result. | string |
| transactions | This 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export batch requests, check the success and response_code parameter values. Check out API Response Codes for possible values.
If a batch doesn't exist or no transactions exist, you will get an error response with an HTTP status code - 400 Bad Request. Test data can be found here.
{
"batch_number":50,
"integrator_id":"xxxxxxxxxx"
}The following response will be returned with an 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 a batch doesn't exist or no transactions exist within the request batch, the following response will be returned with an 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 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 reference a past, legitimate transaction within the PayTrace system 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 an 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 credit card number. | boolean | Optional |
| including_text | The text submitted will be used to locate transactions containing this text. This will help to narrow down the export results. | string | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that an export report request is successful. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values. Test data can be found here. This method will return an array of the transaction details object.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| transactions | This is an array of the 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export transaction requests, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If the transaction ID provided does not exist, you will get an error response with an HTTP status code - 400 Bad Request. Test data can be found here.
{
"transaction_id":105968573,
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
Following response will be returned with an 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 the transaction ID provided does not exist, the following response will be returned with an 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 transaction 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 | The start date is used to indicate the beginning date used to search for transactions or batches to export. This must be a valid date formatted as MM/DD/YYYY. | string | Required |
| end_date | The end date is used to indicate the ending date used to search for transactions or batches to export. This must be a valid date formatted as MM/DD/YYYY. | string | Required |
| integrator_id | A unique ID to correlate API consumers calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | 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 reference a past, legitimate transaction within the PayTrace system to avoid any API errors. | string | Required |
| transaction_type | The transaction type to find transactions. Possible values: SALE, AUTHORIZATION, STR/FWD, REFUND, VOID, SETTLED, PENDING, DECLINED. | string | Optional |
| created | For supported Schema, Click here Request_Creation_Record Schema. | object | Optional |
| customer_id | A unique identifier for an 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. This will help 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 that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| transactions | This 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export transaction requests, please check the success and response_code parameter values. Check out API Response Codes for possible values.
If no transaction exists within a request date range, you will get a response with an HTTP status code - 200 OK. Invalid dates will trigger an error response with 400 Bad Request. Test data can be found here.
{
"start_date":"04/10/2016",
"end_date":"04/15/2016",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an 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 the provided transaction ID does not exist, the following response will be returned with an 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, the following error response will be returned with an 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":""
}The PayTrace API allows you to create and manage recurring payments with your existing customers stored within the PayTrace customer database (Vault). Recurring Payments (transactions) will be processed as per the specified frequency until the transaction has been processed for the specified total count.
A unique ID will be assigned to the scheduled recurring payment when any recurring payment is created. This ID can be used to update, delete or export recurring payments.
This method allows you to create a recurring payment with an existing customer from your Customer Database (Vault) within 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 from an existing customer ID within the 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 length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a transaction has been created. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| recurrence | For supported Schema, Click here Recurrence_Record Schema. Note: ID will be the only parameter returned with the successful creation of a recurring payment. | object |
Error response will include a HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the customer_id customerid123 does not exist within the PayTrace vault, you will get an error response with an HTTP status code - 400 Bad request.
{
"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"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":150,
"status_message":"The recurring transaction was successfully created.",
"recurrence":{
"id":"647914"
}
}If the customer_id customerid123 does not exist within the PayTrace vault, the following error response will be returned with an 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 an existing recurring payment with a 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. The ID is required and the 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 within the PayTrace Vault to avoid API errors. | string | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a payment transaction is updated. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values. | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| recurrence | For supported Schema, Click here Recurrence_Record Schema. Note: ID will be the only parameter returned with a successful update request of a recurring payment. | object |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the recurrence id or customer_id does not exist in the PayTrace vault, you will get an error response with an HTTP status code - 400 Bad request.
{
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"id":"647918",
"amount":2.00
}
}*The above sample request contains the minimum required parameters.
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 the recurrence ID does not exist, the following error response will be returned with an 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 permanently delete an existing recurring payment with just the recurring payment ID.
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. ID is the only parameter required. For supported Schema, Click here Recurrence_Record Schema. | object | Required |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a payment transaction is deleted. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type | |
|---|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean | |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number | |
| status_message | The status message about the request that provides additional information about the request execution end result. | string | |
| recurrence | For supported Schema, Click here Recurrence_Record Schema. Note: ID will be the only parameter returned with a successful delete request of the recurring payment. | object |
Error responses will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
{
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"id":"647917"
}
}The following response will be returned with an 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 within the PayTrace Vault to avoid API errors. | string | Required to find all recurring payments for a specific customer. |
| integrator_id | A unique ID to correlate API consumer calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | string | No configuration settings applied. Required |
| recurrence | Recurrence Payment details. ID is the only parameter that is required. For supported Schema, Click here Recurrence_Record Schema. | object | Required to find a specific recurring payment transaction. |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a payment an export request is successful. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| recurrences | An array of Recurrence Record objects. For the supported schema, Click here Export_Recurrence_Record Schema. Note: If the Request parameter is a recurrence ID, you will get an array of single recurrence transaction records. If the Request parameter is a customer ID, you will get an array of one or more transaction records. | array of objects |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export requests, check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the customer ID or recurrence ID does not exist within the PayTrace vault, you will get an error response with an HTTP status code - 400 Bad request.
To find all recurrence payments for a specific customer.
{
"customer_id":"customerId123",
"integrator_id":"xxxxxxxxxx"
}OR
To find a specific recurrence payment transaction.
{
"integrator_id":"xxxxxxxxxx",
"recurrence":{
"id":"708751"
}
}The following response will be returned with an 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 the customer ID does not exist, the following error response will be returned with an 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 the 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 within your Customer Database (Vault) at PayTrace. Note: This ID should be an existing customer ID within the PayTrace Vault to avoid API errors. | string | Required |
| integrator_id | A unique ID to correlate an API consumer's calls to the PayTrace system. If you have not been assigned an Integrator ID, please request one on our Sandbox Request page. | string | No configuration settings applied. Required |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that an export request is successful. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| created | Transaction creation details. The 'at' attribute will be the only parameter used. For supported Schema, Click here Response_Creation_Record Schema. | object |
| recurrence | Recurrence Payment detail. ID will be the only parameter returned in 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 | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number |
| next_date | The next date when a recurring transaction is scheduled to occur. The format should 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 length text describing the transaction, products, customers, or other attributes of the transaction. | string |
| Attribute | Description | Type |
|---|---|---|
| TOTALCOUNT | The total number of times the recurring payment transaction should be processed. It should be set to 999 if the recurring payment transaction should be processed indefinitely. | string |
| CURRENTCOUNT | The number of times this payment has been processed in context to the total number of scheduled payments. The payment(s) will end when the current count is equal to the total count unless the total count is set to 999 (infinite). | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful export requests, please check the success and response_code parameter values. Check out API Response Codes for possible values. Test data can be found here.
If the customer ID does not have any recurring transactions, you will get an error response with an HTTP status code - 400 Bad request.
{
"customer_id":"customerId123",
"integrator_id":"xxxxxxxxxx"
}The following response will be returned with an 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 the customer ID does not have any recurring transactions, the following error response will be returned with an 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 Web User or an API User password. Web user passwords must be changed at least once every 90 days, while API User passwords/tokens must be changed once a year.
To find out more detail about the PayTrace user, Check out this page PayTrace User Profiles.
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 an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a password has been updated. You will need to verify the success and the response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The 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, an error response will be returned.
The error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful requests, check the success and response_code parameter values. Check out API Response Codes for possible values.
If the new password is similar to the last 5 passwords, you will get an error response with an HTTP status code - 400 Bad request.
{
"new_password":"NewPasswordValue",
"integrator_id":"xxxxxxxxxx"
}The following response will be returned with an 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, the following error response will be returned with an 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 within your account, you will need to contact your Merchant Service Provider. They will be able to enable check processing for you within PayTrace.
Check or ACH (Automated Clearing House) Sale transactions can be performed with this method by providing the 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 | The dollar amount of the transaction. This must be a positive number up to two decimal places. | number | No configuration settings applied. Required |
| check | The checking account details. 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 the supported Schema, Click here Billing_Address Schema. | object | The Billing Address Name is required. The Billing Address and Billing ZIP may be required if the "Require Billing Address" and/or "Require Billing ZIP" is enabled within the PayTrace Virtual Terminal → Account → Security Settings page. Required |
| invoice_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 within the PayTrace Virtual Terminal → Account → Security Settings page. Required if configured |
| Attribute | Description | Type | Attributes Requirements | ||
|---|---|---|---|---|---|
| shipping_address | For the supported schema, click here shipping_address. | object | Optional | ||
| The customer's email address where the transaction receipt will be sent. | string | Optional | |||
| description | Optional 255 character length max text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional | ||
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema, Click here Discretionary_Data Schema | object | Optional | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a check transaction is approved. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that 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 the 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 an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, check the success and response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters ach_code and ach_message. Test data can be found here.
With a declined check transaction, the 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 an 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"
}
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981619
}When processing a check with a real-time check processor two additional parameters are needed (ach_code and ach_message).
{
"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, the following response will be returned with an HTTP Status 400 Bad Request.
Note: If the real-time processor is Paya, the 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) within PayTrace.
Post | /v1/checks/sale/by_customer |
| Attribute | Description | Type | Configuration (Must provide if configured, results in an error when missing) |
|---|---|---|---|
| amount | The dollar amount of the transaction. This 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) within 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 the 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" are enabled within the PayTrace Virtual Terminal → Account → Security Settings page. Required |
| invoice_id | A unique identifier for the transaction in your accounting or inventory management system. | string | This attribute is only required if the "Require Invoice" field is enabled within the 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 |
| The customer's email address where the transaction receipt will be sent. | string | Optional | |
| description | Optional 255-character max length text describing the transaction, products, customers, or other attributes of the transaction. | string | Optional |
| tax_amount | The portion of the original transaction amount that is tax. This must be a number that reports the tax amount of the transaction. Use -1 if the transaction is tax-exempt. | string | 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 the supported schema Click here Discretionary_Data Schema | object | Optional |
A successful request returns an HTTP status code in the 2XX range with a JSON body.
An HTTP status code in the 2XX range does not indicate that a check transaction is processed. You will need to verify the success and response_code parameters. Check out API Response Codes for possible values.
| Attribute | Description | Type |
|---|---|---|
| success | This flag will indicate if the request is successful. Possible values : true/false. True indicates that the request was successful and had no errors. False indicates that the request was not successful and some kind of error has occurred. | boolean |
| response_code | This code will show you the response code based on the request execution status. Check out API Response Codes for possible values | number |
| status_message | The status message about the request that provides additional information about the request execution end result. | string |
| check_transaction_id | A unique identifier for each check transaction within the PayTrace system. | number |
| ach_code | This code is generated and returned by the real-time check processor when the check is processed. 0 (zero) indicates that the check was accepted. | number |
| ach_message | A message generated by the real-time check processor. | string |
Error response will include an HTTP status code and JSON body with error information. Check out API Errors for more information.
To check for unsuccessful transactions, please check the success and response_code parameter values. Check out API Response Codes for possible values.
Additional error information can be retrieved from the response parameters ach_code and ach_message. Test data can be found here.
With a declined check transaction, the 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 an HTTP status code - 400 Bad request.
{
"amount":2.00,
"customer_id":"customerId121",
"integrator_id":"xxxxxxxxxx"
}*The above sample request contains the minimum required parameters.
The following response will be returned with an HTTP Status 200 OK.
{
"success":true,
"response_code":120,
"status_message":"Your check was successfully processed.",
"check_transaction_id":981620
}If processing with a real-time check processor, two additional parameters are needed (ach_code and ach_message)
{
"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, the following response will be returned with an HTTP Status 400 Bad Request.
Note: If the 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":""
}I