Skip to content

Reports for a shop

To get either a list or a number of all transactions processed for your shop by PayCross for a certain period of time, send report requests as described below.

The requests must:

Info

If you suppose that the requested report might contain more than 1000 transactions, it is strongly recommended using the pagination reports API.


Get a list of transactions

Request

Send a POST request to https://admin.pay-cross.com/api/reports with the additional X-Api-Version: 2 header and the following parameters:

required
object
A section of report parameters.
date_type
required
string
A date type.

Possible values:
created_at,
paid_at,
settled_at.
date
required
string
A date in the YYYY-MM-DD format, for example 2020-01-01.
status
required
string
A transaction status.

Possible values:
all,
successful,
failed,
pending,
incomplete.
payment_method_type
required
string
A payment method.

Possible values:
credit_card,
alternative.
time_zone
required
string
A timezone name as defined here, for example Europe/London.
Example of the request
{
  "report_params": {
      "date_type":"created_at",
      "date":"2022-01-27",
      "status":"failed",
      "payment_method_type":"credit_card",
      "time_zone":"Etc/UTC"
  }
}
Response
required
array
An array of transactions of the requested report. Each element represents a transaction property with its own set of fields depending on the payment type and payment method used in this transaction.
object
A section of the customer's address details.
first_name
string
The customer's first name.
last_name
string
The customer's last name.
country
string
The customer's billing country in ISO 3166-1 Alpha-2 format.
city
string
The customer's billing city.
state
string
The customer's billing state.
zip
string
The customer's billing ZIP or postal code. If country=US, zip format must be NNNNN or NNNNN-NNNN.
address
string
The customer's billing address.
phone
string
The customer's phone number.
birth_date
string
The customer's date of birth in ISO 8601 format YYYY-MM-DD.
object
A section of the customer information.
ip
string
The customer's IP address.
email
string
The customer's email.
object
gateway_id
integer
Gateway ID in the PayCross system.
auth_code
string
An authorization code provided by the acquirer.
bank_code
string
A transaction bank code.
rrn
string
A retrieval reference number. A transaction ID issued by the card processing service.
ref_id
string
A transaction reference ID provided by the acquirer.
message
string
A processing result message provided by the acquirer.
billing_descriptor
string
A billing descriptor assigned to the transaction.
status
string
A status of the processed transaction in the acquiring bank.
object
brand
string
The detected card brand.
product
string
A card product type code.
last_4
string
The last 4 digits of the card.
first_1
string
The first digit of the card.
exp_month
integer (2)
Card expiration month.
exp_year
integer (4)
Card expiration year.
bin
string (6)
6-digit bank identification number (BIN). The first 6 digits of the card number.
bin_8
string (8)
8-digit bank identification number (BIN). The first 8 digits of the card number. The value is returned for Visa, MasterCard, Maestro cards and the corresponding co-branded cards. Otherwise, null is returned.
issuer_country
string (2)
The country of the card issuing bank in ISO 3166-1 Alpha-2 format.
issuer_name
string
The name of the card issuing bank.
token
string
The card token.
object
id
integer
The identifier of the shop in the PayCross system.
uid
string
A UID of the processed transaction.
id
integer
The transaction identifier in the PayCross. This value is used for pagination.
payment_method_type
string
A payment method type used to make the transaction.
status
string
A status of the processed transaction.
message
string
Message with the transaction processing result.
gateway_note
string
The value of the Gateway note field in the gateway settings in PayCross system.
amount
bigInteger
A transaction amount in minimal currency units.
discount_rate
float
Transaction fee, in %.
transaction_rate
float
Fixed transaction fee in the transaction currency, in base currency units.
transaction_fee
float
Total amount of transaction fees, in minimal currency units.
pay_to_merchant
float
Amount to be paid to the merchant (after deducting acquirer, PayCross commissions, and security deposits) in minimal currency units.
test
boolean
If true, the transaction was a test one.
currency
string
Currency in ISO-4217 format.
description
string
The short description of the order.
tracking_id
string
The identifier of the transaction in the merchant's system.
type
string
A transaction type.
order_id
integer
An identifier of an order related to a transaction. The payment and the corresponding refund transaction will have the same order_id. The authorization and the corresponding capture and void transactions will also have the same order_id.
created_at
string
A time when the transaction was created at in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ.
paid_at
string
A time when the transaction was successfully completed at in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ. Set to null if the transaction is incomplete.
settled_at
string
A time when the acquiring bank settled the transaction amount to the merchant's current account in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ. Set to null if the parameter is not applicable to the transaction.
manually_corrected_at
string
A time when the transaction was manually updated at in the ISO 8601 format YYYY-MM-DDThh:mm:ss.SSSZ. Set to null if the parameter is not applicable to the transaction.
object
A section with 3-D Secure verification results.
eci
string or integer
Electronic Commerce Indicator. Provides information regarding merchant protection level against chargebacks requests by the cardholders or their banks.
pa_status
string
Status of payment authentication in the 3-D Secure protocol.
xid
string
Unique 3-D Secure authentication identifier.
cavv
string
Cardholder Authentication Verification Value (present only if the cardholder has been successfully authenticated).
cavv_algorithm
string
CAVV algorithm used for generating CAVV.
ve_status
string
Verification Enrollment Status which indicates whether the cardholder’s account is enrolled in the 3-D Secure program.
message
string
Message about 3-D Secure authentication status.
status
string
3-D Secure authentication status.
object
A section of detailed information about the transaction.
contract
array
The value used in the request. Possible values: recurring, card_on_file, oneclick, credit.
object
Section of customer browser parameters. Used only for 3DS 2.0.
accept_header
string
Value of Accept request HTTP header sent by the customer's browser.
screen_width
integer
Screen width in pixels. Equals the screen.width parameter in JavaScript.
screen_height
integer
Screen height in pixels. Equals the screen.height parameter in JavaScript.
screen_color_depth
integer
Screen color depth in bits per pixel. Equals the screen.colorDepth parameter in JavaScript. Applicable values are:

