# APM orders

The report is essential for merchants using alternative payment methods, offering comprehensive transaction details, including order IDs, statuses, amounts, customer information, crucial for a complete understanding of APM transaction dynamics.
This report uses the updated_at as the default parameter for unloading data, indicating the latest update to the APM orders.

Endpoint: POST /apm-orders
Version: 1.0.0
Security: merchant, signature

## Security:

  - `merchant` (unknown)
    apiKey in header merchant

  - `signature` (unknown)
    apiKey in header signature

## Header parameters:

  - `merchant` (string, required)

  - `signature` (string, required)

## 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:

  - `200` (unknown)
    This endpoint returns the APM orders data directly in the response body. No polling or separate download call is needed.

## Response 200 fields (application/json):

  - `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)
    Order description.

  - `orders.product_id` (string)
    Unique identifier of the product associated with the order.

  - `orders.product_name` (string)
    Name of the product associated with the order.

  - `orders.product_type` (string)
    Type of the product associated with the order.
    Enum: "recurring", "one_time"

  - `orders.subscription_id` (string)
    Unique identifier of the subscription associated with 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.method` (string, required)
    Payment method used to process the order.

  - `orders.amount` (integer, required)
    Original order 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.settled_amount` (integer)
    Total settled amount across all successful non-refund transactions on the order.

  - `orders.settled_currency` (string)
    Three-letter ISO-4217 currency code of the settled amount.

  - `orders.refunded_amount` (integer)
    Total refunded amount across all successful refund transactions on the order.

  - `orders.refunded_currency` (string)
    Three-letter ISO-4217 currency code of the refunded amount.

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

  - `orders.refund` (string)
    Refund status of the order.
    Enum: "partial", "full", "failed"

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

  - `orders.customer_email` (string, required)
    Customer's email address.

  - `orders.ip_address` (string, required)
    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.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.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.

  - `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.psp_transaction_id` (string)
    PSP saves the encrypted payment data and responds with a unique identifier for this transaction.
PSP uses the psp_transaction_id to locate the encrypted payment data for this transaction. This is the identifier generated by the provider (in our case PayPal). Only for transactions with orders:method:paypal-vault.

  - `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.method` (string, required)
    Payment method used to process the transaction.

  - `orders.transactions.amount` (integer, required)
    Transaction amount.

  - `orders.transactions.currency` (string, required)
    Three-letter ISO-4217 currency code of the transaction.

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

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

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

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

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

## Response 200 examples:

  - `Success` (unknown)

  - `Authentication failed` (unknown)