Create Reports

A guide to using the PayConex Reporting Services API to create transaction reports.

The Bluefin Reporting Service API (RSAPI) responds to requests with a report of all transactions for a given day or a range of dates.

Responses from the API can be provided in CSV, JSON, or XML formats. For security and PCI compliance the reporting data will contain no card/account numbers, PIN blocks, or card verification values.


For the certification test environment:

For the production environment:

Reporting API Requests and Timing Considerations

Because some data is reconciled with financial institutions nightly the most recent date a report should be run is from previous business day.

If you plan on running automated reports for multiple single dates, the suggested time to run these reports is between 4:00 AM – 6:00 AM Eastern. This time range should give you optimal server response time and should allow enough time for the previous day's records to reconcile from any West Coast entities.

Reporting Services API Examples

Report for a specific day

This example uses the transaction_date parameter to get a complete list of transactions for the date of 2021-07-04 (YYYY-MM-DD formatting required).

curl --request POST \
  --url \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data response_format=JSON \
  --data transaction_date=2021-08-10


Notes on the 'date' variables.

Using, or including, the start_date and end_date variables will override a transaction_date value, even if start_date is blank. The start_date and end_date variable combination should be used for getting data for a date range, and transaction_date should be used for getting data for a particular date.

Report for a range of dates

This example uses the start_date and end_date parameters to get all transactions that occurred between the two given dates.

curl --request POST \
  --url \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data start_date=2021-08-10 \
  --data end_date=2021-08-12 \
  --data response_format=JSON


Did you know?

If you specify a start_date but include no end_date variable or value, it is assumed that you want all transactions from the “start_date” to today (now).

If you specify an end_date but include no value for start_date, it is assumed that you want all transactions from your account start date up to the end_date.

Report for a single transaction

In some cases a full list of transactions is not needed. If you have a transaction_id value in your system and need more information you can send a request to the API for that transaction's full details.

curl --request POST \
  --url \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data response_format=JSON \
  --data transaction_id=000000101161

Wildcard Searches

Wildcard searches are possible for the transaction_date, action_date, group, cashier, custom_id, and name variables. By default all parameters are treated as exact matches. A question mark (?) is used for a SINGLE missing character, and an asterisk (*) specifies zero or more unknown characters.

curl --request POST \
  --url \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data start_date=2021-08-10 \
  --data end_date=2021-08-12 \
  --data response_format=JSON \
  --data 'name=T*'

Date/Time Wildcard Search

Wildcard searching is also possible for the transaction_date parameter.

These wildcard searches are formatted similarly to regular wildcard searches with * or ? characters.

For example, here the day value is replace by ?? to provide transactions from any day of the specific month: transaction_date=2018-08-??

Here is an example of a transaction_date formatted with a timestamp where the hour is known and the wildcard search is on minutes and seconds: transaction_date=2018-08-22 14:*:*.

curl --request POST \
  --url \
  --cookie BLUEFINA=rd4o00000000000000000000ffffac128117o443 \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data response_format=JSON \
  --data 'transaction_date=2021-08-12 20:*:*'


Did you know?

Reports can also be requested using variables such as custom_id, card_brand, group etc... For a full list of parameters that can be used please see the API Request Format table.

ACH Reporting

It is important to note that ACH transactions are processed by banks differently than credit cards. While credit card transactions respond with approvals or declines immediately, ACH transactions are submitted in daily batches. The banking and financial institutions often take multiple business days to respond with a status to an ACH transaction.

If you are running reports to capture your previous day’s transactions, ACH transactions will show “BATCHED” in the “transaction_date” records. This indicates that the ACH transaction was successfully sent at the end of the business day to the processor.

Since the time for an ACH transaction reply can vary, we suggest running a separate daily report to determine what updates (if any) were made by the financial institutions. To run this report use the action_date parameter.

When the action_date parameter is used the API will only respond with ACH transactions that had a status update on the date value provided in the action_date. This means if there are ACH transactions processed in different batches they could be all be updated on the same action_date and included in the report.

Here is a full example request:

curl --request POST \
  --url \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data response_format=JSON \
  --data action_date=2020-07-20

Handling Report Responses

Responses from the reporting API can be provided in CSV, JSON, or XML formats by setting the response_format parameter.

