Reporting API
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
Parameter
Description
Comment
xKey
Credential
Max Size: 250 Alphanumeric Characters
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
xReturnDownloadURL
A boolean flag indicating if response should include xReportURL to use for downloading the results instead of xReportData.
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.
Base URL:
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
Method: POST The Cardknox gateway requires the POST method to be used for enhanced security. We do not support the GET method.
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.
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
Parameter
Description
Sample Value
xFields
Specify parameters to be returned in the report.
xrefnum, xcommand, xname, xmaskedcardnumber, xtoken, xamount, xentereddate, Reportingxresponseresult
Available report types include the following:
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
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
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
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
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.
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.
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
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
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
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
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
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
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
You can use the Reporting API feature to send a receipt for a completed transaction.
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
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
Use the following Cardknox URL: