# Updated alternative order

Webhooks for alternative payment method status enable merchants to securely receive real-time notifications of changes in the status of alternative payment methods, such as processing or declined, and automatically initiate 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 APMOrderStatus
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: "alt_gate.order.updated"

## Request fields (application/json):

  - `order` (object)
    Details of an order, including identifiers, timestamps, amounts, status, and customer data.

  - `order.method` (string)
    Payment method that was used to process the order.

  - `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.

  - `order.subscription_id` (string)
    Unique subscription identifier.

  - `order.token` (string)
    Token associated with a card method that can be used for the subsequent payments.

  - `order.created_at` (string)
    Datetime when the order was created.

  - `order.updated_at` (string)
    Datetime when the order was updated.

  - `order.amount` (integer)
    Order amount in the smallest currency unit supported by the alternative payment method.

  - `order.currency` (string)
    Three-letter ISO-4217 currency code.

  - `order.order_description` (string)
    Brief order description.

  - `order.descriptor` (string)
    Identifying text that appears on a customer’s statement.


  It includes information about the transaction and helps the customer recognize the charge and provided only for paypal-vault method.

  - `order.status` (string)
    Status of the requested order.
    Enum: "created", "processing", "settle_pending", "approved", "declined", "refunded"

  - `order.customer_account_id` (string)
    Unique customer identifier defined by the merchant.

  - `order.customer_email` (string)
    Customer's email address.

  - `order.ip_address` (string)
    Public IP address of the cardholder, both IPv4 and IPv6 are supported.

                
  Useful for antifraud checks. For recurring payments, use the last session or registration IP.
  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.provider_data` (object)
    Additional data from the payment provider. 

                
  Parameters in this object are only available for transactions with paypal-vault method.

  - `order.provider_data.billing_address` (object)
    Billing address details.

  - `order.provider_data.billing_address.country` (string)
    ISO 3166-1 alpha-3 country code of the billing address.

  - `order.provider_data.billing_address.state` (string)
    ISO 3166-2 address state code of the billing address.

  - `order.provider_data.billing_address.city` (string)
    City name.

  - `order.provider_data.billing_address.zip` (string)
    Address zip/postal code.

  - `order.provider_data.billing_address.line1` (string)
    First line of the address.

  - `order.provider_data.billing_address.line2` (string)
    Second line of the address.

  - `order.provider_data.shipping_address` (object)
    Address to ship.


  If this field is passed by the merchant - the customer cannot change this address.

  - `order.provider_data.shipping_address.country` (string)
    ISO 3166-1 alpha-3 country code of the shipping address.

  - `order.provider_data.shipping_address.state` (string)
    Code of the state where the person, business or institution is located.

  - `order.provider_data.shipping_address.city` (string)
    City or town where the person, business or institution is located.

  - `order.provider_data.shipping_address.zip` (string)
    Address zip/postal code where the person, business or institution is located.

  - `order.provider_data.shipping_address.line1` (string)
    First line of the address.

  - `order.provider_data.shipping_address.line2` (string)
    Second line of the address.

  - `order.provider_data.payer` (object)
    Details of the payer for transactions conducted via APMs.


  It provides key information such as the payer's email, first name, and last name, crucial for identifying the payer in the transaction process.

  - `order.provider_data.payer.account_id` (string)
    Payer or their wallet identifier in the payment provider's system.


  Used to uniquely identify the payer.

  - `order.provider_data.payer.first_name` (string)
    Payer's first name, used to identify the individual within the transaction.

  - `order.provider_data.payer.last_name` (string)
    Payer's last name, used to verify the payer's identity.

  - `order.provider_data.payer.phone` (string)
    Phone number of the payer.


  Used for communication and identification purposes in the transaction.

  - `order.provider_data.payer.email` (string)
    Email address of the payer.


  Used for communication and identification purposes in the transaction.

  - `order.provider_data.merchant` (object)
    Information about the merchant involved in the transaction, useful for identifying the specific PayPal account used for the payment.


  This object provides identifiers for merchants, essential for accurate tracking and processing of transactions.

  - `order.provider_data.merchant.account_id` (string)
    Unique merchant PayPal account identifier used in the transaction.


  Identifier is critical for associating the transaction with the correct merchant's PayPal account, enabling accurate processing and order reporting.

  - `error` (object) — one of (discriminator: code):
    Error object.


  Returned only in cases of declined statuses at the order, and fail status at transaction.
    - 5.02 Invalid card token:
      - `messages` (array, required)
        Array containing messages that specify why the payment was declined due to validation errors.
        Example: ["Invalid card token"]
      - `recommended_message_for_user` (string)
        Recommended message to be displayed to the user for further action or information.


  Ask the customer to retry the transaction or use a different card. Ensure that the card token generation and handling processes are correctly implemented.
    - X.XX:
      - `messages` (array, required)
        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: "Invalid card token."

  - `error.code` (string)
    Gateway error code for the declined payment.

  - `transactions` (array)
    Details of transactions, including identifiers, amounts, currencies, statuses, and types.

  - `transactions.method` (string)
    Payment method that was used to process the order.

  - `transactions.id` (string)
    Unique transaction identifier.

  - `transactions.created_at` (string)
    Datetime when the transaction was created.

  - `transactions.amount` (integer)
    Transaction amount in the smallest currency unit supported by the alternative payment method.

  - `transactions.currency` (string)
    Three-letter ISO-4217 currency code.

  - `transactions.status` (string)
    Status of the transaction.
    Enum: "created", "processing", "settle_pending", "success", "fail"

  - `transactions.type` (string)
    Type of the transaction.
    Enum: "pay", "recurring", "refund"

  - `transactions.refund_reason` (string)
    Text description of the refund reason.

  - `transactions.refund_reason_code` (string)
    Refund reason code.


  This field is actively validated against the current list of reason codes. Deprecated codes will not be accepted.

  - `transactions.payer_details` (object)
    Details of the payer for transactions conducted through APMs.


  It provides essential information such as the payer's email and the invoice identifier, both of which are specifically applicable to transactions conducted with the PayPal method.

  - `transactions.payer_details.invoice_id` (string)
    Unique invoice identifier provided by PayPal.


  It would be provided only for the transactions with paypal-vault method.

  - `transactions.payer_details.payer_email` (string)
    Payer's email.


  It would be provided only for the transactions with paypal-vault method.

  - `order_metadata` (object)
    Metadata is useful for storing additional, structured information about an order.

  - `pay_form` (object)
    Payment form data.


  Including fields necessary for processing the payment.

  - `pay_form.token` (string)
    Secure payment token representing sensitive payment method information.

  - `pay_form.script_url` (string)
    URL of the JavaScript file needed to display the PayPal button is required for integration, initialization, configuration.


## Response 2XX fields