Here is an example JSON response for a single transaction report:

  "api": "RSAPI",
  "version": "3.8",
  "count": 1,
  "transactions": [
      "transaction_id": "000000101161",
      "account_id": "220614966801",
      "authorization_date": "2021-08-12 20:53:13",
      "time_zone": "MDT",
      "tender_type": "CARD",
      "transaction_type": "SALE",
      "keyed": true,
      "swiped": false,
      "transaction_amount": 1,
      "name": null,
      "card_brand": "VISA",
      "last4": "9990",
      "card_expiration": "1230",
      "description": null,
      "user_data": null,
      "authorization_msg": "APPROVED",
      "authorization_code": "332363",
      "avs_response": null,
      "cvv2_response": "N",
      "ip_address": null,
      "cashier": "QSAPI 3.8",
      "street_address1": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone": null,
      "email": null,
      "group": null,
      "refund_id": null,
      "refund_balance": "0.00",
      "custom_id": null,
      "action_date": null,
      "noc_data": null,
      "recurring_id": null,
      "input_group": null,
      "invoice_entry": "",
      "trace_num": "000000088401",
      "company": null,
      "entry_mode": "keyed"

The API responds with headers that provide information about the response format and MIME/Type.

For example, for CSV files, the HTTP Header will include: Content-type: text/csv

A custom response code is also provided within the HTTP header: QS-response-code: NNN Message

For error conditions (Response Codes other than 100), a human-readable error message will be returned as the body of the response: QS-response-code: 601 Authentication failed Account number and/or API access key is missing or invalid.. A list of these response codes can be found at the bottom of this page in the RSAPI HTTP Response Format table.


Did you know?

In combination with the Reporting Service API, PayConex provides a webhook called POSTback. POSTback allows a developer to receive an HTTP POST after every transaction request. For more information, please see our POSTback guide.

RSAPI Request Format

The following table includes an index of all API request posts for RSAPI.

Variable NameMaxTypeReq'dDescription
account_id12NumericYesThis is the Payconex account identification number that you are issued after your account has been set up.
ach_settle_date10YYYY-MM-DD HH:MM:SSNoUsed for getting all ACH transactions with the value supplied. The value for tender_type must be ACH when using this.
action_date10YYYY-MM-DD HH:MM:SSNoDownload transactions with this action date (for ACH only; default: yesterday). This is useful for viewing ACH updated transactions on a specific date.
amount10DecimalNoThe amount of the original transaction. Must be zero or positive decimal numbers.
amount_max10DecimalNoThe maximum amount of a transaction amount range. Use with amount_min. Must be zero or positive decimal numbers.
amount_min10DecimalNoThe minimum amount of a transaction amount range. Use with amount_max. Must be zero or positive decimal numbers.
api_accesskey32AlphanumericYesThis is a secret key that you will be provided when your Payconex account is set up and when you’ve requested access to QSAPI.
batch_detail1BooleanNoIf sent as "1", batch number and batch date/time will be returned.
cashier100AlphanumericNoThe cashier that created the original transaction.
custom_id50AlphanumericNoAny custom text value that may have been used.
date1EnumeratedNoValue can be either "ACTION" or "BATCH".

ACTION = will return ACH records with action_date in the range (similar to using action_date with its single value)

BATCH = will return records with a batch_date in the range.
end_date10YYYY-MM-DD HH:MM:SSNoUsed for getting transactions in a date range. Use with start_date.
group25AlphanumericNoGroups can be used flexibly for various reasons, including a) assign transactions to a specific group. b) direct transactions to separate back-end or depository accounts.
include_ach_settle_date1BooleanNoIf sent as "1", the ACH transactions settle date will be returned.
name100AlphanumericNoThe name used for the customer on the original transaction.
reportable_fields1BooleanNoIf sent as "1", any reportable field values from HPF (Hosted Payment Forms) will be added to the end of the RSAPI response, with column names matching account setup.
response_format4EnumeratedNoHow the resulting data is returned.

Valid options are:

- CSV: Comma-separated value formatted file (default)
- JSON: JavaScript Object Notation formatted file.
- XML: Extended markup language formatted file.
start_date 10YYYY-MM-DD HH:MM:SSNoUsed for getting transactions in a date range. Use with end_date.
status8EnumeratedNoValue can be either "APPROVED" or "DECLINED" which will return matching transactions. If omitted, BOTH types will be returned.
tender_type4EnumeratedNoPayment type to include in the report:

Allowed values:

- ALL (default)
transaction_typeEnumeratedNoType of transaction to return as part of the resulting report.

Valid values can be:

- SALE/Decline
transaction_date19YYYY-MM-DD HH:MM:SSNoDownload transactions run for this date (default: yesterday).
transaction_id12NumericNoThe transaction ID for a specific transaction.

RSAPI Response Format

The following table includes an index of all API responses for RSAPI.

