Pagination reports API

If you suppose that the requested report might contain a large number of transactions, use the pagination report API.

Request

Send the report request with the additional X-Api-Version: 3 request header and the following parameters:

report_params 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:ss format, for example 2020-01-01 12:00:00. For the settled_at date type, set the date in the YYYY-MM-DD format. 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. For the settled_at date type, set the date in the YYYY-MM-DD format. 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. time_zone required string A timezone name as defined here, for example Europe/London starting_after string Forward pagination parameter. Accepts value last_object_id from the response. ending_before string Reverse pagination parameter. Accepts value first_object_id from the response. manual_correction_from string A start date of the reporting period with manually edited transactions in the YYYY-MM-DD hh:mm:ss format, for example 2020-01-01 12:00:00. manual_correction_to string An end date of the reporting period with manually edited transactions in the YYYY-MM-DD hh:mm:ss format, for example 2020-01-01 15:00:00.

Example of the request

{
  "report_params": {
      "date_type":"created_at",
      "from":"2020-09-11 00:00:00",
      "to":"2020-09-11 23:59:59",
      "status":"successful",
      "payment_method_type":"credit_card",
      "time_zone":"UTC"
  }
}

Response

transactions required array An array of transactions for the requested report. The number of elements must be the same as in the count section. Each element represents a transaction entity with its own set of fields depending on the payment type and payment method used in this transaction. billing_address 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. customer object A section of the customer information. ip string The customer's IP address. email string The customer's email. {transaction-type} object gateway_id integer Gateway ID in the Forte E-commerce 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. credit_card 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. shop object id integer The identifier of the shop in the Forte E-commerce system. uid string A UID of the processed transaction. id integer The transaction identifier in the Forte E-commerce. 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 Forte E-commerce 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, Forte E-commerce 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. three_d_secure_verification 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. additional_data 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. browser 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. tdsecure 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. avs_cvc object A section of AVS/CVC verification check. avs_verification object A section of AVS verification check. result_code string The code of AVS verification results. cvc_verification object A section of CVC verification check. result_code string The code of CVC verification results. smart_routing_verification 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. has_more required boolean true - indicates that there are more transactions which meet the request parameters, but are not included in the response. false - indicated that all transactions which meet the request parameters are included in the response. first_object_id required string An ID of the first object returned in the response. last_object_id required string An ID of the last object returned in the response.

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
            },
            "payment": {
                "gateway_id": 312,
                "ref_id": null,
                "message": null,
                "status": "incomplete",
                "gateway_name": "Demo",
                "auth_code": null,
                "bank_code": null,
                "rrn": null,
                "billing_descriptor": null
            },
            "credit_card": {
                "holder": "JJJJ",
                "token": "544ffa4a-d16f-4ebb-b390-d997c29858c9",
                "brand": null,
                "last_4": "0000",
                "first_1": "4",
                "bin": "420000",
                "issuer_country": "IT",
                "issuer_name": "INVESTBANK",
                "exp_month": 12,
                "exp_year": 2027,
                "product": "VISA"
            },
            "shop": {
                "id": 1
            },
            "gateway_note": "",
            "uid": "20528-f87e29fa35",
            "id": 28860,
            "payment_method_type": "credit_card",
            "status": "incomplete",
            "message": null,
            "amount": 1000,
            "discount_rate": 0.0,
            "transaction_rate": 0.0,
            "pay_to_merchant": 0.0,
            "transaction_fee": 0.0,
            "test": false,
            "currency": "USD",
            "description": "Test description",
            "tracking_id": null,
            "type": "payment",
            "order_id": 27724,
            "created_at": "2022-01-27T14:07:00Z",
            "paid_at": null,
            "settled_at": null,
            "manually_corrected_at": null,
            "additional_data": {
                "request_id": "cb8ada4d-59cb-49c5-b6c5-3e679dd2c7c7",
                "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": 666,
                    "window_width": 600,
                    "accept_header": "application/json"
                },
                "vendor": {
                    "name": "CTP",
                    "token": "18b3e6fe3d08edf84bb2fe60c9077c8b898a5bd58f7dc27cd2b286b6b10197d2"
                },
                "tdsecure": {
                    "status": "incomplete",
                    "message": "Authentication Available",
                    "ve_status": "Y",
                    "acs_url": "https://test.pc.com:8443/pareq/15524/003ec8b2-4bef-4036-84ba-f27721c99d86/",
                    "pa_req": "eJxVUtFy2jAQ/BVP3vFJslMwc9GMiRtCZkIpMCXpm7APYxJsIpsW/31PgJtWT7ennb3blXC5tUTJgtKjJY3PVNcmJ6/I7m5e5w8v4U8lF7civp/0B+OXZHajcRbP6UPjL7J1UZVa+sJXCB1kBZtuTdloNOnHaDLVkZQqihCuEPdkJ4mOuoNwaWBp9qTXdDBF5q9bhDPGtDqWjW01iyB0AI/2XW+b5lAPAXZ1r25MXpS5v6bcNPTbtH5a7QHB0RA+N5odXVWz7KnI9OrH03iVzM3z7mE5XY5G38Vb8O1rxrbjOwTHwIzltBJKCan6ngyHoj8UXxDOfTR7t4+WwhfCG71O2eOlgwc3KO6uhUD4t4OctaUybXUUBOyqQ0inQ1USM9jr3xozqlMd9JKFt6ms19iTp8StGvQ2gz6paGOCkBdyHIRPg/eP7gHShpOVQoYseEVuSMEZqtAlegUIjg/Xp+XEzr+Aq/9+xx/mJ7T7",
                    "md": "42877",
                    "pa_res_url": "https://gateway.fortebank.com/process/20528-f87e29fa35",
                    "eci": null,
                    "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": null,
                "pa_status": null,
                "xid": null,
                "cavv": null,
                "cavv_algorithm": null,
                "ve_status": "Y",
                "message": "Authentication Available",
                "status": "incomplete"
            }
        },
        {
            "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": "79.98.55.24",
                "email": null
            },
            "payment": {
                "gateway_id": 312,
                "ref_id": null,
                "message": null,
                "status": "incomplete",
                "gateway_name": "Demo",
                "auth_code": null,
                "bank_code": null,
                "rrn": null,
                "billing_descriptor": null
            },
            "credit_card": {
                "holder": "John Doe",
                "token": "3379480e-4c10-4dbd-83a3-7a14d16baf1f",
                "brand": null,
                "last_4": "0007",
                "first_1": "4",
                "bin": "420000",
                "issuer_country": "IT",
                "issuer_name": "INVESTBANK",
                "exp_month": 1,
                "exp_year": 2027,
                "product": "VISA"
            },
            "shop": {
                "id": 1
            },
            "gateway_note": "",
            "uid": "20529-66a8451797",
            "id": 28861,
            "payment_method_type": "credit_card",
            "status": "incomplete",
            "message": null,
            "amount": 1000,
            "discount_rate": 0.0,
            "transaction_rate": 0.0,
            "pay_to_merchant": 0.0,
            "transaction_fee": 0.0,
            "test": false,
            "currency": "USD",
            "description": "Test description",
            "tracking_id": null,
            "type": "payment",
            "order_id": 27725,
            "created_at": "2022-01-27T14:11:53Z",
            "paid_at": null,
            "settled_at": null,
            "manually_corrected_at": null,
            "additional_data": {
                "request_id": "9e97e8ad-54e6-487f-9bc0-eae0b497f73f",
                "browser": {
                    "screen_width": 1920,
                    "screen_height": 1080,
                    "screen_color_depth": 24,
                    "language": "it",
                    "java_enabled": false,
                    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:89.0) Gecko/20100101 Firefox/89.0",
                    "time_zone": -180,
                    "time_zone_name": "Europe/London",
                    "window_height": 666,
                    "window_width": 600,
                    "accept_header": "application/json"
                },
                "vendor": {
                    "name": "CTP",
                    "token": "179a4105e3f25b2c0ec3e6daf6135629f2fc4caf66667346ae5aeb776c958b4b"
                },
                "tdsecure": {
                    "status": "incomplete",
                    "message": "Authentication Available",
                    "ve_status": "Y",
                    "acs_url": "https://test.pc.com:8443/pareq/15525/a52d019a-440b-450a-b72c-67b24f02a56c/",
                    "pa_req": "eJxVUl1v4jAQ/CtR34k/AvSCFkvQqOpHgiCQVjwaZy+kVxJwQpv8+7MDoXd+mlmPZnfHhs1eIwZrVGeNAiKsKpmhk6fTu1X4kizDx9l8FUY8jrdeuA3uBCxnMZ4EfKGu8rIQzKUuB9JT46DVXha1AKlO8+eF8Bnjvg/kSuGA+jkQfn+AXApQyAOKHR5lnrq7FkjHQZXnotatMCZAegJn/Sn2dX2sJoR8VIOqllleZO4OM1njt2xdVR4IECsD8jPR8mxRZWybPBVJ0ry+vc2j+M/jg8GL6PNl/b5ZRO/JagrEKiA1doJTzinj9w4bThibjDwgXR3kwc4jGHUpdebbhdnxUoGjbTTrrykF8m8FTNYaC9UK3zNmNwbYHMsCjcLsesOQYqWENwjWzu9SO7VuHE5H3B+Mx/LXcMTu/bEZyGqA/Cz48GQfQNUmWUbZ0BhemW2SmwztTl0XS4BYPbk+rUms+wUG/fc7/gJV8bWH",
                    "md": "42878",
                    "pa_res_url": "https://gateway.fortebank.com/process/20529-66a8451797",
                    "eci": null,
                    "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": null,
                "pa_status": null,
                "xid": null,
                "cavv": null,
                "cavv_algorithm": null,
                "ve_status": "Y",
                "message": "Authentication Available",
                "status": "incomplete"
            }
        }
    ],
    "count": 2,
    "has_more": false,
    "first_object_id": 28860,
    "last_object_id": 28861
}

Pagination

If the has_more response parameter value is set to true, there are more transactions that meet the request parameters, but are not included in the response. Use forward and reverse pagination to get a report on all the transactions.

For the forward pagination, send another report request with the same parameters, but add the starting_after parameter and set its value to last_object_id from the response.

For the reverse pagination, send another report request with the same parameters, but add the ending_before parameter and set its value to first_object_id from the response.