# Chargebacks

The report is essential for merchants, providing exhaustive insights into each chargeback, including identifiers, dates, types, amounts, reasons, and related original order details, which is crucial for understanding chargeback patterns, enhancing dispute resolution, and fraud prevention.


  Chargeback information is unloaded using the updated_at as the default parameter, which reflects the date when the latest chargeback flow was created.

Endpoint: POST /card-orders/chargebacks
Version: 1.0.0
Security: MerchantID

## Header parameters:

  - `merchant` (string, required)
    Unique public key provided upon registration and must be shared for identification purposes.
    Example: "api_pk_7b197...ba108f842"

  - `signature` (string, required)
    Request signature that allows verification of merchant authenticity on the payment gateway server.
    Example: "M2E3OTkyNzcz...xMmExODI4"

## Request fields (application/json):

  - `filter` (string)
    Filtering criteria for the report data.
    Enum: "updated_at", "created_at"

  - `date_from` (string, required)
    Start datetime for the report stated in UTC+0.
    Example: "2025-08-15 11:00:00"

  - `date_to` (string, required)
    End datetime for the report stated in UTC+0.
    Example: "2025-08-18 11:00:00"

  - `limit` (integer)
    Limit value indicates the maximum number of items to be returned.
    Example: 2000

  - `next_page_iterator` (string)
    Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.


  If this value is null, it indicates that all available data has been successfully retrieved by the merchant.
    Example: "eyJzdWJzY3JpcHRpb25faWQiOiI5ODlkCJkYXRlX3RvIjoiMjAyMC0wOS0xNyAxNDoxMDowMCJ9"