account_id12NumericThe account ID for the transactions
ach_return_code4alphanumericThe ACH Return Code for ACH transactions. Will only be included for ACH transactions that have cleared and batched (could be up to 5 days depending on the banks).
ach_settle_date16CharacterThe date and time of the ACH transactions settlement. May be empty if not included in a batch yet. Can be used with action_date value if a transaction was returned to get more historical info. ONLY returned if include_ach_settle_date=1 was submitted.
action_date10Date (YYYY-MM-DD)The action date indicates that an ACH update has been applied to a previous ACH transaction. A status response to an ACH settlement takes days to receive. By using action_date and the date you wish to check you can see what ACH transactions have been updated on a specific day. Responses are:

authorization_code6AlphanumericThe authorization code returned by the processor.
authorization_date19YYYY-MM-DD HH:MM:SSThe date and time when the transaction was initiated (YYYY-MM-DD HH:MM:SS)
authorization_msg50AlphanumericAPPROVED or the auth message from the processor (e.g. AUTH DECLINED 200).
avs_response1EnumeratedA single letter address verification response:

- DFJMQVXY - Address and ZIP code match
- LWZ - ZIP code match, address is wrong
- ABOP - Address match, ZIP code is wrong
- KN - No match, address and ZIP is wrong
- U - No data from issuer/banknet switch
- R - AVS System unable to process
- S - Issuing bank does not support AVS
- E - Error, AVS not supported for your business
- C - Invalid address and ZIP format (International)
- I - Address not verifiable (International)
- G - Global non-verifiable address (International)
- ? - Unrecognized codes (none of the above)
- _ - No AVS data (blank)
batch_date16CharacterThe batch date and time of the transaction. May be empty if not included in a batch yet. ONLY returned if batch_detail=1 was submitted.
batch_id4NumericThe batch number (ID) of the transaction. May be empty if not included in a batch yet. ONLY returned if batch_detail=1 was submitted.
card_brandn/aEnumeratedCustomers brand of card used. VISA, MASTERCARD, AMERICAN EXPRESS, DISCOVER, ACH, EBT.
card_expiration4NumericThe month and year of the card expiration date in the format MMYY. For example, 0115 for January 2015.
cashier100CharacterThe cashier value from the transaction
city100CharacterCustomer’s city
company50StringCompany name field from the transaction
country3AlphanumericCustomer’s country
custom_id50CharacterCustom ID value from the transaction.
cvv2_response1EnumeratedSingle letter card verification value response:

- M - CVV match
- N - CVV does not match
- P - CVV not processed
- S - Card has CVV, customer says it doesn't
- U - No CVV data from issuer
- ? - Unrecognized codes (none of the above)
- _ - No CVV data (blank)
description65KCharacterThe description entered in the transaction_description.
email100CharacterCustomer’s email that was sent as part of a transaction.
entry_mode17EnumeratedThe value of the entry mode from the transaction:

