Reporting API

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

  1. Submit the first request.
  2. 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

Reporting Fields

This is an option field that can be sent in with any report to specify what fields you want to get back for a report.

Name Type
xAmount
xAuthCode
xBillCity
xBillCompany
xBillCountry
xBillFirstName
xBillLastName
xBillMiddleName
xBillMobile
xBillPhone
xBillState
xBillStreet
xBillStreet2
xBillZip
xCardSource
xCardType
xCashbackAmount
xCCType
xClerkName
xClientIP
xCommand
xComments
xComputerName
xCoupon
xCurrency
xCustID
xCustNumber
xCustom01
xCustom02
xCustom03
xCustom04
xCustom05
xCustom06
xCustom07
xCustom08
xCustom09
xCustom10
xCustom11
xCustom12
xCustom13
xCustom14
xCustom15
xCustom16
xCustom17
xCustom18
xCustom19
xCustom20
xCustomerID
xCVMResult
xDescription
xEmail
xEngine
xEnteredDate
xEntryMethod
xExistingCustomer
xExternalTransactionID xRefnum_Engine that is returned by E25
xFraudResubmitted
xGatewayError
xGatewayResult
xHTMLReceipt
xInvoice
xIsDebit
xIsEMV
xIsSwiped
xIsTOR
xLegacyCardknox_Auto_Request
xLegacyCardknox_Charge
xLegacyCardknox_Charge_Client
xLegacyCardknox_Client
xLegacyCardknox_Client_Type
xLegacyCardknox_Ctype
xLegacyCardknox_Generate
xLegacyCardknox_Record_External_Transaction
xLegacyCardknox_SID
xLegacyCardknox_Submit
xLegacyCardknox_UID
xLoginName
xLoginPassword
xMaskedAccountNum
xMaskedCardNum
xMaskedCardNumber
xMerchantCity
xMerchantLogo
xMerchantName
xMerchantPhone
xMerchantState
xMerchantStreet
xMerchantStreet2
xMerchantZip
xName
xOOSIdentifier
xOOSRefnum
xOrderDate
xOrderID
xOrderType
xPaymentMethodID
xPaymentType
xPONum
xProcessingFee
xProcessor
xRatePercentage
xRequest_Client_IP
xRequestAmount
xResponseAuthCode
xResponseAVSCode
xResponseBatch
xResponseCVVCode
xResponseEMVData
xResponseError
xResponseRefnum
xResponseResult
xScheduleID
xScoreOnly
xSerialNumber
xServiceFee
xShipAmount
xShipCity
xShipCompany
xShipCountry
xShipEmail
xShipFirstName
xShipLastName
xShipMethod
xShipMiddleName
xShipMobile
xShipPhone
xShipState
xShipStreet
xShipStreet2
xShipZip
xSignature
xSoftwareName
xSourceKey
xSplitAmount
xStatus
xStatusReason
xStreet
xSubtotal
xTag4F
xTag50
xTag5F2A
xTag5F34
xTag82
xTag95
xTag9A
xTag9B
xTag9C
xTag9F02
xTag9F03
xTag9F07
xTag9F0D
xTag9F0E
xTag9F0F
xTag9F10
xTag9F12
xTag9F1A
xTag9F21
xTag9F26
xTag9F27
xTag9F34
xTag9F36
xTag9F37
xTax
xTerminalNum
xTip
xToken
xUsername
xVersionAPI
xWebsite
xZip

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.

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:

  • report:declined
  • 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:authonly
xCommand:

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
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

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

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

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

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