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.

  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

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

Expand to See All Reporting Fields

Report Types

Available report types include the following:

Date-Based Reports

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

  • report:authonly

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

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

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

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

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

​