Reporting API
Overview
The Cardknox Reporting API enables you to generate transaction reports based on specified parameters, such as date ranges. Reports can be created for single accounts or multiple accounts.
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 5.0.0 |
xSoftwareName | The name of your software | |
xSoftwareVersion | Version number of your software | 2.1 |
xCommand | Transaction type | Samples: report:all, report:approved |
Other Parameters
| Parameter | Description | Comment |
|---|---|---|
xReturnDownloadURL | A boolean flag indicating if response should include | If you are running reports that are returning more than 5MB of data we recommend that you use this parameter. The URL returned is valid for 5 minutes. |
Endpoints
Base URL: https://x1.cardknox.com
Cardknox reporting API allows you to send the data in FormData and JSON formats. Add to the base URL any of the following formats to indicate which format you are sending it as:
FormData | /report | |
JSON | /reportjson |
Request Method
Method: POST The Cardknox gateway requires the POST method to be used for enhanced security. We do not support the GET method.
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 do not include your search string, but sometimes also include other information. | xCardLastFour=a!4444 |
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 |
Customize report parameters
To customize the transaction parameters included in a generated report, you can utilize the "xFields" parameter and specify the desired field names. Refer to the available parameters listed here
Parameter | Description | Sample Value |
xFields | Specify parameters to be returned in the report. | xrefnum, xcommand, xname, xmaskedcardnumber, xtoken, xamount, xentereddate, Reportingxresponseresult |
Report Types
Available report types include the following:
Date-Based Reports
Report:Approved
xCommand: 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
xCommand: 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:Auth
xCommand: ReportAuth
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
xCommand: 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 |
xSecondaryKeys | 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.
Report:Deposit
xCommand: Report:Deposit
The Report:Deposit command will only return valid responses for accounts that have ongoing ACHQ activity. The Deposit ID given as a parameter must be an ACHQ deposit ID and the values shown in the response are only pertaining to ACHQ transaction activity.
The Report:Deposit command returns the following values:
Deposit Id
Deposit Date
Total Amount
Transactions
Refnum
Amount
Required Parameters
Parameter | Description | Sample Value |
xDepositId* |
|
|
xBeginDate* | Begin date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2020-01-01 2019-08-15 09:00:00 |
xEnd Date* | End date in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format | 2019-10-31 2020-06-30 12:00:00 |
*Either xDepositId or xBeginDate and xEndDate are required.
Transaction-Based Reports
Single transaction
report:transaction
xCommand: 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
xCommand: 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 |
Related Transactions
xCommand: 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 |
Gift:Approved
xCommand: Report:GiftApproved
Required Parameters
xKey | Your Cardknox API key | Max Size: 250 Alphanumeric Characters |
xCommand | Cardknox transaction type | Report:GiftApproved |
xBeginDate | Beginning date of range | 2020-01-01 2019-08-15 09:00:00 |
xEndDate | Ending date of range | 2020-01-01 2019-08-15 09:00:00 |
xSoftwareName | Name of your software | [xsoftwarecredentials] |
xSoftwareVersion | Version number of your software | The current version is 4.5.8 |
xFields | Optional. If not used, returns all fields |
|
Response Fields
xResult | “A” |
xStatus | “Approved” |
xError | ““ |
xRefNum | "10000016875" |
xRecordsReturned | “20” |
xReportData |
|
Gift:Summary
xCommand: Report:GiftSummary
Required Parameters
xKey | Your Cardknox API key | [xkeycredentials] |
xCommand | Cardknox transaction type | Report:GiftSummary |
xBeginDate | Beginning date of range | 2020-01-01 2019-08-15 09:00:00 |
xEndDate | Ending date of range | 2020-01-01 2019-08-15 09:00:00 |
xSoftwareName | Name of your software | [xsoftwarecredentials] |
xSoftwareVersion | Version number of your software | The current version is 4.5.8 |
xFields | Optional. If not used, returns all fields |
|
Response Fields
xResult | “A” |
xStatus | “Approved” |
xError | ““ |
xRefNum | "10000016875" |
xRecordsReturned | “20” |
xReportData |
|
Liability
xCommand: Report:Liability
Required Parameters
xKey | Your Cardknox API key | [xkeycredentials] |
xCommand | Cardknox transaction type | Report:Liability |
xSoftwareName | Name of your software | [xsoftwarecredentials] |
xSoftwareVersion | Version number of your software | The current version is 4.5.8 |
Response Fields
Parameter | Example |
xResult | “A” |
xStatus | “Approved” |
xError | ““ |
xRefNum | "10000016875" |
xRecordsReturned | “20” |
xReportData |
|
Batch Report
Obtain batch summary by date
report:batch
xCommand: 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 |
Last updated