1 - 1 bit
4 - 4 bits
8 - 8 bits
15 - 15 bits
16 - 16 bits
24 - 24 bits
32 - 32 bits
48 - 48 bits.
window_width
integer
Browser window width in pixels. Equals the document.body.clientWidth parameter in JavaScript.
window_height
integer
Browser window height in pixels. Equals the document.body.clientHeight parameter in JavaScript.
language
string
Language of the navigator. Equals the navigator.language parameter in JavaScript.
java_enabled
boolean
Indicates if the browser is Java-enabled or not. Equals the navigator.javaEnabled() parameter in JavaScript.
user_agent
string
User agent string for the browser. Equals the navigator.userAgent parameter in JavaScript.
time_zone
integer
Time zone difference, in minutes, from the current locale (host system settings) to UTC. Equals the new Date().getTimezoneOffset() parameter in JavaScript.
challenge_window_size
integer
Recommended value for the 3-D Secure check window. Calculated using the values of window_width and window_height parameters. Possible values: 1, 2, 3, 4, 5.
time_zone_name
string
Time zone name. Equals the Intl.DateTimeFormat().resolvedOptions().timeZone parameter in JavaScript.
object
A section with 3-D Secure verification results.
status
string
3-D Secure authentication status.
message
string
Message about 3-D Secure authentication status.
ve_status
string
Verification Enrollment Status which indicates whether the cardholder’s account is enrolled in the 3-D Secure program.
acs_url
string
URL to the Access Control Server form (ACS form) in the card issuer's system to which the customer is redirected to complete 3-D Secure authentication.
pa_req
string
Payer Authentication Request, encoded.
md
string
Unique transaction identifier, used to link the merchant's server and the issuing bank's server.
pa_res_url
string
URL where the issuing bank’s server sends a response to the payment authentication request.
eci
string or integer
Electronic Commerce Indicator. Provides information regarding merchant protection level against chargebacks requests by the cardholders or their banks.
pa_status
string
Status of payment authentication in the 3-D Secure protocol.
xid
string
Unique 3-D Secure authentication identifier.
cavv
string
Cardholder Authentication Verification Value (present only if the cardholder has been successfully authenticated).
cavv_algorithm
string
CAVV algorithm used for generating CAVV.
fail_reason
string
Unencrypted message indicating the reason for 3-D Secure authentication failure.
method_process_url
string
URL for additional check based on the browser data.
creq
string
3-D Secure authentication request, encoded.
object
A section of AVS/CVC verification check.
object
A section of AVS verification check.
result_code
string
The code of AVS verification results.
object
A section of CVC verification check.
result_code
string
The code of CVC verification results.
object
A section of parameters of Smart Routing verification results.
status
string
Smart Routing check status for the transaction.
count
required
integer
A total number of transactions in the requested report.
Example of the successful response
{
    "transactions": [
        {
            "billing_address": {
                "first_name": null,
                "last_name": null,
                "address": null,
                "country": null,
                "city": null,
                "zip": null,
                "state": null,
                "phone": null,
                "birth_date": null
            },
            "customer": {
                "ip": "127.0.0.1",
                "email": null
            },
            "authorization": {
                "gateway_id": 2,
                "ref_id": null,
                "message": "Card check error",
                "status": "failed",
                "auth_code": null,
                "bank_code": null,
                "rrn": null,
                "billing_descriptor": null
            },
            "credit_card": {
                "holder": "JJJ",
                "token": "f1ed1ac4-875a-48bf-ae15-e2b2092969c1",
                "brand": "visa",
                "last_4": "0000",
                "first_1": "4",
                "bin": "420000",
                "issuer_country": "IT",
                "issuer_name": "INVESTBANK",
                "exp_month": 10,
                "exp_year": 2027,
                "product": "VISA"
            },
            "shop": {
                "id": 1
            },
            "uid": "20527-b7ea8c95f4",
            "id": 28859,
            "payment_method_type": "credit_card",
            "status": "failed",
            "message": null,
            "amount": 1000,
            "discount_rate": 1.0,
            "transaction_rate": 0.3,
            "pay_to_merchant": 960.0,
            "transaction_fee": 40.0,
            "test": false,
            "currency": "USD",
            "description": "Test description",
            "tracking_id": null,
            "type": "authorization",
            "order_id": 27723,
            "created_at": "2022-01-27T13:48:51Z",
            "paid_at": null,
            "settled_at": null,
            "manually_corrected_at": null,
            "additional_data": {
                "customer": {
                    "id": "b17727a9-0632-4454-b639-b941826be36f"
                },
                "request_id": "2a906819-5fbc-4dcb-8aaf-fe7ac17da248",
                "browser": {
                    "screen_width": 1440,
                    "screen_height": 900,
                    "screen_color_depth": 24,
                    "language": "it",
                    "java_enabled": false,
                    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36",
                    "time_zone": -180,
                    "time_zone_name": "Europe/London",
                    "window_height": 744,
                    "window_width": 600,
                    "accept_header": "application/json"
                },
                "vendor": {
                    "name": "CTP",
                    "token": "cb15c0e3d6419c24bda4823b5b32559a2f30c16cdbb30539ade2c449c7cd453c"
                },
                "tdsecure": {
                    "status": "failed",
                    "message": "Card check error",
                    "ve_status": "E",
                    "acs_url": null,
                    "pa_req": null,
                    "md": null,
                    "pa_res_url": "https://gateway.pay-cross.com/process/20527-b7ea8c95f4",
                    "eci": "07",
                    "pa_status": null,
                    "xid": null,
                    "cavv": null,
                    "cavv_algorithm": null,
                    "fail_reason": null,
                    "method_process_url": null
                },
                "avs_cvc": {
                    "avs_verification": {
                        "result_code": null
                    },
                    "cvc_verification": {
                        "result_code": null
                    }
                }
            },
            "three_d_secure_verification": {
                "eci": "07",
                "pa_status": null,
                "xid": null,
                "cavv": null,
                "cavv_algorithm": null,
                "ve_status": "E",
                "message": "Card check error",
                "status": "failed"
            }
        },
        {
            "billing_address": {
                "first_name": "Jane",
                "last_name": "Smith",
                "address": "Gilbert 104",
                "country": "IT",
                "city": "Milan",
                "zip": null,
                "state": null,
                "phone": null,
                "birth_date": null
            },
            "customer": {
                "ip": "127.0.0.1",
                "email": "[email protected]"
            },
            "p2p": {
                "gateway_id": 2,
                "ref_id": null,
                "message": "Can't make",
                "status": "failed",
                "auth_code": null,
                "bank_code": null,
                "rrn": null,
                "billing_descriptor": null
            },
            "credit_card": {
                "holder": "Dof Hag",
                "token": "a1e442d1-0633-4f48-b6ab-4dc36d71356d",
                "brand": "master",
                "last_4": "0707",
                "first_1": "5",
                "bin": "515464",
                "issuer_country": null,
                "issuer_name": null,
                "exp_month": 6,
                "exp_year": 2027,
                "product": null
            },
            "shop": {
                "id": 1
            },
            "uid": "20532-cb06cfeeed",
            "id": 28864,
            "payment_method_type": "credit_card",
            "status": "failed",
            "message": null,
            "amount": 100,
            "discount_rate": 0.0,
            "transaction_rate": 0.0,
            "pay_to_merchant": 0.0,
            "transaction_fee": 0.0,
            "test": false,
            "currency": "USD",
            "description": "Test transaction",
            "tracking_id": "tracking_id_000",
            "type": "p2p",
            "order_id": 27728,
            "created_at": "2022-01-27T15:03:01Z",
            "paid_at": null,
            "settled_at": null,
            "manually_corrected_at": null,
            "additional_data": {
                "tdsecure": {
                    "status": "successful",
                    "message": "Authentication Successful",
                    "ve_status": "Y",
                    "acs_url": null,
                    "pa_req": null,
                    "md": null,
                    "pa_res_url": "https://gateway.pay-cross.com/process/20532-cb06cfeeed",
                    "eci": "02",
                    "pa_status": "Y",
                    "xid": "8GamGXlGw6o2QTwXDd2cjz70qr0=",
                    "cavv": "ADlWFgxrq8BtAU6/rKnuAoABFA==",
                    "cavv_algorithm": null,
                    "fail_reason": null,
                    "method_process_url": null
                },
                "verify_p2p": {
                    "status": "failed",
                    "message": "Can't make",
                    "amount": 100,
                    "currency": "USD",
                    "bank_fee": 0.0,
                    "required_fields": {
                        "p_id": null
                    }
                }
            },
            "three_d_secure_verification": {
                "eci": "02",
                "pa_status": "Y",
                "xid": "8GamGXlGw6o2QTwXDd2cjz70qr0=",
                "cavv": "ADlWFgxrq8BtAU6/rKnuAoABFA==",
                "cavv_algorithm": null,
                "ve_status": "Y",
                "message": "Authentication Successful",
                "status": "successful"
            },
            "recipient_card": {
                "holder": "Qwert Qwerty",
                "token": "516638c8-a113-4061-97a1-a58874cd9cd2",
                "brand": "visa",
                "last_4": "3101",
                "first_1": "4",
                "bin": "401200",
                "issuer_country": null,
                "issuer_name": null
            }
        }
    ],
    "count": 2
}

Count the number of transactions for a shop

Request

Send a POST request to https://admin.pay-cross.com/api/reports/count with the additional X-Api-Version: 3 header and the following parameters:

required
object
A section of report parameters.
date_type
required
string
A date type.

Possible values: created_at, paid_at, settled_at.
from
required
string
A start date of the reporting period in the YYYY-MM-DD hh:mm:ssformat, for example 2020-01-01 12:00:00.
to
required
string
An end date of the reporting period in the YYYY-MM-DD hh:mm:ss format, for example 2020-01-01 15:00:00.
status
required
string
A transaction status.

Possible values:
all,
successful,
failed,
pending,
incomplete.
payment_method_type
required
string
A payment method.

Possible values:
credit_card,
alternative.
time_zone
required
string
A timezone name as defined here, for example Europe/London.
Example of the request
{
  "report_params": {
      "date_type":"created_at",
      "from":"2022-01-25 00:00:00",
      "to":"2022-01-27 23:59:59",
      "status":"incomplete",
      "payment_method_type":"credit_card",
      "time_zone":"Etc/UTC"
  }
}
Response
object
count
required
integer
A total number of transactions in the requested report.
Example of the response
{
    "transactions": {
        "count": 2
    }
}