# Updated card order Webhooks allow merchants to securely receive real-time notifications in card order status changes, for example, from processing to auth_failed, and automatically trigger actions or updates in their own systems based on those events. Duplicate webhook events can occur. Implement idempotency on your end to avoid processing the same event twice. Endpoint: POST CardsOrderStatus 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: "wh_pk_7b197...ba108f842" - `signature` (string, required) Request signature that allows verification of merchant authenticity on the payment gateway server. Example: "M2E3OTkyNzcz...xMmExODI4" - `solidgate-event-id` (string, required) Unique event identifier. Example: "e1765cf7-70f7-4e56-8fb2-bd88744a94d1" - `solidgate-event-created-at` (string, required) Event creation time in ISO 8601 format with milliseconds. Example: "2025-06-05T12:34:56.789Z" - `solidgate-event-type` (string, required) Event type, indicating the specific event that occurred. Example: "card_gate.order.updated" ## Request fields (application/json): - `order` (object) Information about the order, including identifiers, timestamps, amounts, status, and customer details. - `order.order_id` (string) Unique order identifier, which can be used to find the payment. For the first payment, the identifier is defined by the merchant. For recurring subscription-based payments, it is generated by the Solidgate subscription service. Example: "923bb4e6-4a5f-41ec-81fb-28eb8a152e55" - `order.order_description` (string) Brief description of the order. Example: "Premium package" - `order.psp_order_id` (string) PSP identifier generated by Solidgate. - `order.provider_payment_id` (string) PSP identifier generated by the PSP. Value will be if the integration transmitted this data. - `order.product_id` (string) Unique product identifier. - `order.product_name` (string) Product name. - `order.subscription_id` (string) Unique subscription identifier. Example: "83b19018-cbc4-4df0-899a-dda84fd2705e" - `order.amount` (integer) Order amount in the smallest currency unit. This is the intended initial authorization amount. For instance, 1020 means 10 EUR and 20 cents. Example: 100 - `order.currency` (string) Three-letter ISO-4217 currency code. Example: "USD" - `order.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. - `order.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. - `order.marketing_amount` (integer) Order amount converted to USD, or other currency as agreed, using a publicly available rate at the payment date. This is based on the intended initial authorization amount. It should not be considered financial information, but it can be used for forecasting. - `order.marketing_currency` (string) Three-letter ISO-4217 currency code of the currency used for calculation of marketing amount. Example: "USD" - `order.refunded_amount` (integer) Indicates the amount that has been already refunded. - `order.authorized_amount` (integer) Total authorized amount of the order. - `order.status` (string) Status of the requested order. In the case of auth_failed, an error object will be returned at the order level. Enum: "processing", "3ds_verify", "refunded", "auth_ok", "auth_failed", "settle_ok", "partial_settled", "void_ok" - `order.auth_code` (string) Transaction authorization code. It can be empty if the provider does not pass a value. Example: "2w9m8" - `order.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" - `order.payment_method` (string) Payment method used for the transaction. Enum: "card", "network-token", "token", "apple-pay", "google-pay" - `order.customer_account_id` (string) Unique customer identifier defined by the merchant. Example: "93a1c659-288d-4d62-929d-10e241078faa" - `order.customer_email` (string) Customer's email address. Example: "example@example.com" - `order.descriptor` (string) Identifying text that appears on a customer’s credit or debit card statement. It includes information about the transaction and helps the cardholder recognize the charge. Example: "google.com" - `order.mid` (string) Merchant identifier in Solidgate. Example: "bank-mid-1" - `order.ip_address` (string) Public IP address of the cardholder, both IPv4 and IPv6 are supported. 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. - `order.traffic_source` (string) Identifies the marketing or acquisition channel that brought the customer to the transaction. Example: "facebook" - `order.fraudulent` (boolean) Whether the merchant system has flagged this customer as suspicious. - `error` (object) — one of (discriminator: code): Error object. Returned only in cases of auth_failed status at the order, and fail status at transaction. - 3.08 Do not honor: - `messages` (array, required) Array containing messages that specify why the payment was declined due to validation errors. Example: ["Do not honor"] - `recommended_message_for_user` (string) Recommended message to be displayed to the user for further action or information. Advise the customer to contact their card issuer to resolve potential restrictions like blocked cards, insufficient limits, or currency issues before retrying the transaction. - X.XX: - `messages` (array, required) An array containing either strings or objects that provide details about the error or status. When it is an array of strings, each string describes a separate issue. When it is an object, the object will contain key-value pairs explaining the issue in more detail. - `recommended_message_for_user` (string) Message with recommended next steps or additional information. Example: "The problem here lies with the data format and accuracy, validation error on the acquiring side" - `merchant_advice_code` (string) Merchant Advice Codes (MACs) are introduced by Mastercard to clearly communicate to merchants the reason for declining transactions, and the course of action that merchants can take. If present, the MAC contains information about why the payment failed, whether it can be retried and in some cases, the recommended duration after which it should be retried. Follow to the merchant advice codes to get recommendations to handle the value. - `error.code` (string) Gateway error code for the declined payment. - `transaction` (object) Details of a card transaction, including identifiers, timestamps, amounts, currency, operation type, status, and other relevant data. - `transaction.id` (string) Unique transaction identifier. - `transaction.created_at` (string) Datetime when the transaction was created. - `transaction.updated_at` (string) Datetime when the transaction was updated. - `transaction.amount` (integer) Transaction amount in the smallest currency unit. For instance, 1020 means 10 EUR and 20 cents. - `transaction.currency` (string) Three-letter ISO-4217 currency code of the transaction. - `transaction.marketing_amount` (integer) Order amount converted to USD, or other currency as agreed, using a publicly available rate at the payment date. It should not be considered financial information, but it can be used for forecasting. - `transaction.marketing_currency` (string) Three-letter ISO-4217 currency code of the currency used for calculation of marketing amount. Example: "USD" - `transaction.operation` (string) Type of the transaction. Enum: "recurring-auth", "refund", "resign-auth", "auth", "settle", "void", "apple-pay", "google-pay" - `transaction.status` (string) Status of the transaction. In the case of fail, an error object will be returned at the transaction level. Enum: "processing", "success", "fail", "verify" - `transaction.authorization_type` (string) Authorization type that defines the transaction flow and capabilities. Enum: "final", "estimated", "incremental" - `transaction.scheme_transaction_id` (string) Card-scheme transaction identifier linking this transaction to the original customer-initiated payment. - `transaction.transaction_link_id` (string) Transaction link identifier (TLID) is an ID generated by Mastercard to link lifecycle activity after the original transaction. - `transaction.descriptor` (string) Identifying text that appears on a customer’s credit or debit card statement. It includes information about the transaction and helps the cardholder recognize the charge. - `transaction.billing_details` (object) Billing address details. - `transaction.billing_details.address` (string) First and second line of the billing address. - `transaction.billing_details.country` (string) Billing address country. - `transaction.billing_details.city` (string) Billing address city. - `transaction.billing_details.state` (string) ISO 3166-2 address state code of the billing address. - `transaction.billing_details.zip` (string) Billing zip/postal code. - `transaction.refund_reason` (string) Text description of the refund reason. - `transaction.refund_reason_code` (string) Code representing the reason for the refund. This code is used to identify the reason for both void and refund transactions operation - `transaction.card_token` (object) Token associated with a card method that can be used for subsequent payments. - `transaction.card_token.token` (string) Token generated for a card method, enabling its use for future payments. The token is not generated for all types of payment flows. - `transaction.card_token.original_payment_method` (string) Payment method used to capture the card credentials at token creation. Enum: "card", "apple-pay", "google-pay", "network-token", "click-to-pay" - `transaction.card` (object) Object containing detailed information about the card used in the transaction. - `transaction.card.bank` (string) Name of the card issuer. - `transaction.card.bin` (string) Card issuer's Bank Identification Number (BIN). - `transaction.card.brand` (string) Card brand. - `transaction.card.card_exp_month` (string) Expiry month of the card. - `transaction.card.card_exp_year` (integer) Expiry year of the card. - `transaction.card.card_holder` (string) Cardholder's name as it appears on the card, which is essential for transaction processing. 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. Example: "John Snow" - `transaction.card.card_type` (string) Card type. Enum: "CREDIT", "CREDIT/DEBIT", "DEBIT", "PREPAID", "CHARGE CARD", "DEFERRED DEBIT" - `transaction.card.is_reloadable` (boolean) Indicator of whether the card belongs to a reloadable program. null means the reloadable indicator is not available. - `transaction.card.card_id` (string) Unique identifier of the card used for the transaction. - `transaction.card.country` (string) Card issuer's country. - `transaction.card.number` (string) Masked card number. - `transaction.card.card_token` (object) Token associated with a card method that can be used for subsequent payments. - `transaction.card.card_token.token` (string) Token generated for a card method, enabling its use for future payments. The token is not generated for all types of payment flows. - `transaction.card.card_token.original_payment_method` (string) Payment method used to capture the card credentials at token creation. Enum: same as `transaction.card_token.original_payment_method` (5 values) - `transaction.error` (object) — one of (discriminator: code): Error object. - 3.08 Do not honor: - `messages` (array, required) Array containing messages that specify why the payment was declined due to validation errors. Example: ["Do not honor"] - `recommended_message_for_user` (string) Recommended message to be displayed to the user for further action or information. Advise the customer to contact their card issuer to resolve potential restrictions like blocked cards, insufficient limits, or currency issues before retrying the transaction. - X.XX: - `messages` (array, required) An array containing either strings or objects that provide details about the error or status. When it is an array of strings, each string describes a separate issue. When it is an object, the object will contain key-value pairs explaining the issue in more detail. - `recommended_message_for_user` (string) Message with recommended next steps or additional information. Example: "The problem here lies with the data format and accuracy, validation error on the acquiring side" - `merchant_advice_code` (string) Merchant Advice Codes (MACs) are introduced by Mastercard to clearly communicate to merchants the reason for declining transactions, and the course of action that merchants can take. If present, the MAC contains information about why the payment failed, whether it can be retried and in some cases, the recommended duration after which it should be retried. Follow to the merchant advice codes to get recommendations to handle the value. - `transaction.error.code` (string) Gateway error code for the declined payment. - `transaction.payment_account_reference` (string) Payment Account Reference (PAR) is a unique, non-financial identifier for a payment account that remains consistent across card replacements. Example: "PAR_1A2B3C4D5E6F7G8H9" - `transaction.arn_code` (string) Acquirer Reference Number (ARN) assigned to transactions. Use ARN to check transaction status. Example: "12345678901234567890123" - `transaction.rrn_code` (string) Retrieval Reference Number (RRN) assigned to transactions, based on the ISO 8583 standard. Example: "100034876543" - `transactions` (object) Map of transactions where the keys are transaction identifiers. - `transactions.` (object) Details of a card transaction, including identifiers, timestamps, amounts, currency, operation type, status, and other relevant data. - `transactions..id` (string) Unique transaction identifier. - `transactions..created_at` (string) Datetime when the transaction was created. - `transactions..updated_at` (string) Datetime when the transaction was updated. - `transactions..amount` (integer) Transaction amount in the smallest currency unit. For instance, 1020 means 10 EUR and 20 cents. - `transactions..currency` (string) Three-letter ISO-4217 currency code of the transaction. - `transactions..marketing_amount` (integer) Order amount converted to USD, or other currency as agreed, using a publicly available rate at the payment date. It should not be considered financial information, but it can be used for forecasting. - `transactions..marketing_currency` (string) Three-letter ISO-4217 currency code of the currency used for calculation of marketing amount. Example: "USD" - `transactions..operation` (string) Type of the transaction. Enum: same as `transaction.operation` (8 values) - `transactions..status` (string) Status of the transaction. In the case of fail, an error object will be returned at the transaction level. Enum: same as `transaction.status` (4 values) - `transactions..authorization_type` (string) Authorization type that defines the transaction flow and capabilities. Enum: same as `transaction.authorization_type` (3 values) - `transactions..scheme_transaction_id` (string) Card-scheme transaction identifier linking this transaction to the original customer-initiated payment. - `transactions..transaction_link_id` (string) Transaction link identifier (TLID) is an ID generated by Mastercard to link lifecycle activity after the original transaction. - `transactions..descriptor` (string) Identifying text that appears on a customer’s credit or debit card statement. It includes information about the transaction and helps the cardholder recognize the charge. - `transactions..billing_details` (object) Billing address details. - `transactions..refund_reason` (string) Text description of the refund reason. - `transactions..refund_reason_code` (string) Code representing the reason for the refund. This code is used to identify the reason for both void and refund transactions operation - `transactions..card_token` (object) Token associated with a card method that can be used for subsequent payments. - `transactions..card_token.token` (string) Token generated for a card method, enabling its use for future payments. The token is not generated for all types of payment flows. - `transactions..card_token.original_payment_method` (string) Payment method used to capture the card credentials at token creation. Enum: same as `transaction.card_token.original_payment_method` (5 values) - `transactions..card` (object) Object containing detailed information about the card used in the transaction. - `transactions..card.bank` (string) Name of the card issuer. - `transactions..card.bin` (string) Card issuer's Bank Identification Number (BIN). - `transactions..card.brand` (string) Card brand. - `transactions..card.card_exp_month` (string) Expiry month of the card. - `transactions..card.card_exp_year` (integer) Expiry year of the card. - `transactions..card.card_holder` (string) Cardholder's name as it appears on the card, which is essential for transaction processing. 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. Example: "John Snow" - `transactions..card.card_type` (string) Card type. Enum: same as `transaction.card.card_type` (6 values) - `transactions..card.is_reloadable` (boolean) Indicator of whether the card belongs to a reloadable program. null means the reloadable indicator is not available. - `transactions..card.card_id` (string) Unique identifier of the card used for the transaction. - `transactions..card.country` (string) Card issuer's country. - `transactions..card.number` (string) Masked card number. - `transactions..card.card_token` (object) Token associated with a card method that can be used for subsequent payments. - `transactions..card.card_token.token` (string) Token generated for a card method, enabling its use for future payments. The token is not generated for all types of payment flows. - `transactions..card.card_token.original_payment_method` (string) Payment method used to capture the card credentials at token creation. Enum: same as `transaction.card_token.original_payment_method` (5 values) - `transactions..error` (object) — one of (discriminator: code): Error object. - 3.08 Do not honor: - `messages` (array, required) Array containing messages that specify why the payment was declined due to validation errors. Example: ["Do not honor"] - `recommended_message_for_user` (string) Recommended message to be displayed to the user for further action or information. Advise the customer to contact their card issuer to resolve potential restrictions like blocked cards, insufficient limits, or currency issues before retrying the transaction. - X.XX: - `messages` (array, required) An array containing either strings or objects that provide details about the error or status. When it is an array of strings, each string describes a separate issue. When it is an object, the object will contain key-value pairs explaining the issue in more detail. - `recommended_message_for_user` (string) Message with recommended next steps or additional information. Example: "The problem here lies with the data format and accuracy, validation error on the acquiring side" - `merchant_advice_code` (string) Merchant Advice Codes (MACs) are introduced by Mastercard to clearly communicate to merchants the reason for declining transactions, and the course of action that merchants can take. If present, the MAC contains information about why the payment failed, whether it can be retried and in some cases, the recommended duration after which it should be retried. Follow to the merchant advice codes to get recommendations to handle the value. - `transactions..payment_account_reference` (string) Payment Account Reference (PAR) is a unique, non-financial identifier for a payment account that remains consistent across card replacements. Example: "PAR_1A2B3C4D5E6F7G8H9" - `transactions..arn_code` (string) Acquirer Reference Number (ARN) assigned to transactions. Use ARN to check transaction status. Example: "12345678901234567890123" - `transactions..rrn_code` (string) Retrieval Reference Number (RRN) assigned to transactions, based on the ISO 8583 standard. Example: "100034876543" - `three_ds` (object) Information related to the processing of the payment. - `three_ds.eci` (string) Electronic Commerce Indicator (ECI) security level used to authorize the payment. Applicable for 3D Secure, digital wallet, and network token payments. Example: "05" - `three_ds.flow` (string) Specifies whether and how the customer was involved in the 3D Secure. Flow null indicates that 3D Secure authentication was not initiated for the transaction. Enum: "frictionless", "challenge", "none", "unspecified" - `three_ds.exception` (string) Strong Customer Authentication (SCA) exception type applied to the transaction. Enum: "low_value", "transaction_risk_assessment" - `routing` (object) Payment routing information. The availability of this object depends on whether routing is configured for your account. - `routing.cascade_steps` (array) Details of the attempts made to process the payment. - `routing.cascade_steps.mid` (string) Merchant identifier in Solidgate. - `routing.cascade_steps.mid_descriptor` (string) Identifying text that appears on a customer's credit or debit card statement. - `routing.cascade_steps.route_id` (string) Route identifier configured in Solidgate. - `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. - `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. - `antifraud_result` (object) Pre-authorization decision returned by Solidgate Antifraud. Returned only when the merchant uses Solidgate’s internal antifraud service, which excludes provider-side fraud results. - `antifraud_result.pre_auth` (string) Outcome of the real-time antifraud screening performed before the authorization request is sent. - reject - transaction declined - review - requires manual review - pass - approved to proceed Enum: "reject", "review", "pass" - `verification_result` (object) Verification results for Address Verification Service (AVS), Card Verification Value (CVV), and Account Name Inquiry (ANI), providing match status. - `verification_result.avs_result` (string) AVS result from card schemes verifies if the billing address matches with the issuing bank. It returns a value that indicates the level of match, assisting in the decision to approve, verify, or decline a transaction. Enum: "matched", "partially_matched", "not_matched", "unsupported", "unavailable", "unknown" - `verification_result.cvv_result` (string) CVV result indicates whether the CVV code entered matches the one on the card, confirming the cardholder’s possession. It helps assess transaction legitimacy and decide whether to approve, verify, or decline. Enum: "matched", "not_matched", "not_checked", "unavailable", "unknown" - `verification_result.ani` (object) ANI result from the card scheme verifies whether the cardholder name matches the issuer’s records. It helps confirm the cardholder’s identity, supporting the decision to approve, verify, or decline a transaction. - `verification_result.ani.status` (string) Outcome of the name match check performed against the issuer’s records. Enum: "performed", "not_performed", "not_supported" - `verification_result.ani.full_name_match` (string) Result of matching the full cardholder name against the issuer’s records. Enum: "matched", "partially_matched", "not_matched" - `verification_result.ani.first_name_match` (string) Result of matching the cardholder’s first name against the issuer’s records. Enum: same as `verification_result.ani.full_name_match` (3 values) - `verification_result.ani.last_name_match` (string) Result of matching the cardholder’s last name against the issuer’s records. Enum: same as `verification_result.ani.full_name_match` (3 values) - `chargebacks` (object) Map of chargebacks where the keys are chargeback identifiers. - `chargebacks.id` (integer) Unique chargeback identifier. - `chargebacks.dispute_date` (string) Date on which the chargeback was created by the issuer. - `chargebacks.settlement_date` (string) Date on which the chargeback was financially settled. - `chargebacks.amount` (integer) Amount that will be deducted for the chargeback on a specific order. This amount may vary based on the user's decision to dispute a different amount. - `chargebacks.currency` (string) Three-letter ISO-4217 currency code of the chargeback amount. - `chargebacks.type` (string) Current type of the chargeback. Enum: "1st_chb", "2nd_chb", "arbitration" - `chargebacks.status` (string) Status of the chargeback. Enum: "in_progress", "document_sent", "reversed", "accepted", "resolved", "resolved_reversal" - `chargebacks.reason_group` (string) Reason code group. It could be used for the segmentation and analytic purposes. - `chargebacks.reason_code` (string) Reason code for the chargeback provided by the card scheme. - `chargebacks.reason_description` (string) Reason code description for the chargeback provided by the card scheme. - `chargebacks.chargeback_flow` (array) Map of chargeback flows where the keys are chargeback flow identifiers. - `chargebacks.chargeback_flow.id` (integer) Unique chargeback flow identifier. - `chargebacks.chargeback_flow.date` (string) Datetime when the chargeback flow was created. - `chargebacks.chargeback_flow.updated_date` (string) Datetime when the chargeback flow was updated. - `chargebacks.chargeback_flow.settlement_date` (string) Date when the chargeback flow was financially settled. - `chargebacks.chargeback_flow.deadline_date` (string) Deadline for submitting a response to the dispute. This corresponds to date + n, where n is a number of calendar days set by the scheme/acquirer. - `chargebacks.chargeback_flow.amount` (integer) Amount involved in each stage of the chargeback process. For example, there could be two records in chargeback_flow one with an amount of 113.58 USD and another with an amount of 100 USD. - `chargebacks.chargeback_flow.dispute_amount` (integer) Specific amount disputed, typically in the smallest currency unit, that would be returned to the merchant if the dispute is resolved in their favor. For example, if the second chargeback was successfully disputed, the dispute_amount would be 100 USD. - `chargebacks.chargeback_flow.currency` (string) Three-letter ISO-4217 currency code of the chargeback amount. - `chargebacks.chargeback_flow.type` (string) Type of the chargeback flow. Enum: same as `chargebacks.type` (3 values) - `chargebacks.chargeback_flow.status` (string) Status of the chargeback. Enum: same as `chargebacks.status` (6 values) - `chargebacks.chargeback_flow.arn_code` (string) Acquirer Reference Number (ARN) assigned to transactions. Use ARN to check transaction status. - `chargebacks.chargeback_flow.rrn_code` (string) Retrieval Reference Number (RRN) assigned to transactions, based on the ISO 8583 standard. - `device_info` (object) Information about the device used. - `device_info.user_agent` (string) Device user-agent. - `verify_url` (string) URL where the customer should be redirected to complete 3DS authentication. Only after opening the URL and authenticating the order status change to 3ds_verify. - `redirect_url` (string) URL where customer should be redirected after finishing 3D Secure or redirect payment method. - `order_metadata` (object) Metadata is useful for storing additional, structured information about an order. - `payment_adviser` (object) Provides recommendations on which payment type to offer for future orders based on the card used. - `payment_adviser.advise` (string) Recommendation for which payment type to use for the given order and card. ## Response 2XX fields