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

API URLs

For the certification test environment:

https://cert.payconex.net/api/rsapi/3.8

For the production environment:

https://secure.payconex.net/api/rsapi/3.8

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 https://cert.payconex.net/api/rsapi/3.8 \
  --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 https://cert.payconex.net/api/rsapi/3.8 \
  --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 https://cert.payconex.net/api/rsapi/3.8 \
  --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 https://cert.payconex.net/api/rsapi/3.8 \
  --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 https://cert.payconex.net/api/rsapi/3.8 \
  --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.

Include Fields

Including fields allows you to specify the data elements of your transaction report. This setting is optional and it is important in the reporting process in case the desired fields aren't returned by default.

Table Of Fields

This is the comprehensive list of all the fields that can be included. To check out the description of most of these fields, see RSAPI Response Format.

List Of Transactions

In a POST request, the include_fields field is applied to the body.

For example,

curl -X POST --location 'https://cert.payconex.net/api/rsapi/3.8' \
--form 'account_id=220614966801' \
--form 'api_accesskey=32d42f0f0b6c89616d42aed8c96801e6' \
--form 'response_format="JSON"' \
--form 'start_date=2024-08-10' \
--form 'end_date=2024-09-12' \
--form 'response_format=JSON' \
--form 'include_fields=transaction_id,digital_wallet_type,scx_token_bank_account_number,bfid'

or

curl -X POST --location 'https://cert.payconex.net/api/rsapi/3.8' \
--data account_id=220614966801 \
--data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
--data response_format=JSON \
--data start_date=2024-08-10 \
--data end_date=2024-09-12 \
--data response_format=JSON \
--data include_fields=transaction_id,digital_wallet_type,scx_token_bank_account_number,bfid

In a GET request, the include_fields field can be used as part of a URL query as shown in this curl example:

curl --request GET \
  --url 'https://cert.payconex.net/api/rsapi/3.8?start_date=2024-08-01&response_format=JSON&order_field=transaction_id&order_direction=DESC&page=3&page_size=100&account_id=220614966801&api_accesskey=32d42f0f0b6c89616d42aed8c96801e6&include_fields=transaction_id,digital_wallet_type,description'

Single Transaction

This option can also be applied to a single transaction.

For example,

curl --request POST \
  --url https://cert.payconex.net/api/rsapi/3.8 \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data response_format=JSON \
  --data transaction_id=000000004687 \
  --data include_fields="transaction_id,description,last4"

Note that even if these fields aren't available in a transaction, they will be assigned null or "".

Response:

{
  "api": "RSAPI",
  "version": "3.8",
  "count": 1,
  "transactions": [
    {
      "transaction_id": "000000004687",
      "account_id": "220614966801",
      "authorization_date": "2024-08-01 08:25:13",
      "tender_type": "CARD",
      "transaction_type": "SALE",
      "transaction_amount": 40,
      "last4": "1111",
      "description": null
    }
  ]
}

If only one field is specified, a transaction is filled with the necessary fields by default.

For example, include_fields=description.

{
  "api": "RSAPI",
  "version": "3.8",
  "count": 1,
  "transactions": [
    {
      "transaction_id": "000000004687",
      "account_id": "220614966801",
      "authorization_date": "2024-08-01 08:25:13",
      "tender_type": "CARD",
      "transaction_type": "SALE",
      "transaction_amount": 40,
      "description": null
    }
  ]
}

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 https://cert.payconex.net/api/rsapi/3.8 \
  --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.

RSAPI Response Format

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

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:

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 'http://cert.payconex.net/api/rsapi/3.8?page_size=100' \
  --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 'https://cert.payconex.net/api/rsapi/3.8?start_date=2013-01-01&response_format=JSON&order_field=transaction_id&order_direction=DESC&page=2&page_size=100&account_id=your_account_id&api_accesskey=your_api_accesskey'

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 'https://cert.payconex.net/api/rsapi/3.8?start_date=2013-01-01&response_format=JSON&order_field=transaction_id&order_direction=DESC&page=3&page_size=100&account_id=your_account_id&api_accesskey=your_api_accesskey&pagination_outset=000000223686'