group12AlphanumericGroup value from the transaction
input_group10CharacterInput group from the transaction
invoice_entry65kCharacterConcatenated list of invoice line description and amounts, each separated by &, when invoice feature is used for transactions.
ip_address15NNN.NNN.NNN.NNNIP address of the client which initiated the transaction.
keyed1Enumerated1 indicates key entry of card information, 0 indicates not a keyed entry.
last44NumericThe last four digits of the card number or Primary Account Number (PAN). For ACH, it is the last four digits of the account number.
name100CharacterCustomer name
noc_data50CharacterThe NOC data from the transaction
phone20AlphanumericCustomer’s phone
recurring_id12NumericThis unique identifier is provided in addition to the transaction ID to allow for identifying and segmenting recurring transactions. This variable is in version 3.6.1 and higher.
refund_balance9DecimalRefund balance (if applicable) from the transaction
refund_id12 NumericRefund ID from the transaction (length may be longer if multiple refunds were run, all refund transaction id's separated by a pipe indicator)
Reportable Fields?CharacterIf "reportable_fields" was set to "1" and there are reportable fields on the HPF (Hosted Payment Form), those columns will be included at the end of the response.
state2AlphanumericCustomer’s state
street_address150CharacterCustomer’s street address
swiped1Enumerated1 indicates swiped entry of card information, 0 indicates not a swiped entry.
tender_type4EnumeratedThe method of transaction that was made: CARD, ACH, EFT, EBT, USDA, FNS, GIFT.
time_zone3CharacterThis is a timezone indicator for the RSAPI fields that contain actual times. Would be similar to EST, CST, etc (batch_date will ALWAYS be in CST)
trace_num12IntegerBack-end transaction number that might be used by some end processors for reporting or communication.
transaction_amount9Numeric w/ decimalAmount of funds involved in the transaction.
transaction_id12NumericThe transaction ID for the new transaction. When using tokenization, this is the transaction_id that you submit as the token_id.
transaction_type14EnumeratedType of transaction to return as part of the resulting report.

Valid values can be:

- SALE/Decline
user_data65KCharacterUser data entered in the transaction. Originates from the QSAPI variable "custom_data".
zip10Numeric with hyphenCustomer’s zip

HTTP Response Codes

In addition to the RSAPI responses shown above, in the HTTP header of the response, you will find another piece of data that you may wish to capture, called QS-response-code. An example of an HTTP header for a RSAPI request is similar to the following:

HTTP/1.1 200 OK Date: Tue, 03 Aug 2013 12:23:05 GMT Server: Apache QS-response-code: 601 Authentication failed Connection: close Vary: Accept-Encoding,User-Agent Content-Encoding: gzip X-Frame-Options: SAMEORIGIN Cache-Control: private, no-cache, no-store, proxy-revalidate, no-transform Pragma: no-cache Content-Length: 63 Content-Type: text/html; charset=UTF-8

Values for the QS-response-code variable (Code and Message concatenated) are as follows:

Response CodeResponse MessageDescription
100OKSuccess. Report file follows.
601Authentication FailedAccount number and/or API access key is incorrect.
607Invalid DateDate format is incorrect (YYYY-MM-DD) or invalid date (2009-02-31).
608No DataNo data or transactions matched the search criteria.
611Data UnavailableA temporary system error has prevented access to the data requested. Please try again later or contact administrator.
621Invalid ParameterOne or more parameters do not match the RSAPI Request Format specification.
622Missing ParameterOne or more required parameters are missing.
623Conflicting ParametersCombination of parameters is invalid (e.g., specifying action_date for card transactions).

If QS-response-code is NOT equal to “100 OK”, then you will receive the Description from above in the actual response from your request.

Report Pagination

The ReportingService API (RSAPI) provides a robust pagination mechanism that allows developers to fetch transaction records in manageable chunks. This guide outlines how to implement pagination in your application when interacting with the Reporting Service API.

Pagination Parameters

When requesting paginated data, you can control the results using the following parameters:

  • page: Identifies the page number in the sequence of paginated results. Defaults to 1 if not specified.
  • page_size: Indicates the number of records per page, with the maximum limit set at 2500. This parameter is required for pagination.
  • pagination_outset: An optional parameter representing the transaction ID from which to begin pagination.

Making Paginated Requests

To start, you need to specify the page_size. In the example below each page will return a set of 100 records.

The page parameter can be omitted on the initial request. The default response will be the first page of results.

Example: Initial Request

curl --request POST \
  --url '' \
  --header 'content-type: multipart/form-data' \
  --form account_id=your_account_id \
  --form api_accesskey=your_api_key \
  --form 'start_date=2013-01-01' \
  --form response_format=JSON

Navigating Paginated Responses

The response to the initial API request above will include headers to assist with navigation through the paginated data:

  • X-TOTAL-PAGES: The total number of pages.
  • X-TOTAL-RECORDS: The total count of records that match your query.
  • Link: URLs for the first, previous, next, and last pages.

In the response to the API request above below are the values recieved for those headers:

The Link Header

The Link header follows the RFC-8288 standard, offering navigational URLs. For subsequent requests you can simply use the URLs provided in the Link header with your account credentials to paginate through the dataset.

Example: Subsequent Request

curl --request GET \
  --url ''

Managing Data Consistency

While pagination_outset is optional, it is particularly useful for ensuring data consistency in environments with a high transaction volume. By setting this parameter to the ID of the last transaction received, you create a fixed reference point for pagination. This prevents new transactions from altering the dataset you're iterating over, which could otherwise result in missing or duplicated transaction entries in the paginated output.

Considerations for pagination_outset

  • When to Use: Implement this parameter when transaction data is frequently added, and consistent ordering is required throughout the pagination process.
  • How It Works: pagination_outset locks the pagination sequence to the moment when the first page is fetched, ensuring subsequent pages are not affected by new data.
  • Without pagination_outset: If not used, pagination will still function, but there is a risk of dataset changes between page requests.

Example: Using Pagination Outset

After receiving your first page of data with the transaction ID included, append the pagination_outset to your subsequent requests to maintain the dataset's integrity.

curl --request GET \
  --url ''

What’s Next

Follow these links to other API examples