# Card orders

The report provides essential data for merchants, including transaction details, customer information, and technical insights, facilitating comprehensive order tracking, financial reconciliation, and enhanced operational and marketing strategies.


  This report uses the updated_at as the default parameter for unloading data, which reflects the latest update to card orders.

Endpoint: POST /card-orders
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.psp_order_id` (string)
        PSP identifier generated by Solidgate.
      - `orders.provider_payment_id` (string)
        PSP identifier generated by the PSP.


  It is available if the integration passed the data.
      - `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.


  This is the intended initial authorization amount.
      - `orders.currency` (string, required)
        Three-letter ISO-4217 currency code of the order.
      - `orders.processing_amount` (integer)
        Amount of the payment in the smallest currency unit as it was processed by the payment service provider.


  This amount may differ from the original order amount due to currency conversion or other processing factors.
      - `orders.processing_currency` (string)
        Three-letter ISO-4217 currency code of the payment when it was processed by payment service provider.


  In some cases, it is different from the original currency.
      - `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.payment_type` (string)
        Payment type that defines if the transaction is customer-initiated (CIT) or merchant-initiated (MIT) and helps to define if a cardholder authentication can be provided.
        Enum: "1-click", "recurring", "retry", "installment", "rebill", "moto"
      - `orders.payment_method` (string)
        Payment method used for the transaction.
        Enum: "card", "network-token", "token", "apple-pay", "google-pay"
      - `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.routing` (object)
        Payment routing information.


  The availability of this object depends on whether routing is configured for your account.
      - `orders.routing.cascade_steps` (array)
        Details of the attempts made to process the payment.
      - `orders.routing.cascade_steps.mid` (string)
        Merchant identifier in Solidgate.
      - `orders.routing.cascade_steps.mid_descriptor` (string)
        Identifying text that appears on a customer's credit or debit card statement.
      - `orders.routing.cascade_steps.route_id` (string)
        Route identifier configured in Solidgate.
      - `orders.routing.cascade_steps.cascade_number` (integer)
        Sequential number of the processing attempt in the routing cascade, fallback step number.


  Indicates which attempt in the fallback sequence was used to process the payment.
      - `orders.routing.cascade_steps.segment_id` (string)
        Identifier of the segment used for this processing attempt in the routing configuration.


  Each segment represents a specific processing configuration within a route.
      - `orders.customer_account_id` (string)
        Unique customer identifier defined by the merchant.
      - `orders.customer_email` (string, required)
        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.mid` (string)
        Merchant identifier in Solidgate.
      - `orders.traffic_source` (string)
        Identifies the marketing or acquisition channel that brought the customer to the transaction.
      - `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: "APP", "WEB", "MOB"
      - `orders.geo_country` (string)
        Country where the customer account is registered on the merchant platform.
      - `orders.error_code` (string)
        Gateway error code for the declined payment.
      - `orders.transactions` (array, required)
        List of transactions, each containing detailed attributes such as transaction identifier, status, type, method, amount, currency, and timestamps for creation and updates.
      - `orders.transactions.id` (string, required)
        Unique transaction identifier.
      - `orders.transactions.created_at` (string, required)
        Datetime when the transaction was created.
      - `orders.transactions.updated_at` (string, required)
        Datetime when the transaction was updated.
      - `orders.transactions.amount` (integer, required)
        Transaction amount.
      - `orders.transactions.currency` (string, required)
        Three-letter ISO-4217 currency code of the transaction.
      - `orders.transactions.operation` (string, required)
        Type of the transaction.
        Enum: same as `orders.type` in "Success" (11 values)
      - `orders.transactions.status` (string, required)
        Status of the transaction.
        Enum: "processing", "success", "fail", "verify"
      - `orders.transactions.authorization_type` (string)
        Authorization type that defines the transaction flow and capabilities.
        Enum: "final", "estimated", "incremental"
      - `orders.transactions.descriptor` (string)
        Identifying text that appears on a customer’s bank statement.


  It includes information about the transaction and helps the cardholder recognize the charge.
      - `orders.transactions.refund_reason` (string)
        Text description of the refund reason.
      - `orders.transactions.refund_reason_code` (string)
        Indicates the reason code for the refund provided.


  This code is used to identify the reason for void and refund transaction operations.
      - `orders.transactions.card` (object, required)
        Information related to the card used in the transaction.


  Object, especially in refunds, may contain null values.
      - `orders.transactions.card.bank` (string)
        Card issuer name.
      - `orders.transactions.card.bin` (string)
        Card issuer Bank Identification Number (BIN).
      - `orders.transactions.card.brand` (string)
        Card brand.
      - `orders.transactions.card.card_exp_month` (string)
        Expiry month of the card.
      - `orders.transactions.card.card_exp_year` (integer)
        Expiry year of the card.
      - `orders.transactions.card.card_holder` (string)
        Cardholder's name.


  Should be provided as the cardholder's name to ensure accurate cardholder information and increase conversions. For some PSPs, if not provided, it is set to John Snow.
      - `orders.transactions.card.card_type` (string)
        Card type.
        Enum: "CREDIT", "CREDIT/DEBIT", "DEBIT", "PREPAID", "CHARGE CARD", "DEFERRED DEBIT"
      - `orders.transactions.card.card_id` (string)
        Unique identifier of the card used for the transaction.
        Example: "22733af4-f6c6-4368-b7d0-98aeb0253a57"
      - `orders.transactions.card.country` (string)
        Card issuer's country.
      - `orders.transactions.card.number` (string)
        Masked card number.
      - `orders.order_metadata` (object)
        Metadata is useful for storing additional, structured information about an object.
      - `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"]