## Response 200 fields (application/json):

  - `body` (object) — one of:
    - Success:
      - `orders` (array, required)
        List of orders, each containing attributes like order identifier, status, type, amount, currency, and timestamps for creation and updates.
      - `orders.order_id` (string, required)
        Unique order identifier defined by the merchant.
      - `orders.order_description` (string, required)
        Description of the order.
      - `orders.created_at` (string, required)
        Datetime when the order was created.
      - `orders.updated_at` (string, required)
        Datetime when the order was updated.
      - `orders.amount` (integer, required)
        Original order amount.
      - `orders.currency` (string, required)
        Three-letter ISO-4217 currency code of the order.
      - `orders.status` (string, required)
        Status of the requested order.
        Enum: "processing", "3ds_verify", "refunded", "auth_ok", "auth_failed", "settle_ok", "partial_settled", "void_ok"
      - `orders.type` (string, required)
        Type of the transaction.


  The type from the initialized transaction.
        Enum: "pay", "recurring", "recurring-auth", "refund", "resign", "resign-auth", "auth", "settle", "void", "apple-pay", "google-pay"
      - `orders.is_secured` (boolean, required)
        Indicates whether this was a 3DS payment.
      - `orders.customer_account_id` (string)
        Unique customer identifier defined by the merchant.
      - `orders.customer_email` (string)
        Customer's email address.
      - `orders.customer_first_name` (string)
        Customer's first name.
      - `orders.customer_last_name` (string)
        Customer's last name.
      - `orders.ip_address` (string)
        Public IP address of the cardholder, both IPv4 and IPv6 are supported.

                
  Required for antifraud checks.
  Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255, 192.168.0.0-192.168.255.255) will result in an 'Invalid IP' error.
      - `orders.platform` (string)
        Device platform used by the customer at the time of payment.

                
  APP for application, WEB for desktop web, and MOB for mobile web.
        Enum: "MOB", "WEB", "APP"
      - `orders.geo_country` (string)
        Country where the customer account is registered on the merchant platform.
      - `orders.chargebacks` (array, required)
        List of chargebacks, each containing attributes such as unique identifier, creation, dispute, and settlement dates, amount, currency, type, status, and reason codes.
      - `orders.chargebacks.id` (string, required)
        Unique chargeback identifier.


  int64 value serialized as a string in JSON.
      - `orders.chargebacks.created_at` (string, required)
        Datetime when the chargeback was created.
      - `orders.chargebacks.updated_at` (string, required)
        Datetime when the chargeback was updated.
      - `orders.chargebacks.dispute_date` (string, required)
        Date when the chargeback was created by the issuer.
      - `orders.chargebacks.settlement_date` (string)
        Date when the chargeback was financially settled.
      - `orders.chargebacks.amount` (integer, required)
        Amount that will be deducted for the chargeback on a specific order.


  This amount may vary depending on the cardholder's decision on the amount to dispute.
      - `orders.chargebacks.currency` (string, required)
        Three-letter ISO-4217 currency code of the chargeback amount.
      - `orders.chargebacks.type` (string)
        Current type of the chargeback.
        Enum: "1st_chb", "2nd_chb", "arbitration"
      - `orders.chargebacks.status` (string)
        Status of the chargeback.
        Enum: "in_progress", "document_sent", "reversed", "accepted", "resolved", "resolved_reversal"
      - `orders.chargebacks.reason_group` (string)
        Reason code group.

                
  It can be used for the segmentation and analytic purposes.
      - `orders.chargebacks.reason_code` (string)
        Reason code for the chargeback provided by the card scheme.
      - `orders.chargebacks.reason_description` (string)
        Reason code description for the chargeback provided by the card scheme.
      - `orders.chargebacks.flows` (array)
        List of chargeback flows, each containing attributes such as unique identifier, creation, settlement, and deadline dates, amount, currency, type, status, and ARN code.
      - `orders.chargebacks.flows.id` (string, required)
        Unique chargeback flow identifier.


  int64 value serialized as a string in JSON.
      - `orders.chargebacks.flows.date` (string)
        Datetime when the chargeback flow was created by Solidgate.
      - `orders.chargebacks.flows.created_at` (string, required)
        Datetime when the chargeback flow was created.
      - `orders.chargebacks.flows.updated_at` (string, required)
        Datetime when the chargeback flow was updated.
      - `orders.chargebacks.flows.settlement_date` (string)
        Date when the chargeback flow was financially settled.
      - `orders.chargebacks.flows.deadline_date` (string)
        Deadline for submitting a response to contest the dispute.


  This corresponds to date + n, where n is a number of calendar days set by the scheme or acquirer.
      - `orders.chargebacks.flows.amount` (integer, required)
        Amount involved in each stage of the chargeback process.


  For example, there can be two records in chargeback_flow one with an amount of 113.58 USD and another with an amount of 100 USD.
      - `orders.chargebacks.flows.dispute_amount` (integer, required)
        Specific amount disputed, typically in the smallest currency unit, that is returned to the merchant if the dispute is resolved in their favor.


  For example, if the second chargeback is successfully disputed, the dispute_amount will be 100 USD.
      - `orders.chargebacks.flows.currency` (string, required)
        Three-letter ISO-4217 currency code of the chargeback amount.
      - `orders.chargebacks.flows.type` (string, required)
        Type of the chargeback flow.
        Enum: same as `orders.chargebacks.type` in "Success" (3 values)
      - `orders.chargebacks.flows.status` (string, required)
        Status of the chargeback flow.
        Enum: same as `orders.chargebacks.status` in "Success" (6 values)
      - `orders.chargebacks.flows.represented_by` (string)
        Indicates which party has provided the defense document for dispute representment.
        Enum: "merchant", "automation"
      - `orders.chargebacks.flows.arn_code` (string)
        Acquirer Reference Number (ARN) assigned to transactions.


  Use ARN to check transaction status.
      - `orders.fraudulent` (boolean)
        Whether the merchant system has flagged this customer as suspicious.
      - `metadata` (object, required)
        Metadata object containing pagination and count information.
      - `metadata.next_page_iterator` (string, required)
        Pagination helps in managing large datasets by dividing them into smaller, manageable chunks.


  If this value is null, it indicates that all available data has been successfully retrieved by the merchant.
      - `metadata.count` (integer, required)
        Number of orders on the page.
    - Authentication failed:
      - `error` (object, required)
        Error object.
      - `error.code` (string, required)
        Unauthorized access due to invalid credentials.
        Example: "1.01"
      - `error.messages` (array, required)
        Array of error messages applied to the decline payment.
        Example: ["Authentication failed"]