Choose a topic...
Overview
The Cardknox Reporting API enables you to retrieve data from transactions and create reports for all report types.
Credentials
Parameter | Description | Comment |
---|---|---|
xKey | Credential | Max Size: 250 Alphanumeric Characters |
Universally Required Parameters
Parameter | Description | Comment |
---|---|---|
xVersion | Gateway API version | The current version is 4.5.8 |
xSoftwareName | The name of your software | |
xSoftwareVersion | Version number of your software | 2.1 |
xCommand | Transaction type | Samples: report:all, report:approved |
Endpoints
URL: https://x1.cardknox.com/report
Alternate URL: https://b1.cardknox.com/report
We also support JSON formatted responses. Replace /report in the URL with /reportjson.
Pagination
- Submit the first request.
- If xRecordsReturned equals xReportingMaxTransactions, submit another report request and adjust the beginning date and time according to the last transaction returned.
Filter Options
Available filtering options include the following.
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xgetnewest | Returns the most recent transactions in the requested date range | True/False |
xmaxrecords | Sets the maximum number of records to return on the report | Integer value between 1 – 1000*
If the date range on the report is within 24 hours you can request up to 5000 transactions |
For date-based reports, you can filter results using the following operators for any of the reporting fields:
Parameter | Operator | Description | Example |
---|---|---|---|
ai | In | Use for an exact match. | xBillCountry=aiCanada |
a= | Like | Use for fields that include your search string, but sometimes also include other information. | xAmount=a=40 |
a! | Not Like | Use for fields that does not include your search string, but sometimes also include other information. | xCardLastFour=a!4444 |
a< | Less Than | Shows results that are less than the value you enter. | xAmount=a<1000 |
a> | Greater Than | Shows results that are greater than the value you enter. | xAmount=a>20 |
an | Not In | Shows results that don’t have the value you enter. | xBillPhone=an212 |
as | Ends With | Use when you know what your value starts with. | xName=asJane |
ae | Ends With | Use when you know what your value ends with. | xEmail=aeOrg |
Reporting Fields
This is an optional field that can be sent in with any report to specify what fields you want to get back for a report.
Parameter | Description | Sample Value |
---|---|---|
xFields | Specify fields to be returned in the report. | xAmount, xAuthAmount, xCardType, xCommand, xEnteredDate, xExp, xMaskedAccountNumber, xMaskedCardnumber, xRefnum, xRefNumCurrent, xResponseError, xResponseResult, xToken |
- xCardLastFour
- xName
- xAmount
- xPONum
- xCardNum
- xCardLastSeven
- xOrderID
- xInvoice
- xTerminalNum
- xDescription
- xEmail
- xSourceKey
- xEngine
- xStatus
- xCustom01
- xCustom02
- xCustom03
- xResponseStatus
- xResponseResult
- xResponseError
- xResponseBatch
- xResponseRefNum
- xResponseAVSCode
- xResponseCVVCode
- xResponseAuthCode
- xBillCompany
- xPaymentType
- xCardType
Report Types
Available report types include the following:
Date-Based Reports
Report:Approved
The Report:Approved command returns the following transactions:
- CC:Sale
- CC:Capture
- CC:PostAuth
- CC:Save
- CC:Credit
- CC:Refund
The Report:Approved command does not return authorization-only transactions that have not been captured.
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xBeginDate | Transaction begin date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2020-01-01
2019-08-15 09:00:00 |
xEndDate | Transaction end date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2019-10-31
2020-06-30 12:00:00 |
Report:Declined
The Report:Declined command returns the following transactions:
- CC:Sale
- CC:AuthOnly
- CC:Capture
- CC:PostAuth
- CC:Save
- CC:Credit
- CC:Refund
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xBeginDate | Transaction begin date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2020-01-01
2019-08-15 09:00:00 |
xEndDate | Transaction end date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2019-10-31
2020-06-30 12:00:00 |
- report:authonly
Report:Auth
The Report:Auth command returns the following transaction:
- CC:AuthOnly
The ReportAuth command only returns approved authorizations.
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xBeginDate | Transaction begin date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2020-01-01
2019-08-15 09:00:00 |
xEndDate | Transaction end date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2019-10-31
2020-06-30 12:00:00 |
- report:all
Report:All
The Report:All command returns the following transactions:
- CC:Sale
- CC:AuthOnly
- CC:Capture
- CC:PostAuth
- CC:Save
- CC:Credit
- CC:Refund
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xBeginDate | Transaction begin date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2020-01-01
2019-08-15 09:00:00 |
xEndDate | Transaction end date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2019-10-31
2020-06-30 12:00:00 |
Note: You can run a report against all accounts by adding the search parameter xSecondaryKeys:[comma-delimited xKeys] and use all the xKeys for all accounts for the following date-based reports:
Parameter | Description | Sample Value |
---|---|---|
xSecondaryKey | Run a report for secondary accounts.
For multiple account keys, you can include comma-separated values. |
Bread_Butter_xxxdxxxecbxxxxaxxxdbexxx, Other_Account_xxxxfxxxexxfxxxfxbxxx, Yet_Another_Account_xxxbexaxxddxxbabbxexcxxxafxfexx |
Optional Field: xBatch:[batch#]to get only the transactions of a specific batch.
Transaction-Based Reports
Single transaction
- report:transaction
Report:Transaction
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xRefnum | Reference number
Multiple reference numbers are comma delimited This value is required only if you do not enter an Invoice number. |
r10000001
r10000001,r2000001,r3000001 |
Multiple transactions
- report:transactions
Report:Transactions
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xRefnum | Reference number
Multiple reference numbers are comma delimited This value is required only if you do not enter an Invoice number. |
r10000001
r10000001,r2000001,r3000001 |
xInvoice | Invoice number
Multiple invoice numbers are comma delimited This value is required only if you do not enter a Reference number. |
1234
1234,5678,9012 |
Report:Related
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xRefnum | Reference number
Multiple reference numbers are comma delimited This value is required only if you do not enter an Invoice number. |
r10000001
r10000001,r2000001,r3000001 |
Batch Report
Obtain batch summary by date
- report:batch
Report:Batch
Required Parameters
Parameter | Description | Sample Value |
---|---|---|
xBeginDate | Begin date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2020-01-01
2019-08-15 09:00:00 |
xEndDate | End date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2019-10-31
2020-06-30 12:00:00 |
Send a Receipt for a Completed Transaction
You can use the Reporting API feature to send a receipt for a completed transaction.
Reporting URL
Use the following Cardknox URL: https://x1.cardknox.com/report
Required Variables:
Parameter | Description | Comments |
---|---|---|
xKey | Credential | Max Size: 250 Alphanumeric Characters |
xVersion | Gateway API version | The current version is 4.5.8 |
xSoftwareName | The name of your software | |
xSoftwareVersion | Version number of your software | |
xCommand | Transaction type | Report:Transaction |
xRefnum | Reference number | |
xEmail | Email address of receipt destination |