openapi: 3.0.1
info:
  title: "Merchant API"
  description: |
    This document serves as the API documentation for our Payment Gateway services, designed for merchant integration.

    It facilitates interactions with our expansive payment platform, enabling the seamless management of orders and transactions across a range of payment methods including credit/debit cards, digital wallets, loyalty programs (🚧 in development), bank transfers, vouchers (🚧 in development), wire transfers (🚧 in development), and more.

    ## Before you start

    Before you begin working with the API endpoints, make sure that you have visited [Getting started page](/docs/common/getting-started)

    ## OpenAPI File Export
    For your convenience, you can download the OpenAPI file of our API: [download merchant-api.yaml](/merchant-api.yaml)

  version: "1.0"
servers:
  - url: "https://gateway.vertexgateway.com/api/v1"
    description: Base URL for the production API endpoints.
  - url: "https://gateway.demo.vertexgateway.com/api/v1"
    description: Base URL for the test API endpoints.
tags:
  - name: Order
    description: "Handles the creation, cancellation, refund, capture, and retrieval of order statuses."
security:
  - ApiKeyAuth: []

paths:
  /order:
    post:
      tags:
        - Order
      summary: Create Order
      description: |
        Use this endpoint to initiate a new order.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/order.createOrderRequest"
      responses:
        "204":
          description: "Order successfully created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/order.createOrderResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /order/cancel:
    post:
      tags:
        - Order
      summary: "Cancel Order"
      description: |
        Voids an order whose payments are still in the `authorized` state.  
        Use this endpoint when an order is `in_progress` and **all** of its payments are in `authorized` status (funds are blocked but not yet captured).  
        Once accepted, the system submits cancellation requests to the acquirer for every authorized transaction and—when all succeed—sets both the order and the related payments to `cancelled`.  

        Retrieve the order via [Retrieve Order Details](/docs/merchant-api/retrieve-order-details).
      requestBody:
        description: "Parameters required to cancel an order."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/order.cancelOrderRequest"
      responses:
        "202":
          description: "Order cancellation in progress"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /order/reject:
    post:
      tags:
        - Order
      summary: "Reject Order (Deprecated)"
      deprecated: true
      description: |
        **Deprecated.** Use [`POST /api/v1/order/cancel`](/docs/merchant-api/cancel-order) instead. This endpoint will be removed in a future release.

        Force-cancels an order that is already being processed.
        Use this endpoint when you need to stop an order that is in the `in_progress` state and still contains at least one payment with status `in_progress`.
        When accepted, the system sends a cancellation request to the acquirer, then updates the order to `failed` and the related payments to `cancelled`.

        Poll the order via [Retrieve Order Details](/docs/merchant-api/retrieve-order-details) to track the final status.
      requestBody:
        description: "Order parameters"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/order.rejectOrderRequest"
      responses:
        "202":
          description: "Order rejection in progress."
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: "Order is no longer in a cancellable state (already processed)."
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /order/refund:
    post:
      tags:
        - Order
      summary: "Refund Order"
      description: |
        Process a full or partial refund for an order.

        ### Validation Rules

        The refund request will be rejected if any of the following conditions are not met:

        - **Order Status:** The order (`orderStatus`) must be in `completed` or `partially_refunded` status.
        - **Payment Status:** The specified payment (`payments[].paymentStatus.status`) must be in `completed` or `partially_refunded` status.
        - **Order Balance:** The refund amount (`cost.amount`) cannot exceed the remaining unrefunded balance of the order.
        - **Payment Balance:** The refund amount (`cost.amount`) cannot exceed the remaining unrefunded amount of the specific payment (`payments[].cost.amount`).
      requestBody:
        description: "Parameters required to process an order refund."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/order.refundOrderRequest"
      responses:
        "202":
          description: "Refund operation in progress."
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /order/capture:
    post:
      tags:
        - Order
      summary: "Capture Order"
      description: "This endpoint allows you to confirm an order in case of [two-step payment](/docs/merchant/orders/scenarios/two-stage-payments). To utilize this endpoint, the `autocapture` parameter should be set to `false`. This action is only available for orders with the status 'in_progress' and the `payments` array within the response from the [Retrieve Order Details](/docs/merchant-api/retrieve-order-details) endpoint must include at least one payment item. Refer to the [Order Actions and Conditions](/docs/merchant/orders/order-life-cycle#order-statuses)."
      requestBody:
        description: "Order parameters"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/order.captureOrderRequest"
      responses:
        "202":
          description: "Capture operation in progress."
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /order/{shopId}/{orderNumber}:
    get:
      tags:
        - Order
      summary: "Retrieve Order Details"
      parameters:
        - name: shopId
          in: path
          description: "ID of the shop where the order is placed. [How to get your shopId](/docs/common/getting-started/shop-id)"
          required: true
          schema:
            type: string
        - name: orderNumber
          in: path
          description: "Unique code identifying the specific order."
          required: true
          schema:
            type: string
            minLength: 3
            maxLength: 255
      responses:
        "200":
          description: "Order details fetched successfully."
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/order.status"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /payouts:
    post:
      tags:
        - Payout
      operationId: post_app_external_v1_payout_payout_create
      summary: Create Payout Request
      description: |
        Initiates a new payout request for a specified shop, defining the payout amount, purpose, and optional payout and recipient settings. This endpoint supports both fiat and cryptocurrency payouts. To fill out the body data of this endpoint, use the endpoints: [Retrieve Payout Methods](/docs/merchant-api/get-app-external-v-1-payout-shop-getshoppayoutmethods) and [Retrieve Required Payout Fields](/docs/merchant-api/post-app-external-v-1-payout-payoutfields-getfields).

        For cryptocurrency payouts, see the [Cryptocurrency Reference Guide](/docs/merchant/crypto) for details on supported cryptocurrencies and how to specify them using either `crypto_currency_code` with `cryptoTokenStandard` or `asset_code` format.

        For all payouts, a Time-To-Live (TTL) of 1 week is set, starting from the moment the payout is created. If the payout process has not been successfully completed within 7 days after the TTL expires, the system will automatically change the payout's status to `failed`.

        This automatic status change to `failed` indicates that the payout attempt was not completed within the required time frame. However, this status change does not stop the system from continuing to process updates or responses from the payment provider. For example, if after the status is marked as `failed`, the payment provider later confirms a successful or unsuccessful transaction, the payout status could still be updated based on this new information. The `failed` status simply reflects that the payout wasn't completed within the allowed timeframe, but it does not prevent further updates or changes to the status in the future.
      requestBody:
        description: Details of the payout request to be created, including shop ID, payout specifics, purpose, and optional settings.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePayoutRequest"
      responses:
        "201":
          description: Successfully created a new payout request.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/PayoutResponse"
                type: object
                description: A response object containing the payout request details after successful creation.
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /payouts/{shopId}/{payoutNumber}:
    get:
      tags:
        - Payout
      operationId: get_app_external_v1_payout_payout_getpayoutstatus
      summary: Retrieve Payout Status
      description: "Retrieves the current status of a specific payout operation for a shop."
      parameters:
        - name: shopId
          in: path
          required: true
          description: "ID of the shop from which the payout operation was performed. [How to get your shopId](/docs/common/getting-started/shop-id)"
          example: "1234"
          schema:
            type: string
        - name: payoutNumber
          in: path
          required: true
          description: "Payout operation number, which is obtained from the response of the [Create Payout Request](/docs/merchant-api/post-app-external-v-1-payout-payout-create) endpoint"
          schema:
            type: string
            minLength: 3
            maxLength: 255
      responses:
        "200":
          description: Payout status
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/payout.status"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /shops/{shopId}/payment-methods:
    get:
      tags:
        - Order
      operationId: get_app_external_v1_operation_shop_getshoppaymentmethods
      summary: Retrieve Payment Methods
      description: "Retrieves the list of payment methods available for a given shop, identified by its {shopId}. This endpoint provides an unfiltered list of all payment methods applicable to the shop. Optionally, the results can be narrowed down by specifying supported currencies and payment instrument types. The information obtained from this endpoint is essential for the `paymentSettings` object in the [order creation endpoint](/docs/merchant-api/create-order)."
      parameters:
        - name: currencies
          in: query
          required: false
          description: |
            Currently not implemented.

            Specifies a list of currency codes to filter available payment methods by currencies they support. 

            For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.

            For cryptocurrencies, a specific format is used; a full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies)."
          style: form
          explode: false
          example: USD
          schema:
            type: array
            items:
              type: string
        - name: instrumentTypes
          in: query
          required: false
          style: form
          explode: false
          description: "Currently not implemented. A list of payment instrument types to filter the payment methods."
          schema:
            type: array
            items:
              type: string
              enum:
                - card
                - bank_transfer
                - wallet
                - crypto_wallet
                - voucher
                - cash
        - name: shopId
          in: path
          required: true
          description: "The unique identifier of the shop for which to retrieve payment methods. [How to get your shopId](/docs/common/getting-started/shop-id)"
          schema:
            type: integer
      responses:
        "200":
          description: "Returns a list of payment methods available for the specified shop, optionally filtered by the supported currencies and instrument types."
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PaymentMethodResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /payouts/payout-methods/{shopId}:
    get:
      tags:
        - Payout
      operationId: get_app_external_v1_payout_shop_getshoppayoutmethods
      summary: Retrieve Payout Methods
      description: |
        Retrieves the list of payout methods available for a given shop, identified by its {shopId}. This endpoint provides an
        unfiltered list of all payout methods applicable to the shop.

        Optionally, the results can be narrowed down by specifying supported currencies, instrument types, regions, and transfer types.

        The information obtained from this endpoint is used to determine the list of mandatory fields required for creating a payout, as detailed in the [Retrieve Required Payout Fields](/docs/merchant-api/post-app-external-v-1-payout-payoutfields-getfields) endpoint.
      parameters:
        - name: currencies
          in: query
          required: false
          description: Currently not implemented. A list of currency codes to filter available payout methods by currencies they support. Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters.
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: "#/components/schemas/CurrencyAlpha3Type"
        - name: instrumentTypes
          in: query
          required: false
          style: form
          explode: false
          description: Currently not implemented. A list of payout instrument types to filter the payout methods.
          schema:
            type: array
            items:
              type: string
              enum:
                - card
                - bank_transfer
                - wallet
                - crypto_wallet
                - voucher
                - cash
        - name: regions
          in: query
          required: false
          description: Currently not implemented. A list of regions to filter the payout methods available in specific geographical areas. Each region should be specified by its ISO 3166-1 alpha-2 code.
          style: form
          explode: false
          schema:
            type: array
            pattern: "^[A-Z]{2}$"
            items:
              type: string
        - name: transferTypes
          in: query
          required: false
          description: |
            Currently not implemented. Applicable only for `instrumentType` == `bank_transfer`. Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type)
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - swift
                - sepa
                - bank_wire
                - card2card
                - pix
                - sbp
                - online_banking
                - open_finance
                - virtual_account
                - qris
                - promptpay
                - thaiqr
                - spei
                - vietnambanksqr
                - vietqr
                - khipu
                - paysafecard
                - multibanco
                - bancontact
                - blik
                - p24
                - rapidtransfer
                - thb_qr
                - upi
                - upi_intent
                - sberbank
                - giropay
                - eps
                - account2card
                - fpx
                - trustly
                - wise
                - n26
                - pesalink
                - imps
                - upi_p2p
                - upi_fast_vip
                - mybank
                - tink
                - bizum
                - sofort
                - p2p
                - easypay
                - klarna
                - clabe
                - codi
                - rapipago
                - pse
        - name: shopId
          in: path
          required: true
          description: The unique identifier of the shop for which to retrieve payout methods.
          schema:
            type: integer
      responses:
        "200":
          description: Returns a list of payout methods available for the specified shop, optionally filtered by the supported currencies and instrument types.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PayoutMethodResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /payouts/fields:
    post:
      tags:
        - Payout
      summary: Retrieve Required Payout Fields
      operationId: post_app_external_v1_payout_payoutfields_getfields
      description: |
        This endpoint retrieves data fields required to fill the `recipient` / `sender` object for a payout. You can get a list of required parameters  for your store from [Retrieve Payout Methods](/docs/merchant-api/get-app-external-v-1-payout-shop-getshoppayoutmethods). Upon calling this endpoint, you will receive a `recipient` / `sender` object with fields that need to be filled out and submitted in the [payout creation endpoint](/docs/merchant-api/post-app-external-v-1-payout-payout-create)."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - providerCode
                - acquirerCode
                - instrumentType
                - payoutSettings
              properties:
                instrumentType:
                  type: string
                  description: "The instrument type for which the required fields are being requested."
                  enum:
                    - bank_transfer
                    - card
                    - wallet
                    - crypto_wallet
                    - voucher
                    - cash
                providerCode:
                  type: string
                  description: "The provider code for which the required fields are being requested."
                acquirerCode:
                  type: string
                  description: "The acquirer code for which the required fields are being requested."
                customer:
                  nullable: true
                  type: object
                  properties:
                    customerId:
                      type: string
                      description: "The unique identifier of the customer for which the required fields are being requested."
                      example: "cust789"
                      nullable: true
                payoutSettings:
                  type: object
                  required:
                    - region
                    - currency
                    - shopId
                  properties:
                    region:
                      type: string
                      description: "The payment region for which the required fields are being requested. Region should be specified by its ISO 3166-1 alpha-2 code."
                      example: "US"
                      pattern: "^[A-Z]{2}$"
                    currency:
                      type: string
                      description: "The payment currency for which the required fields are being requested. Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
                      example: "USD"
                      pattern: "^[A-Z]{3}$"
                    shopId:
                      type: string
                      description: "The shop ID for which the required fields are being requested."
                      example: "1234567890"
                    transferType:
                      type: string
                      nullable: true
                      description: "The type of bank transfer for which the required fields are being requested. Required for instrumentType = bank_transfer. See details about [transferType](/docs/merchant/instrument-type#transfertype-for-instrumenttype--bank_transfer-)"
                      enum:
                        - swift
                        - sepa
                        - bank_wire
                        - card2card
                        - pix
                        - sbp
                        - online_banking
                        - open_finance
                        - virtual_account
                        - qris
                        - promptpay
                        - thaiqr
                        - spei
                        - vietnambanksqr
                        - vietqr
                        - khipu
                        - paysafecard
                        - multibanco
                        - bancontact
                        - blik
                        - p24
                        - rapidtransfer
                        - thb_qr
                        - upi
                        - upi_intent
                        - sberbank
                        - giropay
                        - eps
                        - account2card
                        - fpx
                        - trustly
                        - wise
                        - n26
                        - pesalink
                        - imps
                        - upi_p2p
                        - upi_fast_vip
                        - mybank
                        - tink
                        - bizum
                        - sofort
                        - p2p
                        - easypay
                        - klarna
                        - clabe
                        - codi
                        - rapipago
                        - pse
      responses:
        "200":
          description: A list of required fields for the specified payout method. The response format for the recipient and sender objects is the same. The recipient object is always included in the response, while the sender object is included only for those payouts where it is necessary.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - recipient
                      - payoutOptions
                    properties:
                      recipient:
                        type: array
                        items:
                          $ref: "#/components/schemas/RequiredPayoutFieldsResponse"
                      sender:
                        type: array
                        items:
                          $ref: "#/components/schemas/RequiredPayoutFieldsResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /payouts/cancel:
    post:
      tags:
        - Payout
      summary: "Cancel Payout(🚧 in development)"
      description: |
        Cancels an in-progress payout. This endpoint can only be used if the payout is in the `in_progress` status and the `recipient` object was not provided when the payout was initiated (meaning the payout details are to be filled on the payment page). This allows for the cancellation of the created payment page and, thereby, the payout itself.

        If the `recipient` object was provided during payout creation, this endpoint is not applicable.
      requestBody:
        description: "Payout parameters"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/payout.cancelPayoutRequest"
      responses:
        "200":
          description: "Payout cancellation successful"
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/payout.cancelOperationResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /payouts/reject:
    post:
      tags:
        - Payout
      summary: "Reject Payout(🚧 in development)"
      description: "Rejects a payout. This operation is only applicable to payouts in the 'completed' status and can only be performed if the payout provider (identified by `providerCode`) supports the rejection of successfully completed payouts."
      requestBody:
        description: "Payout parameters"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/payout.rejectPayoutRequest"
      responses:
        "200":
          description: "Payout rejection successful"
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/payout.rejectOperationResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /customers:
    post:
      summary: "Create New Customer"
      tags:
        - Common
      description: |
        This endpoint creates a new customer in the system.

        The system will ensure the uniqueness of the customer either within the entire company or a shop. This depends on whether you include shopId in the request or not.
        If the customer already exists for the company or the shop, the system returns an error.
      requestBody:
        description: "Customer creation request data."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/createCustomerRequest"
      responses:
        "201":
          description: "Customer successfully created."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/createCustomerResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
    get:
      summary: "Retrieve Customer Information"
      tags:
        - Common
      description: |
        This endpoint retrieves information about customers in the system.

        The system searches for customers based on the provided `customerId`, and optionally `shopId`. If `shopId` is not provided, the system searches for customers linked directly to the company.

      operationId: Customers
      parameters:
        - name: customerIds
          description: "A comma-separated list of customer identifiers in the merchant's system."
          in: query
          required: true
          style: form
          explode: true
          allowReserved: true
          schema:
            type: array
            items:
              type: string
            example:
              - "cust789"
              - "cust123"
        - name: shopId
          in: query
          description: |
            The unique identifier of the shop within the merchant company. If not provided, the system searches for customers linked directly to the company.
          required: false
          schema:
            type: string
            example: "456"
      responses:
        "200":
          description: "Customer information retrieved successfully."
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/CustomerListResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /recurring-charge-retry-settings/{settingsUuid}:
    get:
      tags:
        - Recurring Payments
      summary: Retrieve Retry Settings
      description: |
        Retrieves the retry settings configuration for recurring payment charges. These settings determine how the system handles failed recurring charges.
      operationId: get_app_external_v1_recurring_recurringchargeretrysettings_get
      parameters:
        - name: settingsUuid
          in: path
          description: "The unique identifier of the retry settings configuration."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
          example: "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
      responses:
        "200":
          description: Recurring charges retry settings retrieved successfully
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1RecurringResponseRecurringChargesRetrySettingsResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
    put:
      tags:
        - Recurring Payments
      summary: Update Retry Settings
      description: |
        Updates the retry settings configuration for recurring payment charges.
      operationId: put_app_external_v1_recurring_recurringchargeretrysettings_update
      parameters:
        - name: settingsUuid
          in: path
          description: "The unique identifier of the retry settings configuration to update."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
          example: "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
      requestBody:
        description: "The updated retry settings parameters."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1RecurringRequestUpdateRecurringChargesRetrySettingsRequest"
      responses:
        "200":
          description: Recurring charges retry settings updated successfully
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1RecurringResponseRecurringChargesRetrySettingsResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
    delete:
      tags:
        - Recurring Payments
      summary: Delete Retry Settings
      description: |
        Permanently deletes the retry settings configuration for recurring payment charges. Once deleted, the system will use default retry settings for any recurring charges associated with the shop.
      operationId: delete_app_external_v1_recurring_recurringchargeretrysettings_delete
      parameters:
        - name: settingsUuid
          in: path
          description: "The unique identifier of the retry settings configuration to delete."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
          example: "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
      responses:
        "204":
          description: Recurring charges retry settings deleted successfully
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /recurring-charge-retry-settings:
    post:
      tags:
        - Recurring Payments
      summary: Create Retry Settings
      description: |
        Creates a new retry settings configuration for recurring payment charges associated with a specific shop.
      operationId: post_app_external_v1_recurring_recurringchargeretrysettings_create
      requestBody:
        description: "The retry settings configuration parameters for the shop."
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1RecurringRequestCreateRecurringChargesRetrySettingsRequest"
      responses:
        "201":
          description: Recurring charges retry settings created successfully
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1RecurringResponseRecurringChargesRetrySettingsResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /recurring/{recurringUuid}:
    get:
      tags:
        - Recurring Payments
      summary: Retrieve Recurring Payment Profile
      description: |
        Retrieves detailed information about a specific recurring payment profile. Use this endpoint to track the lifecycle of recurring payments and monitor all associated charges and retry attempts.
      operationId: get_app_external_v1_recurring_recurringpayments_getrecurring
      parameters:
        - name: recurringUuid
          in: path
          description: "The unique identifier of the recurring payment profile."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        "200":
          description: Recurring payment profile details retrieved successfully
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1RecurringResponseRecurringProfileResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /recurring/{recurringUuid}/cancel:
    post:
      tags:
        - Recurring Payments
      summary: Cancel Recurring Payment
      description: |
        Cancels an active recurring payment profile. Once cancelled, no further charges will be scheduled or processed for this recurring payment.

        **Cancellation behavior:**
        - All charges with status 'scheduled' will be cancelled
        - All charges with status 'retry_pending' will be cancelled
        - All retry attempts with status 'scheduled' will be cancelled
        - Any charges currently in progress will be allowed to complete

        This operation is idempotent - repeated cancellation requests will not cause errors.
      operationId: post_app_external_v1_recurring_recurringpayments_cancelrecurring
      parameters:
        - name: recurringUuid
          in: path
          description: "The unique identifier of the recurring payment profile to cancel."
          required: true
          schema:
            type: string
            pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        "204":
          description: Recurring payment cancelled successfully
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /chargebacks/{shopId}:
    get:
      tags:
        - Chargeback
      operationId: get_app_external_v1_order_chargeback_getchargebacks
      summary: "Retrieve chargebacks"
      parameters:
        - name: shopId
          in: path
          required: true
          description: |
            The unique identifier of the shop for which to retrieve chargeback information.
            [How to get your shopId](/docs/common/getting-started/shop-id)
          example: 1234
          schema:
            type: integer

        - name: limit
          in: query
          required: false
          description: |
            Specifies the maximum number of records to return in the response.
            The value must be between 1 and 200. If not provided, the default is 50.
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 200
            nullable: true

        - name: orderNumber
          in: query
          required: false
          description: |
            Filters the results by a specific order number.
            If provided, only chargebacks related to this order will be returned.
          example: "ORDER123"
          schema:
            type: string
            maxLength: 64
            nullable: true

        - name: startDate
          in: query
          required: false
          description: |
            The start date for filtering chargebacks by creation date.
            Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). If not specified, no lower date limit is applied.
          example: "2023-01-01T00:00:00Z"
          schema:
            type: string
            nullable: true

        - name: endDate
          in: query
          required: false
          description: |
            The end date for filtering chargebacks by creation date.
            Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). If not specified, no upper date limit is applied.
          example: "2023-12-31T23:59:59Z"
          schema:
            type: string
            nullable: true
      responses:
        "200":
          description: List of orders with chargebacks.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/V1OrderResponseOrderChargebacksResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /3ds/verification-result/{shopId}/{orderNumber}:
    post:
      tags:
        - 3DS
      summary: "Process 3DS Verification Result"
      description: |
        Use this endpoint to submit the result of a 3-D Secure (3DS) verification process for a specific order. This endpoint is typically called after the customer completes the 3DS authentication flow.

      operationId: post_app_external_v1_threeds_threeds_processverificationresult
      parameters:
        - name: shopId
          in: path
          required: true
          description: "ID of the shop where the order is placed. [How to get your shopId](/docs/common/getting-started/shop-id)"
          schema:
            type: string
        - name: orderNumber
          in: path
          required: true
          description: "Unique code identifying the specific order."
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1ThreeDsRequestProcessVerificationRequest"
      responses:
        "204":
          description: "3DS verification result successfully processed."
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /p2p:
    post:
      tags:
        - "P2P"
      summary: "Create P2P Transaction"
      description: >
        Initiates a new person-to-person (P2P) transaction from the sender to the recipient.
      requestBody:
        required: true
        description: "Data required to create a new P2P transaction."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateP2PRequest"
      responses:
        "201":
          description: "P2P transaction was successfully created."
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/P2PResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /p2p/{shopId}/{p2pNumber}:
    get:
      tags:
        - "P2P"
      summary: "Retrieve P2P Transaction Status"
      description: >
        Returns the current status of a previously created P2P transaction,
        identified by `p2pNumber` and `shopId`.
      parameters:
        - name: shopId
          in: path
          required: true
          schema:
            type: integer
          description: "The unique identifier of the shop where the P2P transaction was created."
          example: 123
        - name: p2pNumber
          in: path
          required: true
          schema:
            type: string
          description: "The unique P2P transaction number provided by the merchant."
          example: "56573FDFVFDBWF"
      responses:
        "200":
          description: "P2P transaction status retrieved successfully."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/P2PStatusResponse"
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."

  /customers/{customerId}/saved-cards:
    get:
      tags:
        - Saved Card
      operationId: get_app_external_v1_savedcard_customer_getsavedcards
      summary: Retrieve Saved Cards
      description: |
        Retrieves a list of saved cards associated with a specific customer. This endpoint returns card details that can be used for subsequent payments.
      parameters:
        - name: customerId
          in: path
          description: Unique identifier of the customer whose saved cards are being retrieved.
          required: true
          schema:
            type: string
          example: "56656"
        - name: shopId
          in: query
          description: If provided, returns only cards linked to the specified shop. If omitted, returns cards linked to the company level.
          required: false
          schema:
            type: integer
            nullable: true
          example: 123
      responses:
        "200":
          description: Saved-cards
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/V1SavedCardResponseSavedCardResponse"
                type: object
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
  /order/review/result:
    post:
      tags:
        - Antifraud
      summary: "Submit Antifraud Review Decision"
      description: |
        Use this endpoint to submit your decision for orders and payouts that require manual antifraud review.

        When an order or payout triggers an antifraud rule configured with the **review** action, the system pauses the transaction and sends you a callback notification with status `review`. You must then review the transaction details and submit your decision using this endpoint within the specified timeout period.

        **Decision Options:**
        - **accept**: Approve the transaction and resume processing
        - **decline**: Reject the transaction

        If no decision is submitted within the timeout period specified in the callback (`reviewTimeout`), the transaction will be automatically declined.

        For more information about the antifraud review process, see [Antifraud Manual Review](/docs/merchant/antifraud-review).
      requestBody:
        description: "Review decision parameters"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/order.reviewResultRequest"
      responses:
        "200":
          description: "Review decision accepted and processing will continue based on your decision."
        "400":
          description: "Invalid request parameters."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "Authentication failed. Verify that a valid Api-Access-Token is provided in the request headers."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "Access denied. The API token does not have permission for the specified shop, or the request was blocked by a security policy."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: "Resource not found."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "412":
          description: "Precondition failed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: "Internal server error. An unexpected error occurred on the server side."
        "502":
          description: "Service unavailable. The upstream service is temporarily unreachable."
        "503":
          description: "Service unavailable. The server is temporarily unable to handle the request."
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Access-Token
  schemas:
    ErrorResponse:
      type: object
      description: "Error response returned for 4xx errors."
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: "Human-readable error message describing the issue."
        code:
          type: integer
          description: "HTTP status code of the error."
    order.createOrderRequest:
      required:
        - order
        - shopId
      type: object
      properties:
        shopId:
          type: integer
          description: "The unique identifier for the shop creating the order. [How to get your shopId](/docs/common/getting-started/shop-id)"
          example: 1234
        order:
          type: object
          description: "Container for order-related information."
          required:
            - cost
            - orderNumber
          properties:
            orderNumber:
              minLength: 3
              maxLength: 255
              type: string
              description: |
                A unique identifier for the order that you must generate on your side. The `orderNumber` should be specific to the `shopId` or your company (depending on your company's settings) and must be unique for every order and payout within each `shopId` or your company (depending on your company's settings).
                The `orderNumber` may contain only Latin letters (uppercase and lowercase), numbers, and hyphens. Hyphens cannot be at the beginning or end of the string.
              example: "56573FDFVFDBWF"
            localDateTime:
              description: Local date and time of the order in payer's timezone. Need only in h2h orders. Format ISO 8601 (YYYY-MM-DD HH:MM:SS).
              type: string
              nullable: true
              example: "2025-03-31T15:16:23Z"
            description:
              type: string
              maxLength: 128
              description: "Optional text providing additional context for the order."
              example: "Internal reference #123"
            cost:
              type: object
              required:
                - amount
                - currency
              properties:
                amount:
                  type: string
                  description: |
                    Represents the total amount for this order in a decimal string format.
                    For fiat currencies, follow ISO 4217 decimal precision standards.
                    For cryptocurrencies, specify the amount according to the crypto's precision.

                    If you are using recurring payments, this represents the amount that will be charged for EACH recurring payment (not the total sum of all charges).

                  example: "56.99"
                currency:
                  type: string
                  description: |
                    Specifies the currency.

                    For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.

                    For cryptocurrencies, a specific format is used; a full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies).
                  example: "PHP"
              description: "Contains overall financial details of the order. If you have recurring payments, this object represents the base cost from which the recurring calculations derive."
            recurringPayments:
              type: object
              nullable: true
              required:
                - intervalType
                - billingIntervalQuantity
              description: |
                Optional settings for creating a recurring subscription.

                **Requirements:**
                - Only available when `instrumentType=card` and a valid `customerId` is present
                - The payment provider must support recurring payments
                - For the initial payment.

                **Behavior:**
                - After a successful initial payment, a recurring payment profile is created with status 'active'
                - An operation of type `recurring_initial_payment` is created for the initial payment
                - All subsequent automatic charges will have `entryMode` set to 'recurring'
                - If the initial payment fails (status: failed, cancelled), the recurring profile will be physically deleted from the system

                **Response:**
                - Upon successful creation, the subscription details will be returned in the response of order stauts endpoint and callbacks via the `recurringPayments` object.
                - To retrieve complete subscription information including payment history and retry attempts, use the [Retrieve Recurring Payment Profile](/docs/merchant-api/get-app-external-v-1-recurring-recurringpayments-getrecurring) endpoint
              properties:
                billingIntervalQuantity:
                  type: integer
                  description: "Number of interval units between recurring charges."
                  example: 1
                intervalType:
                  type: string
                  enum: [day, week, month, year]
                  description: "Unit of the billing interval (day, week, month, or year)."
                  example: "month"
                endDate:
                  type: string
                  format: date-time
                  description: "Date and time when the recurring payment schedule ends (ISO 8601 format). Used to limit recurring charges by date. Cannot be used together with `paymentCount`. If neither `endDate` nor `paymentCount` is provided, the subscription continues indefinitely."
                  example: "2024-12-01T14:30:00+03:00"
                  nullable: true
                paymentCount:
                  type: integer
                  nullable: true
                  description: "Total number of payments to be made, including the initial payment. Cannot be used together with `endDate`. If neither `endDate` nor `paymentCount` is provided, the subscription continues indefinitely."
                  example: 3
        customer:
          $ref: "#/components/schemas/customer"
        paymentSettings:
          type: object
          nullable: true
          properties:
            entryMode:
              type: string
              nullable: true
              description: |
                Specifies the method by which payment data is entered and should only be used when `instrumentType` == `card`. 

                **Entry modes:**
                - **cnp** - Card Not Present
                - **card_present** - Card Present (physical card)
                - **moto** - Mail Order / Telephone Order
                - **recurring** - Recurring payment. **Note:** This value is set automatically by the system for all subsequent recurring charges. Do NOT set it manually for the initial payment when creating a subscription via the `recurringPayments` object.
                - **saved_card** - Payment using a previously saved card. Requires `payer.cardData.savedCardId` and `customer.customerId` to be provided.
                - **apple_pay** - Apple Pay
                - **google_pay** - Google Pay
                - **samsung_pay** - Samsung Pay

                [Payment Entry Modes for instrument type card](/docs/merchant/instrument-type#payment-entry-modes-for-payment-instrument-card)
              example: null
              enum:
                - cnp
                - card_present
                - moto
                - recurring
                - saved_card
                - apple_pay
                - google_pay
                - samsung_pay
            instrumentType:
              type: string
              nullable: true
              description: "Specifies the instrument type. [See available instrument types](/docs/merchant/instrument-type)"
              example: "wallet"
              enum:
                - card
                - bank_transfer
                - wallet
                - crypto_wallet
                - voucher
                - cash
            providerCode:
              type: string
              nullable: true
              description: "Determines which payment provider should be used to process the payment."
              example: "connectpay"
            acquirerCode:
              description: "Identifies the specific acquirer responsible for processing payments."
              type: string
              nullable: true
              example: "gcash"
            transferType:
              description: "Applicable only when `instrumentType` is `bank_transfer`. Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type). If `instrumentType` is `bank_transfer` and `transferType` is not provided, but there is only one possible `transferType` configured for the shop, it will be selected automatically by the system."
              type: string
              nullable: true
              enum:
                - swift
                - sepa
                - bank_wire
                - card2card
                - pix
                - sbp
                - online_banking
                - open_finance
                - virtual_account
                - qris
                - promptpay
                - thaiqr
                - spei
                - vietnambanksqr
                - vietqr
                - khipu
                - paysafecard
                - multibanco
                - bancontact
                - blik
                - p24
                - rapidtransfer
                - thb_qr
                - upi
                - upi_intent
                - sberbank
                - giropay
                - eps
                - account2card
                - fpx
                - trustly
                - wise
                - n26
                - pesalink
                - imps
                - upi_p2p
                - upi_fast_vip
                - mybank
                - tink
                - bizum
                - sofort
                - p2p
                - easypay
                - klarna
                - clabe
                - codi
                - rapipago
                - pse
            dataEntryMode:
              type: "string"
              nullable: true
              description: |
                Methods for customer data entry to process payment:

                redirect - the customer enters payment information on the provider's (acquirer's) page via redirect;

                h2h (host2host) - the customer enters payment information on our payment page;

                qr - the customer scans a QR code and enters information on the aggregator's side.

                **instruction** - provides payment instructions to the customer, such as manual payment steps.
                When using `instruction` with `paymentPageDesign.format = shop_hosted`:
                - The `payer` object with required fields must be provided in the request. If payer data is insufficient, validation error will be returned
                - Instead of displaying instructions on the payment page, the system sends instruction parameters via webhook and [Retrieve Order Details](/docs/merchant-api/retrieve-order-details) response
                - Instruction parameters are returned in the `operationReference` object within the `payments` array of the webhook payload and in [Retrieve Order Details](/docs/merchant-api/retrieve-order-details) response

                **iframe** - embeds the payment form directly to the payment page, offering a seamless user experience without redirecting the customer to a new page.

                **html** - the payment details or form are delivered as HTML content.
              enum:
                - qr
                - redirect
                - h2h
                - instruction
                - iframe
                - html
            autoCapture:
              type: boolean
              nullable: true
              description: "Set to `true` or omit this parameter for one-stage payments where funds are automatically captured. Set to `false` for two-stage payments requiring manual capture. [How to work with two-stage payments](/docs/merchant/orders/scenarios/two-stage-payments)"
              example: true
            timeLimit:
              type: string
              nullable: true
              description: |
                Specifies the expiration time for the payment page in RFC 3339 format, including the UTC zone. This field determines how long the payment page remains active for the payer to initiate a payment.

                **Behavior:**
                - **If specified:** The payment page remains active until the specified `timeLimit`.
                - **If omitted:** The payment page remains active for exactly 15 minutes from the moment of order creation.

                **Outcomes:**
                - If the time expires before the payer initiates a transaction, the order is automatically moved to the `cancelled` status.
                - If the payer enters their payment details and initiates the transaction within this timeframe, the payment process continues according to the standard flow.
              example: "2024-02-03T10:51:49.086Z"
            redirectUrls:
              type: object
              nullable: true
              properties:
                success:
                  type: string
                  nullable: true
                  description: "URL to redirect the user to after a successful payment completion. If not specified, the default will be the URL of the shop that created the order."
                  format: uri
                  example: "https://example.com/success"
                failure:
                  type: string
                  nullable: true
                  description: "URL to redirect the user to in the event of a payment failure. If not specified, the default will be the URL of the shop that created the order."
                  format: uri
                  example: "https://example.com/failure"
                inProgress:
                  type: string
                  nullable: true
                  description: "Used only for payments with 3DS on the merchant's side. URL to redirect the user to in the event of a payment in progress."
                  format: uri
                  example: "https://example.com/inProgress"
                pending:
                  type: string
                  nullable: true
                  description: "URL to redirect the user to in the event of a payment pending."
                  format: uri
                  example: "https://example.com/pending"
              description: "Container for URLs to redirect to post-payment."
            webhookUrl:
              type: string
              nullable: true
              format: uri
              pattern: '^https:\/\/.*'
              example: "https://example.com/webhook"
              description: |
                This parameter allows you to specify a webhook URL for receiving notifications about order status changes for this specific order.

                If provided, notifications about the order status changes will be sent to this URL instead of the [general webhook URL](/docs/common/getting-started/callbacks) set for the shop.
            paymentSettingsAlias:
              type: string
              nullable: true
              example: "alias2"
              description: |
                Use this field to specify which alias should be applied for this operation. The alias ensures that the correct payment configuration is used.

                This value is obtained from the `paymentSettingsAlias` field in the [Retrieve Payment Methods](/docs/merchant-api/get-app-external-v-1-operation-shop-getshoppaymentmethods) for orders or from Merchant Account Dashboard for payouts. 

                For more detailed information about how to use aliases, refer to the [Alias Documentation](/docs/merchant/alias)

            mcc:
              type: integer
              description: "Merchant Category Code (MCC) is a four-digit number that classifies the type of business or service for a transaction. This field is optional, but for card payments, it is recommended to provide the MCC if more than one code is configured for your payment settings. If only one MCC is configured, it will be used automatically."
              maxLength: 4
              minLength: 4
              nullable: true
              example: 5999

          description: |
            Container for payment method details. Using `paymentSettings`, you can select the method to process the payment.

            To fill out the `paymentSettings` object and obtain other information about payment methods available for your shop ID, use [Retrieve Payment Methods endpoint](/docs/merchant-api/get-app-external-v-1-operation-shop-getshoppaymentmethods).
        paymentPageDesign:
          type: object
          nullable: true
          properties:
            alias:
              type: string
              nullable: true
              description: "A code for customizing the payment page's appearance, set through technical support."
              example: "default"
            format:
              type: string
              nullable: true
              description: "Defines the method of integrating the payment form on your website. 'shop_hosted' - the payment page is hosted on the merchant's side, 'redirect' takes the user to a hosted payment page, ensuring a separate and secure environment for transaction processing. 'iframe' embeds the payment form directly within your website, offering a seamless and integrated user experience without navigating away from your site.\n[Information about redirect](/docs/merchant/orders/payment-page-options/payment-gate-hosted), [Information about iframe](/docs/merchant/orders/payment-page-options/merchant-hosted)"
              example: "redirect"
              enum:
                - redirect
                - iframe
                - shop_hosted
            language:
              type: string
              nullable: true
              description: |
                Sets the language displayed on the payment page for the payer. Use an ISO 639-1 language code (for example, "en" for English). If an unsupported language is provided, the payment page defaults to English. If not specified, the language is automatically determined based on the payer's IP address.
        payer:
          type: object
          nullable: true
          description: |
            The 'payer' object is used to transmit card data and additional payer details during a host-to-host (h2h) payment.
            By providing the payment information and any extra information in this object, the merchant ensures that the payer does not have to manually enter their information on the payment page.

            **Priority rules when both `customer` and `payer` are provided:**
            - If the company setting "Use customer data as payer information" is enabled, data from `customer` and `payer` objects will be merged
            - Fields from `payer` object take priority over corresponding fields from `customer` (including `payer.personalData.id` over `customer.customerId`)
            - Missing fields in `payer` will be supplemented from `customer` data

            For more details, see [Customer and Payer Data](/docs/merchant/person-data).
          properties:
            cardData:
              type: object
              nullable: true
              description: |
                Contains bank card details for processing card payments. This object should be provided when dataEntryMode is 'h2h' and instrumentType is 'card'.

                **Note:** Direct card data submission may be restricted based on your merchant configuration.
              required:
                - cardNumber
                - cardHolderName
                - cvv
                - expireMonth
                - expireYear
              properties:
                cardNumber:
                  type: string
                  description: "The card number (PAN)."
                  example: "4111111111111111"
                cardHolderName:
                  type: string
                  description: "The full name of the cardholder as printed on the card."
                  example: "JOHN A DOE"
                cvv:
                  type: string
                  description: "The card's security code (CVV/CVC)."
                  example: "010"
                expireMonth:
                  type: string
                  description: "Card expiration month in MM format."
                  example: "12"
                expireYear:
                  type: string
                  description: "Card expiration year in YYYY format."
                  example: "2023"
                savedCardId:
                  type: string
                  nullable: true
                  description: |
                    The unique identifier of a previously saved card to be used for payment. This field should be provided when making a payment with a saved card.

                    **Requirements:**
                    - Must be used with `paymentSettings.entryMode` set to `saved_card`
                    - The `customer.customerId` field must also be provided
                    - The card must be linked to the specified customer

                    To retrieve available saved cards, use the [Retrieve Saved Cards](/docs/merchant-api/get-app-external-v-1-savedcard-customer-getsavedcards) endpoint.
                  example: "550e8400-e29b-41d4-a716-446655440000"
            personalData:
              type: object
              nullable: true
              description: "Holds personal information of the payer for verification and fraud checks."
              properties:
                id:
                  type: string
                  nullable: true
                  description: "The unique identifier for the payer from the merchant's system."
                  example: "1234567890123456"
                firstName:
                  type: string
                  nullable: true
                  description: "Payer's first name."
                  example: "John"
                lastName:
                  type: string
                  nullable: true
                  description: "Payer's last name."
                  example: "Smith"
                phone:
                  type: string
                  nullable: true
                  description: "Payer's phone number in international format."
                  example: "+15557654321"
                email:
                  type: string
                  nullable: true
                  description: "Payer's email address."
                  example: "john.smith@example.com"
                birthDate:
                  type: string
                  nullable: true
                  description: "Payer's date of birth in ISO 8601 format (YYYY-MM-DD)."
                  example: "2000-12-01"
            documentData:
              type: object
              nullable: true
              description: "Contains identification document details of the payer."
              properties:
                documentType:
                  nullable: true
                  type: string
                  description: "Type of the document (e.g., passport, driver's license)."
                  example: "BR_PP"
                documentNumber:
                  type: string
                  nullable: true
                  description: "The document number."
                  example: "DOC12345678"
            billingAddress:
              type: object
              nullable: true
              description: "The billing address for the payer"
              properties:
                addressLine1:
                  nullable: true
                  type: string
                  description: "Primary address line."
                  example: "7, Sunny street"
                addressLine2:
                  type: string
                  nullable: true
                  description: "Secondary address line, if applicable."
                  example: "Office 3"
                city:
                  type: string
                  nullable: true
                  description: "City of the billing address."
                  example: "Limassol"
                countryCode:
                  type: string
                  nullable: true
                  description: "Country code in ISO 3166-1 alpha-2 format."
                  example: "CY"
                zipCode:
                  type: string
                  nullable: true
                  description: "Postal code."
                  example: "4141"
                state:
                  type: string
                  nullable: true
                  description: "State or region."
                  example: "CA"
            bankTransferData:
              $ref: "#/components/schemas/PayerBankTransferData"
            browser:
              type: object
              nullable: true
              description: "Contains browser and device details from the payer."
              properties:
                ipAddress:
                  type: string
                  nullable: true
                  description: "Payer's IP address."
                  example: "1.2.3.4"
                acceptHeader:
                  type: string
                  nullable: true
                  description: "The Accept header from the payer's browser."
                  example: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8"
                colorDepth:
                  type: number
                  nullable: true
                  description: "Screen color depth in bits."
                  example: 24
                javaEnabled:
                  type: boolean
                  nullable: true
                  description: "Indicates whether Java is enabled in the browser."
                  example: false
                javascriptEnabled:
                  type: boolean
                  nullable: true
                  description: "Indicates whether JavaScript is enabled in the browser."
                  example: true
                acceptLanguage:
                  type: string
                  nullable: true
                  description: "The Accept-Language header from the browser."
                  example: "en-GB"
                screenWidth:
                  type: number
                  nullable: true
                  description: "Screen width in pixels."
                  example: 412
                screenHeight:
                  type: number
                  nullable: true
                  description: "Screen height in pixels."
                  example: 846
                timeZone:
                  type: number
                  nullable: true
                  description: "Time zone offset from UTC in hours."
                  example: 0
                userAgent:
                  type: string
                  nullable: true
                  description: "The User-Agent string from the payer's browser."
                  example: "Mozilla/5.0 (Linux; Android 10; SM-G965F Build/QP1A.190711.020; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/106.0.5249.126 Mobile Safari/537.36"
        cryptoPayment:
          nullable: true
          description: |
            Contains cryptocurrency payment details required for crypto wallet creation and payment processing.

            This object enables merchants to process cryptocurrency payments by automatically creating 
            a crypto wallet for the customer during order creation. When provided, the system will:
            1. Create a crypto wallet for the customer (if one doesn't exist)
            2. Generate wallet address and QR code for payment
            3. Display payment details on the checkout page

            **Usage scenarios:**
            - For simple crypto payments: Only specify `walletTokenStandard` if needed
            - For provider-specific requirements: Include `accountCurrency` details when the payment 
              provider requires a specific account denomination currency

            **Note:** This object is optional for cryptocurrency payments. It must be provided only when:
            - Using token-based cryptocurrencies (e.g., USDT, USDC) with `crypto_currency_code` format in `order.cost.currency`
            - When the payment provider requires `accountCurrency` specification

            Not required when using native cryptocurrencies (BTC, ETH) or asset_code format (e.g., USDT_TRC20) in `order.cost.currency`.

            **Important:** For cryptocurrency payments, customer identification is required. See the `customer` object documentation for details on required fields.
          properties:
            walletTokenStandard:
              description: |
                The token standard for the customer's wallet cryptocurrency.

                **When to use:**
                - Required for token-based cryptocurrencies (e.g., USDT, USDC)
                - Not required for native cryptocurrencies (BTC, ETH, SOL, TRX, LTC)

                **Examples:**
                - "TRC20" for USDT on Tron network
                - "ERC20" for tokens on Ethereum network
                - "BEP20" for tokens on Binance Smart Chain

                **Important:** This refers to the token standard of the cryptocurrency 
                specified in `order.cost.currency`.
              type: string
              example: TRC20
              nullable: true
            accountCurrency:
              nullable: true
              type: object
              description: |
                Merchant account currency configuration for cryptocurrency payments.

                **When to use:**
                Some payment providers require specifying an account currency that differs 
                from the payment currency. This is common when the provider needs to know the denomination currency for the merchant's account
              required:
                - currency
              properties:
                currency:
                  description: |
                    The currency in which the merchant's account will be denominated.

                    **Supported formats:**
                    - Fiat currencies: ISO 4217 format (e.g., "USD", "EUR", "GBP")
                    - Cryptocurrencies: Standard symbols (e.g., "BTC", "ETH", "USDT")

                  type: string
                  example: USDT
                networkTokenStandard:
                  description: |
                    The token standard for the merchant account currency (if applicable).

                    **When to use:**
                    - Required when `currency` is a token-based cryptocurrency
                    - Not required for native cryptocurrencies or fiat currencies
                    - Must match the network/standard supported by your payment provider

                    **Examples:**
                    - "ERC20" for USDT on Ethereum network
                    - "TRC20" for USDT on Tron network
                    - "BEP20" for tokens on Binance Smart Chain
                    - null or omit for BTC, ETH, USD, EUR, etc.
                  type: string
                  example: ERC20
                  nullable: true
          type: object
    order.createOrderResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - orderNumber
          properties:
            orderNumber:
              type: string
              description: "A unique identifier for the order, generated by the merchant, and specific to each `shopId`."
              example: "56573FDFVFDBWF"
            paymentLink:
              type: string
              nullable: true
              description: "URL directing the user to the payment interface. If the order is not requered payment page, this field will be empty."
              format: uri
              example: "https://someurlwhereyoucanspendyourmoney.com"

    V1SavedCardResponseSavedCardResponse:
      title: V1-SavedCard-Response-SavedCardResponse
      description: Saved card
      required:
        - cardId
        - maskedCardNumber
        - expiryMonth
        - expiryYear
      properties:
        cardId:
          type: string
          description: Unique identifier of the saved card.
          example: "550e8400-e29b-41d4-a716-446655440000"
        maskedCardNumber:
          description: Masked card number.
          type: string
          example: 123456******1234
        cardBrand:
          description: Brand of the card (paysystem).
          type: string
          enum:
            - visa
            - mastercard
            - discover
            - unionpay
            - jcb
            - amex
            - elo
            - hipercard
            - mir
            - dci
            - upi
            - redcompra
            - maestro
            - verve
          nullable: true
        expiryMonth:
          type: string
          description: Expiration month of the card.
          example: "12"
        expiryYear:
          type: string
          description: Expiration year of the card.
          example: "2026"
        issuerOrganization:
          type: string
          nullable: true
          description: Name of the card issuing organization or bank.
          example: "CHINA CITIC BANK"
      type: object
    order.cancelOrderRequest:
      type: object
      required:
        - shopId
        - orderNumber
      properties:
        shopId:
          type: integer
          description: "Unique identifier for the shop where the order was placed."
          example: 1234
        orderNumber:
          type: string
          description: "Unique code identifying the order to be cancelled."
          example: "ORDER-324234"
        description:
          type: string
          maxLength: 128
          nullable: true
          description: "Optional free text providing additional context or reason for the cancellation."
          example: "Order cancelled due to customer request."

    order.rejectOrderRequest:
      required:
        - orderNumber
        - shopId
      type: object
      properties:
        shopId:
          type: integer
          description: "ID of the shop where the order is placed. [How to get your shopId](/docs/common/getting-started/shop-id)"
          example: "1234"
        orderNumber:
          type: string
          description: "Unique code identifying the specific order."
          example: "OREDER-324234"
        description:
          type: string
          nullable: true
          description: "Optional free text providing additional context or reason for the rejection."
          example: "Order rejected due to customer request."
    order.refundOrderRequest:
      type: object
      required:
        - shopId
        - orderNumber
      properties:
        shopId:
          type: integer
          description: "Unique identifier for the shop where the order is placed."
          example: 1234
        orderNumber:
          type: string
          description: "Unique identifier for the order to be refunded."
          example: "ORDER-324234"
        cost:
          type: object
          nullable: true
          description: "Optional refund cost details. Use this object to specify a partial refund amount and its currency if applicable."
          properties:
            amount:
              type: string
              description: |
                Represents the refund amount as a decimal string.

                For fiat currencies, follow ISO 4217 decimal precision standards for the specified currency.

                For cryptocurrencies, specify the amount according to the required precision of the token or coin.
              example: "56.99"
            currency:
              type: string
              description: |
                Specifies the currency.

                For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.

                For cryptocurrencies, a specific format is used; a full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies).
              example: "USD"
        paymentId:
          type: string
          description: "Optional identifier for the specific payment to be refunded. Provide this if the order includes multiple payments."
          example: "26243324234"
          nullable: true
        description:
          type: string
          maxLength: 128
          description: "Optional free text providing additional context or reason for the refund (up to 128 characters)."
          example: "Refund due to order cancellation."
          nullable: true
    V1RecurringResponseRecurringChargesRetrySettingsResponse:
      title: V1-Recurring-Response-RecurringChargesRetrySettingsResponse
      description: |
        Configuration settings that define how the system handles retry attempts for failed recurring charges.
      required:
        - settingsId
        - maxRetryCount
        - intervalType
        - intervals
        - createdAt
        - updatedAt
      properties:
        settingsId:
          description: |
            The unique identifier for this retry settings configuration.
          type: string
          example: "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
        shopId:
          description: |
            The unique identifier of the shop to which these retry settings apply.
          type: string
          nullable: true
          example: "12345"
        maxRetryCount:
          description: |
            The maximum number of retry attempts that will be made after an initial charge failure.
            For example, if set to 3, the system will make up to 3 additional attempts after the first failed charge.
          type: integer
          example: 3
        intervalType:
          $ref: "#/components/schemas/ProcessingEnumRecurringRecurringChargeAttemptIntervalType"
        intervals:
          description: |
            An array of numeric intervals defining the time delays between retry attempts, measured in units specified by `intervalType`.
            For example, if `intervalType` is "hour" and `intervals` is [1, 3, 6], retries will occur 1 hour, 3 hours, and 6 hours after the initial failure.
          type: array
          items:
            type: integer
          example: [1, 3, 6]
        createdAt:
          description: |
            The date and time when this retry settings configuration was created.
            Format: ISO 8601.
          type: string
          example: "2025-10-15T10:30:00Z"
        updatedAt:
          description: |
            The date and time when this retry settings configuration was last updated.
            Format: ISO 8601.
          type: string
          example: "2025-10-20T14:45:00Z"
        deletedAt:
          description: |
            The date and time when this retry settings configuration was deleted.
            This field is null if the configuration is currently active.
            Format: ISO 8601.
          type: string
          nullable: true
          example: null
      type: object
    V1RecurringResponseRecurringProfileResponse:
      title: V1-Recurring-Response-RecurringProfileResponse
      description: "Details of a recurring payment profile."
      required:
        - recurringUuid
        - orderNumber
        - customerId
        - status
        - cost
        - createdAt
        - schedule
        - recurringPayments
      properties:
        recurringUuid:
          description: |
            The unique identifier for this recurring payment profile.
          type: string
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        orderNumber:
          description: |
            The order number of the initial payment that created this recurring payment profile.
          type: string
          example: "ORD-2025-10001"
        customerId:
          description: |
            The unique identifier of the customer associated with this recurring payment.
          type: string
          example: "cust-67890"
        status:
          $ref: "#/components/schemas/ProcessingEnumRecurringRecurringStatus"
        cost:
          type: object
          description: |
            The recurring charge amount and currency.
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: |
                Represents the amount as a decimal string.

                For fiat currencies, follow ISO 4217 decimal precision standards for the specified currency.
              example: "56.99"
            currency:
              type: string
              description: |
                Specifies the currency.

                For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.
              example: "USD"
        createdAt:
          description: |
            The date and time when this recurring payment profile was created.
            Format: ISO 8601.
          type: string
          example: "2025-10-15T10:30:00Z"
        schedule:
          $ref: "#/components/schemas/V1RecurringResponseRecurringPaymentsSchedule"
        paymentsCompleted:
          description: |
            The number of successfully completed recurring charges.
            This count includes all charges that reached the `successful` status.
          type: integer
          nullable: true
          example: 5
        nextChargeDate:
          description: |
            The scheduled date and time for the next recurring charge.
            This field is null if the recurring payment is cancelled, completed, or failed.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2025-11-15T10:30:00Z"
        cancelledAt:
          description: |
            The date and time when this recurring payment was cancelled.
            This field is null if the recurring payment has not been cancelled.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2025-12-01T15:00:00Z"
        recurringPayments:
          description: |
            An array containing all charges associated with this recurring payment profile.
          type: array
          items:
            $ref: "#/components/schemas/V1RecurringResponseRecurringChargeResponse"
      type: object
    ProcessingEnumRecurringRecurringChargeAttemptIntervalType:
      title: " "
      description: |
        The time unit used to measure intervals between retry attempts for failed recurring charges.
      type: string
      enum:
        - second
        - minute
        - hour
        - day
      example: "hour"
    ProcessingEnumRecurringRecurringStatus:
      title: Apic-Contracts-Processing-Enum-Recurring-RecurringStatus
      description: |
        The current status of a recurring payment profile.

        Possible values:
          - awaiting_payment: Waiting for the initial payment to complete successfully
          - active: Recurring payment is active and charges are being processed according to schedule
          - completed: All scheduled charges have been completed successfully
          - failed: Recurring payment failed and cannot continue
          - canceled: Recurring payment was cancelled by the merchant or customer
      type: string
      enum:
        - awaiting_payment
        - active
        - completed
        - failed
        - canceled
      example: "active"
    V1RecurringResponseRecurringPaymentsSchedule:
      title: V1-Recurring-Response-RecurringPaymentsSchedule
      description: |
        The schedule configuration for recurring payments, defining when and how often charges occur.
      required:
        - intervalType
        - billingIntervalQuantity
      properties:
        intervalType:
          $ref: "#/components/schemas/ProcessingEnumRecurringRecurringIntervalType"
        billingIntervalQuantity:
          description: |
            The number of intervals between each recurring charge.
            For example, if `intervalType` is "month" and `billingIntervalQuantity` is 1, charges occur monthly.
            If `billingIntervalQuantity` is 3, charges occur every 3 months.
          type: integer
          example: 1
        endDate:
          description: |
            The date and time when the recurring payment schedule will end.
            After this date, no further charges will be scheduled or processed.
            This field is null if the recurring payment has no defined end date.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2026-10-15T10:30:00Z"
        paymentCount:
          description: |
            The total number of payments to be made before the recurring payment ends.
            For example, if set to 12, the subscription will end after 12 successful charges.
            This field is null if there is no limit on the number of payments.
          type: integer
          nullable: true
          example: 12
      type: object
    V1RecurringResponseRecurringChargeResponse:
      title: V1-Recurring-Response-RecurringChargeResponse
      description: |
        Details of an individual recurring charge, including its status and all retry attempts.
      required:
        - recurringChargeUuid
        - recurringChargeStatus
        - createdAt
        - tries
      properties:
        recurringChargeUuid:
          description: |
            The unique identifier for this recurring charge.
          type: string
          example: "b3e4c5d6-f7a8-49b0-c1d2-e3f4a5b6c7d8"
        recurringChargeStatus:
          $ref: "#/components/schemas/ProcessingEnumRecurringRecurringChargeStatus"
        paymentId:
          description: |
            The unique identifier of the payment associated with this charge.
            This field is null if the charge has not yet been successfully processed.

            This field is automatically populated when the charge status transitions to 'successful' (either from the initial attempt or from a successful retry).
          type: string
          nullable: true
          example: "pay-123456789"
        chargeDate:
          description: |
            The scheduled date and time when this charge should be processed.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2025-11-15T10:30:00Z"
        endDate:
          description: |
            The date and time when the validity period of this charge ends.
            This typically marks the end of the billing period covered by this charge.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2025-12-15T10:30:00Z"
        failedAt:
          description: |
            The date and time when this charge permanently failed after exhausting all retry attempts.
            This field is null if the charge has not failed.
            Format: ISO 8601.
          type: string
          nullable: true
          example: null
        createdAt:
          description: |
            The date and time when this charge was created.
            Format: ISO 8601.
          type: string
          example: "2025-10-15T10:30:00Z"
        tries:
          description: |
            An array of all retry attempts made for this charge, ordered chronologically.
            If the initial charge succeeds, this array may be empty.
          type: array
          items:
            $ref: "#/components/schemas/V1RecurringResponseRecurringChargeAttemptResponse"
      type: object
    ProcessingEnumRecurringRecurringIntervalType:
      title: " "
      description: |
        The time unit used to define the billing cycle for recurring payments.

        Possible values:
          - day: Charges occur daily or every N days
          - week: Charges occur weekly or every N weeks
          - month: Charges occur monthly or every N months
          - year: Charges occur yearly or every N years
      type: string
      enum:
        - day
        - week
        - month
        - year
      example: "month"
    V1RecurringResponseRecurringChargeAttemptResponse:
      title: V1-Recurring-Response-RecurringChargeAttemptResponse
      description: |
        Details of a single retry attempt for a recurring charge.
      required:
        - recurringChargeAttemptUuid
        - recurringChargeAttemptStatus
        - createdAt
      properties:
        recurringChargeAttemptUuid:
          description: |
            The unique identifier for this retry attempt.
          type: string
          example: "d4e5f6a7-b8c9-40d1-e2f3-a4b5c6d7e8f9"
        recurringChargeAttemptStatus:
          $ref: "#/components/schemas/ProcessingEnumRecurringRecurringRetryStatus"
        paymentId:
          description: |
            The unique identifier of the payment associated with this attempt.
            This field is null if the attempt has not resulted in a successful payment.

            When this retry attempt succeeds (status becomes 'successful'), this field is populated and the parent charge's payment_id is also updated.
          type: string
          nullable: true
          example: "pay-987654321"
        chargeDate:
          description: |
            The date and time when this retry attempt was executed.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2025-11-15T14:30:00Z"
        failedAt:
          description: |
            The date and time when this retry attempt failed.
            This field is null if the attempt is still in progress or succeeded.
            Format: ISO 8601.
          type: string
          nullable: true
          example: "2025-11-15T14:30:15Z"
        failedReason:
          description: |
            A description of why this retry attempt failed, typically provided by the payment provider.
            This field is null if the attempt succeeded or is still in progress.
          type: string
          nullable: true
          example: "Insufficient funds"
        createdAt:
          description: |
            The date and time when this retry attempt was created and scheduled.
            Format: ISO 8601.
          type: string
          example: "2025-11-15T14:00:00Z"
      type: object
    ProcessingEnumRecurringRecurringChargeStatus:
      title: " "
      description: |
        The current status of an individual recurring charge.

        Possible values:
          - scheduled: The charge is scheduled and waiting to be processed
          - in_progress: The charge is currently being processed
          - successful: The charge was completed successfully and payment_id has been assigned
          - canceled: The charge was cancelled (can be cancelled from scheduled or retry_pending status)
          - retry_pending: The charge failed and a retry attempt is scheduled
          - retry_exhausted: All retry attempts have been exhausted and the charge has permanently failed
      type: string
      enum:
        - scheduled
        - in_progress
        - successful
        - canceled
        - retry_pending
        - retry_exhausted
      example: "successful"
    ProcessingEnumRecurringRecurringRetryStatus:
      title: " "
      description: |
        The current status of a retry attempt for a recurring charge.

        Possible values:
          - scheduled: The retry attempt is scheduled and waiting to be executed
          - in_progress: The retry attempt is currently being processed
          - successful: The retry attempt succeeded, the charge was completed, and the parent charge status is updated to 'successful' with payment_id assigned
          - canceled: The retry attempt was cancelled (when the recurring payment is cancelled)
          - failed: The retry attempt failed and was unsuccessful. If retry limit is not reached, a new retry attempt will be created automatically
      type: string
      enum:
        - scheduled
        - in_progress
        - successful
        - canceled
        - failed
      example: "successful"
    ProcessingEnumOrderReviewResultStatus:
      title: " "
      description: |
        The merchant's decision for an order that requires manual antifraud review.

        Possible values:
          - accept: Approve the transaction and resume processing. The order will continue through the normal payment flow.
          - decline: Reject the transaction. The order will be declined and no further processing will occur.
      type: string
      enum:
        - accept
        - decline
      example: "accept"
    V1RecurringRequestCreateRecurringChargesRetrySettingsRequest:
      title: V1-Recurring-Request-CreateRecurringChargesRetrySettingsRequest
      description: |
        Request payload for creating retry settings configuration for a shop's recurring charges.
      required:
        - shopId
        - maxRetryCount
        - intervalType
        - intervals
      properties:
        shopId:
          description: |
            The unique identifier of the shop for which to create retry settings.
          type: string
          example: "12345"
        maxRetryCount:
          description: |
            The maximum number of retry attempts that will be made after an initial charge failure.
            Must be greater than 0.
          type: integer
          minimum: 0
          exclusiveMinimum: true
          example: 3
        intervalType:
          description: |
            The time unit used to measure intervals between retry attempts.

          type: string
          enum:
            - second
            - minute
            - hour
            - day
          example: "hour"
        intervals:
          description: |
            An array of numeric intervals defining the time delays between retry attempts, measured in units specified by `intervalType`.
            The array length should equal `maxRetryCount`.
            For example, if `maxRetryCount` is 4 and `intervalType` is "hour", and `intervals` is [1, 2, 4], retries will occur 1 hour, 2 hours, and 4 hours after the previous attempt.
          type: array
          items:
            type: integer
          example: [1, 3, 6]
      type: object
    V1RecurringRequestUpdateRecurringChargesRetrySettingsRequest:
      title: V1-Recurring-Request-UpdateRecurringChargesRetrySettingsRequest
      description: |
        Request payload for updating existing retry settings configuration for recurring charges.
      required:
        - maxRetryCount
        - intervalType
        - intervals
      properties:
        maxRetryCount:
          description: |
            The maximum number of retry attempts that will be made after an initial charge failure.
            Must be greater than 0.
          type: integer
          minimum: 0
          exclusiveMinimum: true
          example: 3
        intervalType:
          description: |
            The time unit used to measure intervals between retry attempts.

          type: string
          enum:
            - second
            - minute
            - hour
            - day
          example: "hour"
        intervals:
          description: |
            An array of numeric intervals defining the time delays between retry attempts, measured in units specified by `intervalType`.
            The array length must match or exceed `maxRetryCount`.
            For example, if `intervalType` is "hour" and `intervals` is [1, 3, 6], retries will occur 1 hour, 3 hours, and 6 hours after the initial failure.
          type: array
          items:
            type: integer
          example: [1, 3, 6]
      type: object
    order.captureOrderRequest:
      required:
        - orderNumber
        - shopId
      type: object
      properties:
        shopId:
          type: integer
          description: "ID of the shop where the order is placed. [How to get your shopId](/docs/common/getting-started/shop-id)"
          example: "1234"
        orderNumber:
          type: string
          description: "Unique code identifying the specific order."
          example: "OREDER-324234"
        paymentId:
          type: string
          description: "Optional identifier for the specific payment to be captured. Provide this if the order includes multiple payments."
          example: "26243324234"
          nullable: true
        cost:
          type: object
          nullable: true
          required:
            - amount
            - currency
          description: "Optional cost details. Use this object to specify a partial capture amount and its currency if applicable."
          properties:
            amount:
              type: string
              description: |
                Represents the capture amount as a decimal string.

                For fiat currencies, follow ISO 4217 decimal precision standards for the specified currency.

              example: "56.99"
            currency:
              type: string
              description: |
                Specifies the currency.

                For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.
              example: "USD"
    order.reviewResultRequest:
      type: object
      required:
        - shopId
        - orderNumber
        - result
      properties:
        shopId:
          type: integer
          description: "Unique identifier for the shop where the order or payout requiring review is placed. [How to get your shopId](/docs/common/getting-started/shop-id)"
          example: 1234
        orderNumber:
          type: string
          description: "Unique identifier for the order or payout that requires manual antifraud review."
          example: "ORDER-324234"
        result:
          $ref: "#/components/schemas/ProcessingEnumOrderReviewResultStatus"
    order.refundOperationResponse:
      required:
        - operationType
        - orderNumber
      type: object
      properties:
        orderNumber:
          type: string
          description: "Unique code identifying the specific order."
          example: "OREDER-324234"
        operationType:
          type: string
          description: "Operations type"
          example: "refund"
          enum:
            - refund
    order.rejectOperationResponse:
      required:
        - operationType
        - orderNumber
      type: object
      properties:
        orderNumber:
          type: string
          description: "Unique code identifying the specific order."
          example: "OREDER-324234"
        operationType:
          type: string
          description: "Operations type"
          example: "reject"
          enum:
            - reject
    order.status:
      type: object
      required:
        - shopId
        - id
        - orderNumber
        - orderStatus
        - cost
        - timeLimit
        - orderCreatedAt
        - autoCapture
        - payments
      properties:
        id:
          type: integer
          description: "The internal unique identifier of the order within the system. Used for referencing the order when contacting technical support in case of any issues."
          example: 54222
        shopId:
          type: integer
          description: "The unique identifier of the shop initiating the order."
          example: 123
        orderNumber:
          type: string
          description: "A unique identifier for the order, generated by the merchant, and specific to each `shopId`."
          example: "56573FDFVFDBWF"
        orderStatus:
          type: string
          description: "Status of the order. [Description of Statuses](/docs/merchant/orders/order-life-cycle#orderpayment-actions-and-conditions)"
          example: "in_progress"
          enum:
            - registered
            - in_progress
            - failed
            - completed
            - cancelled
            - refunded
            - partially_refunded
            - need_action
            - review
        cost:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: |
                Total cost of the order, formatted as a decimal string with a period (.) as the decimal separator.

                Please note that the final amount may differ from the original value specified during [order creation](/docs/merchant-api/create-order), as some providers allow customers to modify the payment amount or may adjust the order amount slightly themselves. This field always reflects the most up-to-date order amount."
              example: "56.99"
            currency:
              type: string
              description: "Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
              example: "USD"
          description: "Container for cost-related information."
        recurringPayments:
          type: object
          nullable: true
          description: |
            If this order triggered a recurring subscription, this object contains basic subscription details.

            For complete subscription information including payment history, retry attempts, and full schedule details, 
            use the [Retrieve Recurring Payment Profile](/docs/merchant-api/get-app-external-v-1-recurring-recurringpayments-getrecurring) endpoint with the `recurringId` from this object.

            Each automatic charge (for the recurring subscription) is added to the payments array in this endpoint or via the callback. It's possible for each payment object to have a status of completed while the overall order remains in_progress if there are future charges still pending.
          properties:
            recurringId:
              type: string
              description: "A unique identifier for the recurring subscription."
              example: "sub_54222"
            status:
              type: string
              enum: [active, canceled, failed, completed]
              description: |
                The current status of this recurring subscription:

                - **active**: The subscription is currently active and recurring charges can occur.

                - **canceled**: The subscription has been canceled; no further charges will be made.

                - **failed**: The subscription encountered an issue.

                - **completed**: The subscription has concluded because it reached its defined end (all payments completed or the end date was reached).
              example: "active"
        timeLimit:
          type: string
          description: |
            Specifies the expiration time for the payment page in RFC 3339 format, including the UTC zone. This field determines how long the payment page remains active for the payer to initiate a payment.
          example: "2023-08-29T15:34:56+03:00"
        reviewTimeout:
          type: integer
          nullable: true
          minimum: 1
          maximum: 1440
          description: |
            Time limit for submitting a decision on orders that require manual antifraud review in minutes. Valid range: 1 to 1440 minutes (24 hours).

            This field is only present when `orderStatus` is `review`. If no decision is submitted within this timeout period using the [Submit Antifraud Review Decision](/docs/merchant-api/submit-antifraud-review-decision) endpoint, the transaction will be automatically declined.
            For more information about the review process, see [Antifraud Manual Review](/docs/merchant/antifraud-review).
          example: 120
        orderCreatedAt:
          type: string
          description: "Date and time the order was created, in RFC 3339 format including the UTC zone."
          example: "2023-08-29T15:34:56+03:00"
        orderPaidAt:
          type: string
          description: "Date and time the order was paid, in RFC 3339 format including the UTC zone."
          example: "2023-08-29T15:34:56+03:00"
          nullable: true
        autoCapture:
          type: boolean
          description: "`true` for one-stage payments where funds are automatically captured. `false` for two-stage payments requiring manual capture. [How to work with two-stage payments](/docs/merchant/orders/scenarios/two-stage-payments)"
        payments:
          type: array
          description: |
            An array of payment objects related to the order. If the array is empty, it indicates that no payments have been made for the order yet. 

            If an order is paid with multiple payments, there will be one object per payment in the array.

            If a refund has been issued for a payment, the array will include an object with `paymentType` set to `refund`

            `order_by_webhook` - used when the merchant is notified about the completion of a crypto payment, as the payment status is updated based on the callback received from the payment provider's webhook.
          items:
            $ref: "#/components/schemas/payment"
        customer:
          allOf:
            - $ref: "#/components/schemas/customerResponse"
          nullable: true
        statusReason:
          type: string
          nullable: true
          example: "The order amount is not equal to the amount of payments"
          description: |
            A short explanation of why the order is in its current status (e.g., `need_action`, `failed`, or `cancelled`).

            This field may contain system-generated messages or error details from the payment provider.

            For example, if the total of completed payments does not match the order amount, the system sets the status to `need_action` and provides the message: "The order amount is not equal to the amount of payments."

            This field will remain empty for statuses such as `completed` or `in_progress`.
        description:
          type: string
          maxLength: 128
          description: "Optional text providing additional context for the order."
          example: "Internal reference #123"
    payment:
      type: object
      required:
        - paymentId
        - paymentType
        - cost
        - acquirer
        - provider
        - instrumentType
        - paymentStatus
      properties:
        paymentId:
          type: string
          description: "Identifier for the specific payment assigned by our system."
          example: "79"
        paymentType:
          type: string
          description: |
            Indicates the type of operation for this payment record. Possible values:

            - **payment**: Represents a standard payment transaction initiated by the merchant.
            - **refund**: Indicates a refund operation, where funds are returned to the customer for a previous payment.
            - **registered**: A service status used only in webhooks; does not signify a financial transaction but marks the registration of a payment attempt.
            - **order_by_webhook**: Used when the merchant is notified about the completion of a crypto payment; the payment status is updated based on the callback received from the payment provider's webhook.
            - **cancel**: Denotes a payment that was cancelled.
            - **capture**: Indicates the capture of previously authorized funds in a two-stage (authorization/capture) payment process. When a capture request is received, the system checks if the integration supports capture operations. If supported, the system locates all transactions in the order with status "authorized" and creates a child operation of type "capture" for each. The system then sends capture requests to the processor. If all captures succeed, the status of the corresponding payments and the order is updated to "completed". If at least one capture fails, the order status is set to "need_action" and the status reason is updated to reflect the capture error. If the provider does not support capture, an error is returned. The order remains in status "in_progress" until all related transactions are completed.
            - **pre_auth**: Represents a pre-authorization, where funds are reserved but not yet captured.
            - **incremental_capture**: Used for capturing additional funds beyond the original authorization in a two-stage payment process.
            - **provider_status_update**: Reflects a status update received from the payment provider, which may not correspond to a direct payment or refund action.
            - **3ds_verification**: Indicates a 3-D Secure verification step, typically for card payments requiring additional authentication.
            - **incremental_pre_auth**: Used for increasing the amount of a pre-authorization before final capture.
            - **decremental_capture**: Indicates a partial capture of funds, less than the originally authorized amount. This operation is recorded when a capture request is made for a reduced sum. The system will update the payment and order balances accordingly, and the original payment will be marked as overwritten.
            - **partial_cancel**: Indicates a partial cancellation of the authorized amount before capture. This operation is used as part of the process to reduce the authorized amount prior to capturing a smaller sum. If the provider does not support partial cancellation, the system will return an error.
            - **saved_card_payment**: Indicates a payment made using a saved card.
          example: "payment"
          enum:
            - payment
            - refund
            - registered
            - order_by_webhook
            - cancel
            - confirmation
            - capture
            - pre_auth
            - incremental_capture
            - provider_status_update
            - 3ds_verification
            - reject
            - incremental_pre_auth
            - decremental_capture
            - partial_cancel
            - saved_card_payment
        parentPayment:
          type: string
          description: "Used only for refunds: refers to the original `paymentId` that was refunded. This field is not needed for `paymentType` == `payment`."
          example: "83"
        cost:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "The amount of the transaction. For refunds (`paymentType` == `refund`), this will be the refund amount. Formatted as a decimal string with a period (.) as the decimal separator."
              example: "56.99"
            currency:
              type: string
              description: "Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
              example: "USD"
          description: "Financial details of the payment or refund."
        acquirer:
          type: object
          properties:
            code:
              type: string
              description: "Acquirer code."
              example: "fyst"
          description: "Information about the acquirer for this payment."
        provider:
          type: object
          properties:
            code:
              type: string
              description: "Provider code."
              example: "fyst"
          description: "Information about the provider for this payment."
        instrumentType:
          type: string
          description: "Specifies the payment instrument. [See available payment instruments](/docs/merchant/instrument-type)"
          example: "card"
          enum:
            - card
            - bank_transfer
            - wallet
            - crypto_wallet
            - voucher
            - cash
        paymentStatus:
          description: "Contains the status of the payment, including detailed information in case of payment failure."
          required:
            - status
          properties:
            status:
              type: string
              description: "The current state of the payment. [Description of Statuses](/docs/merchant/orders/order-life-cycle#orderpayment-actions-and-conditions)"
              example: failed
              enum:
                - in_progress
                - completed
                - cancelled
                - failed
                - authorized
                - need_action
                - overwrite
                - review
            details:
              nullable: true
              description: "Provides additional error details if the payment fails."
              properties:
                errorId:
                  description: "A unique identifier for the error generated by the system, used for tracking and troubleshooting."
                  type: string
                  example: "61740c87-b60d-4578-bf25-575a8c68532e"
                  nullable: true
                providerMessage:
                  description: "An error message provided by the payment provider, offering insight into the reason for the failure."
                  example: "Payment method not found"
                  type: string
                  nullable: true
                code:
                  description: "An internal error code used by the system to categorize the type of error that occurred."
                  example: 401
                  type: integer
                  nullable: true
              type: object
          type: object
        paymentDetails:
          type: object
          description: "Describes the details of the payment, which vary according to the `instrumentType` selected."
          nullable: true
          oneOf:
            - $ref: "#/components/schemas/CardPaymentDetails"
            - $ref: "#/components/schemas/BankTransferPaymentDetails"
            - $ref: "#/components/schemas/WalletPaymentDetails"
            - $ref: "#/components/schemas/OrderPaymentDetailsCryptoWalletResponse"
            - $ref: "#/components/schemas/OrderPaymentDetailsVoucherResponse"
            - $ref: "#/components/schemas/OrderPaymentDetailsCashResponse"
        providerPaymentId:
          description: "Identifier for the specific transaction assigned by the payment provider."
          type: string
          nullable: true
          example: "990943"
        transactionId:
          description: "Identifier for the specific transaction assigned by our system"
          type: string
          nullable: true
          example: "172666307000000001"
        providerPaymentName:
          type: string
          nullable: true
          description: |
            The name of the final payment provider that processed the transaction.
          example: "someName"
        antifraud:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/V1OrderResponseAntifraudResultResponse"
        chargebacks:
          description: "Chargeback details if payment was charged back."
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/V1OrdersResponseOrderPaymentChargebackDetailsResponse"
        description:
          type: string
          nullable: true
          description: "Description of the payment."
          example: "Payment for invoice #12345"
        entryMode:
          nullable: true
          description: "Indicates the mode in which the payment was made."
          type: string
          enum:
            - apple_pay
            - cnp
            - card_present
            - google_pay
            - samsung_pay
            - moto
            - recurring
            - saved_card
        parentId:
          type: string
          nullable: true
          description: "The ID of the parent payment if this payment is a child of another payment."
          example: "1234567890"
        payer:
          description: |
            Information about the payer collected during the payment attempt.

            This object is particularly useful for antifraud review processes, allowing merchants to make informed decisions based on comprehensive payer information.
          nullable: true
          $ref: "#/components/schemas/V1OrdersResponsePersonDataResponse"
        operationReference:
          description: |
            Contains operation reference parameters received from the payment provider for instruction-based payment methods.

            This object provides label-value pairs with transaction details that may include reference codes, amounts, entity identifiers, account numbers, or other provider-specific information needed for transaction completion or reconciliation.

            For orders, this field is typically used in shop-hosted integrations where payment instructions are delivered directly via API. See [H2H Integration for Instructions](/docs/merchant/orders/shop-hosted) for implementation details.
          default: null
          nullable: true
          allOf:
            - $ref: "#/components/schemas/V1OrderResponseOrderPaymentOperationReference"
    CardPaymentDetails:
      type: object
      title: "instrumentType=card"
      properties:
        paymentSystem:
          type: string
          nullable: true
          description: |
            Brand of the card used in the transaction.

            visa - "Visa"

            mastercard - "MasterCard"

            jcb - "JCB"

            amex - "American Express"

            dci - "Diners Club International"

            unionpay - "UnionPay"

            upi - "UnionPay International"

            mir - "Mir"

            discover - "Discover"

            redcompra - "Redcompra"

            elo - "Elo"

            hipercard - "Hipercard"

            maestro - "Maestro"

            verve - "Verve"
          enum:
            - visa
            - mastercard
            - jcb
            - amex
            - dсi
            - unionpay
            - upi
            - mir
            - discover
            - redcompra
            - elo
            - hipercard
            - maestro
            - verve
        authCode:
          type: string
          nullable: true
          description: "Authorization code for the payment"
          example: "auth94753457343"
        rrn:
          type: string
          nullable: true
          description: "Retrieval Reference Number for the payment."
          example: "rrn583743856734"
        maskedCardNumber:
          type: string
          nullable: true
          description: |
            This field displays a partially obscured version of the card number to maintain security and privacy.
            Depending on the provider, the masked card number might show:

              - **The first 6 and last 4 digits**, with the intervening digits replaced by asterisks (e.g., 123456******1234)
              - **Only the last 4 digits** (e.g., **** **** **** 1234)
          example: "123456******1234"
        savedCardId:
          type: string
          nullable: true
          description: |
            The unique identifier of the saved card used in this transaction. This field is returned when:
            - A payment was made using a previously saved card (`entryMode` was `saved_card`)
            - A new card was saved during the payment (`customer.saveCard` was `true`)

            This identifier can be used for future payments with the same card.
          example: "550e8400-e29b-41d4-a716-446655440000"
    BankTransferPaymentDetails:
      type: object
      title: "instrumentType=bank_transfer"
      properties:
        transferType:
          type: string
          nullable: true
          description: "Specifies the type of bank transfer used. See details about [transferType](/docs/merchant/instrument-type)"
          enum:
            - swift
            - sepa
            - bank_wire
            - card2card
            - pix
            - sbp
            - online_banking
            - open_finance
            - virtual_account
            - qris
            - promptpay
            - thaiqr
            - spei
            - vietnambanksqr
            - vietqr
            - khipu
            - paysafecard
            - multibanco
            - bancontact
            - blik
            - p24
            - rapidtransfer
            - thb_qr
            - upi
            - upi_intent
            - sberbank
            - giropay
            - eps
            - account2card
            - fpx
            - trustly
            - wise
            - n26
            - pesalink
            - imps
            - upi_p2p
            - upi_fast_vip
            - mybank
            - tink
            - bizum
            - sofort
            - p2p
            - easypay
            - klarna
            - clabe
            - codi
            - rapipago
            - pse
          example: "swift"
        purpose:
          type: string
          nullable: true
          description: "Describes the purpose of the transfer, providing details on the reason or the underlying transaction for the bank transfer."
          example: "Payment for invoice #12345"
        accountNumber:
          type: string
          nullable: true
          description: "The account number used in the transaction."
          example: "5103984571309587"
    WalletPaymentDetails:
      type: object
      title: "instrumentType=wallet"
      properties:
        walletId:
          type: string
          nullable: true
          description: "The identifier for the wallet used in the transaction."
          example: "aslk1351346"
    OrderPaymentDetailsCryptoWalletResponse:
      title: "instrumentType=crypto_wallet"
      description: "Payment details for crypto wallet payment."
      type: object
      required:
        - blockchain
        - tokenStandard
      properties:
        blockchain:
          type: string
          description: >
            The name of the blockchain on which this crypto transfer occurs.
            For example, if you're using TRON, set this to 'Tron'.
          example: "Tron"
        tokenStandard:
          type: string
          description: >
            The specific token standard for this crypto transfer.
            For instance, 'TRC20' indicates a TRON-based token.
          example: "TRC20"
        senderCryptoAddress:
          type: string
          nullable: true
          description: >
            The cryptocurrency wallet address of the sender.
          example: "0xAbC1234567890abcdef1234567890abcdef1234"
        senderCryptoAddressMeta:
          type: object
          nullable: true
          description: "Additional metadata for the sender address."
          example:
            destinationTag: "123456789"
        recipientCryptoAddress:
          type: string
          nullable: true
          description: "The cryptocurrency wallet address of the recipient."
          example: "0xDef4567890abcdef1234567890abcdef12345678"
        recipientCryptoAddressMeta:
          type: object
          nullable: true
          description: "Additional metadata for the recipient address."
          example:
            destinationTag: "987654321"
        txHash:
          type: string
          nullable: true
          description: >
            The unique transaction hash for this crypto payment. Typically provided
            by the blockchain after a transfer is initiated.
          example: "0x123abc456def7890abc123def456ghi789jkl012"
        tronscanUrl:
          type: string
          nullable: true
          description: >
            A direct URL to view transaction details on TronScan.
            This is relevant only if blockchain is set to "Tron".
          example: "https://tronscan.org/#/transaction/0x123abc456def7890abc123def456ghi789jkl012"
        amlRisk:
          type: string
          enum: [Low, Medium, High, Severe]
          nullable: true
          description: >
            Indicates the Anti-Money Laundering (AML) risk level associated with
            this transaction.
          example: "Low"
    OrderPaymentDetailsVoucherResponse:
      description: "Payment details for voucher payment."
      title: "instrumentType=voucher"
      type: object
      properties:
        serialNumber:
          type: string
          example: "SN123456789"
          description: "A serial number identifying the voucher."
          nullable: true
        pin:
          type: string
          example: "123456789012"
          description: "A  PIN code needed to redeem or validate the voucher."
          nullable: true
    OrderPaymentDetailsCashResponse:
      description: "Payment details for cash payment."
      title: "instrumentType=cash"
      type: object
      properties:
        reference:
          type: string
          description: "Reference number for the cash payment."
          example: "123456789012"
          nullable: true
    customer:
      type: object
      properties:
        customerId:
          type: string
          nullable: true
          maxLength: 255
          description: "A unique identifier for the customer. The `customerId` can either be unique within a shop or across the entire company/merchant. To determine the  setting for your shop, check the admin panel of your merchant account under the settings menu in the field 'External customer ID unique for'."
          example: "56656"
        firstName:
          type: string
          maxLength: 255
          nullable: true
          description: "First name of the customer."
          example: "John"
        lastName:
          type: string
          maxLength: 255
          nullable: true
          description: "Last name of the customer."
          example: "Doe"
        middleName:
          type: string
          nullable: true
          maxLength: 255
          description: "Middle name of the customer, if applicable."
          example: "James"
        phone:
          type: string
          nullable: true
          description: "Customer's phone number, in international format."
          example: "79221110500"
        email:
          type: string
          nullable: true
          maxLength: 255
          description: "Email address of the customer."
          format: email
          example: "john.doe@mymail.com"

        birthDate:
          description: "Customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          type: string
          example: 1990-12-30
          nullable: true
        details:
          type: object
          description: Customer details
          nullable: true
          properties:
            addressData:
              type: object
              description: Customer address data
              nullable: true
              properties:
                city:
                  description: City name
                  maxLength: 255
                  type: string
                  example: Beverly Hills
                  nullable: true
                countryCode:
                  description: ISO 3166-1 alpha-2 country code
                  type: string
                  maxLength: 2
                  minLength: 2
                  example: US
                state:
                  description: State or province name
                  type: string
                  maxLength: 255
                  example: California
                  nullable: true
                zipCode:
                  description: Postal code
                  maxLength: 10
                  type: string
                  example: "90210"
                  nullable: true
                address:
                  description: "Full street address of the customer"
                  type: string
                  nullable: true
                  example: 42, Sunset Blvd.
        metaData:
          type: object
          description: Customer metadata
          nullable: true
          properties:
            affiliatedId:
              maxLength: 255
              type: string
              nullable: true
              description: |
                An optional identifier provided by the merchant to facilitate custom payment routing. 
                This field allows you to pass any arbitrary value, which will be stored in the customer's record.
              example: "afl_4848301"
        saveCard:
          description: |
            Indicates whether to save the customer's card details for future payments. When set to `true`, the card will be stored after a successful payment and can be used for subsequent one-click payments.

            **Important:** If `saveCard` is set to `true`, the `customerId` field must be provided to link the card to the customer.
          type: boolean
          nullable: true
          example: true
      description: |
        Container for customer-specific information. You can configure the order to automatically use the customer's details (firstName, lastName, middleName, phone, email, birthDate, and details -> addressData) as the payer's information, sparing the customer from re-entering these details on the payment page. Note that this feature only applies to providers that require this data; if the provider does not need these details, the payment page will remain unchanged.

        This behavior is governed by the setting **"Use customer data as payer information,"** which applies across the entire merchant company. Merchants can view this setting in their Dashboard under **Settings** (left menu) -> **Company** tab -> **"Use customer data as payer information."**

        **Important limitations:**
        - When both `customer` and `payer` objects are provided, **`payer` fields take priority** over `customer` fields

        To modify this setting, please contact technical support.

        For more details, you can visit the [Optimize the Payment Page Experience](/docs/merchant/orders/payment-page-options/optimize-the-payment-page) page.

        **Cryptocurrency Payments (`instrumentType: crypto_wallet`):**
        Customer identification is required for cryptocurrency payments. You must provide at least one of the following fields:
        - `customerId` - to use an existing customer
        - `email` - to identify or create customer by email
        - `phone` - to identify or create customer by phone

        If none of these fields are provided, the API returns error 422: "Please resend the request including either an existing customerId or the customer's phone or email"
    V1OrderResponseAntifraudResultResponse:
      description: |
        Antifraud verification result.
        If the order is not processed through an antifraud system, this field will be empty.
      required:
        - antifraudResultStatus
      properties:
        antifraudResultStatus:
          description: Antifraud result status.
          type: string
          enum:
            - block
          example: block
      type: object
    V1OrdersResponseOrderPaymentChargebackDetailsResponse:
      title: V1-Orders-Response-OrderPaymentChargebackDetailsResponse
      description: Chargeback details if exists.
      required:
        - cost
        - createdAt
        - status
        - chargebackId
      properties:
        cost:
          description: |
            Contains the financial details of the chargeback, including the disputed amount and its currency.
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "Amount of the chargeback."
              example: "100.00"
            currency:
              type: string
              description: "Currency of the chargeback."
              example: "USD"
        createdAt:
          description: |
            The date and time when the chargeback dispute was initiated.
            Format: ISO 8601.
          type: string
        updatedAt:
          description: |
            The date and time when the chargeback dispute was last updated or resolved.
            This field is null if the dispute has not been updated since creation.
            Format: ISO 8601.
          type: string
          nullable: true
        status:
          type: string
          enum:
            - open
            - open_undefined
            - approved
            - closed
          description: |
            The current status of the chargeback dispute.
            Possible values:
              - open: The dispute is open and under review.
              - open_undefined: The dispute is open, but some transaction details could not be determined.
              - approved: The dispute was resolved in favor of the customer.
              - closed: The dispute was resolved in favor of the merchant.
          example: "open"
        chargebackId:
          description: |
            A unique identifier for the chargeback record within the system.
            This value is used to track and reference the specific chargeback.
          type: string
          example: "CB001"
      type: object
    V1OrderResponseOrderPaymentChargebackDetailsResponse:
      title: V1-Order-Response-OrderPaymentChargebackDetailsResponse
      description: Chargeback details if exists.
      required:
        - cost
        - createdAt
        - providerReasonCode
        - providerReason
        - providerFunctionCode
        - providerDescription
        - status
        - chargebackId
      properties:
        cost:
          description: |
            Contains the financial details of the chargeback, including the disputed amount and its currency.
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "Amount of the chargeback."
              example: "100.00"
            currency:
              type: string
              description: "Currency of the chargeback."
              example: "USD"
        createdAt:
          description: |
            The date and time when the chargeback dispute was initiated.
            Format: ISO 8601.
          type: string
        updatedAt:
          description: |
            The date and time when the chargeback dispute was last updated or resolved.
            This field is null if the dispute has not been updated since creation.
            Format: ISO 8601.
          type: string
          nullable: true
        providerReasonCode:
          description: |
            The code provided by the payment provider indicating the reason for the chargeback.
            This code helps categorize the dispute according to provider-specific rules.
          type: integer
        providerReason:
          type: string
          description: |
            A human-readable description of the reason for the chargeback, as provided by the payment provider.
            This field gives additional context for the dispute.
          example: "Duplicate processing"
        providerFunctionCode:
          type: integer
          description: |
            The code representing the type or stage of the chargeback process, as defined by the payment provider.
            This code helps identify the current phase of the dispute.
          example: 200
        providerDescription:
          type: string
          description: |
            A description of the chargeback type or stage, as provided by the payment provider.
            This field clarifies the current status or action taken in the chargeback process.
          example: "First presentment"
        status:
          type: string
          enum:
            - open
            - open_undefined
            - approved
            - closed
          description: |
            The current status of the chargeback dispute.
            Possible values:
              - open: The dispute is open and under review.
              - open_undefined: The dispute is open, but some transaction details could not be determined.
              - approved: The dispute was resolved in favor of the customer.
              - closed: The dispute was resolved in favor of the merchant.
          example: "open"
        chargebackId:
          description: |
            A unique identifier for the chargeback record within the system.
            This value is used to track and reference the specific chargeback.
          type: string
          example: "CB001"
        comment:
          description: |
            An optional comment or note related to the chargeback.
            This field may contain additional information or remarks added by the system or operator.
          type: string
          nullable: true
          example: "Customer provided additional documentation."
      type: object
    V1OrdersResponsePersonDataResponse:
      title: V1-Orders-Response-PersonDataResponse
      description: |
        Person data collected during the payment or payout attempt.
      properties:
        personalData:
          description: Personal information of the payer or recipient.
          nullable: true
          $ref: "#/components/schemas/V1OrdersResponsePersonalDataResponse"
        addressData:
          description: Address data of the payer or recipient.
          nullable: true
          $ref: "#/components/schemas/V1OrdersResponsePersonAddressDataResponse"
        documentData:
          description: Document data of the payer or recipient.
          nullable: true
          $ref: "#/components/schemas/V1OrdersResponsePersonDocumentDataResponse"
      type: object
    V1OrdersResponsePersonalDataResponse:
      title: V1-Orders-Response-PersonalDataResponse
      description: Personal information data collected from the payer or recipient during the payment or payout process.
      required:
        - birthDate
      properties:
        id:
          description: Person identifier.
          type: string
          example: "ext-12345"
          nullable: true
        firstName:
          description: First name of the payer or recipient.
          type: string
          example: "John"
          nullable: true
        lastName:
          description: Last name of the payer or recipient.
          type: string
          example: "Doe"
          nullable: true
        middleName:
          description: Middle name of the payer or recipient, if applicable.
          type: string
          example: "Michael"
          nullable: true
        phone:
          description: Phone number in international format.
          type: string
          example: "+1234567890"
          nullable: true
        email:
          description: Email address of the payer or recipient.
          type: string
          format: email
          example: "john.doe@example.com"
          nullable: true
        birthDate:
          description: Date of birth in YYYY-MM-DD format.
          type: string
          example: "1990-01-15"
        ipAddress:
          description: IP address used during the payment or payout attempt.
          type: string
          example: "192.168.1.1"
          nullable: true
      type: object
    V1OrdersResponsePersonAddressDataResponse:
      title: V1-Orders-Response-PersonAddressDataResponse
      description: Address data of the payer or recipient collected during the payment or payout process.
      properties:
        type:
          description: Type of the address.
          type: string
          nullable: true
        zipCode:
          description: Postal code or ZIP code.
          type: string
          example: "12345"
          nullable: true
        country:
          description: Country in ISO 3166-1 alpha-2 format.
          type: string
          example: "US"
          nullable: true
        state:
          description: State, province, or region.
          type: string
          example: "California"
          nullable: true
        city:
          description: City name.
          type: string
          example: "Los Angeles"
          nullable: true
        address:
          description: Street address line.
          type: string
          example: "123 Main St"
          nullable: true
      type: object
    V1OrdersResponsePersonDocumentDataResponse:
      title: V1-Orders-Response-PersonDocumentDataResponse
      description: Document data of the payer or recipient.
      properties:
        type:
          description: Type of the document.
          type: string
          example: "passport"
          nullable: true
        series:
          description: Document series.
          type: string
          example: "AB"
          nullable: true
        number:
          description: Document number.
          type: string
          example: "1234567890"
          nullable: true
        issueCountry:
          description: Country that issued the document in ISO 3166-1 alpha-2 format.
          type: string
          example: "US"
          nullable: true
        validBefore:
          description: Expiration date of the document.
          type: string
          nullable: true
      type: object
    V1OrderResponseOrderPaymentOperationReference:
      title: V1-Order-Response-OrderPaymentOperationReference
      description: |
        Contains an array of operation reference parameters associated with a transaction.

        This object is returned when the payment provider supplies instruction or reference parameters for instruction-based methods. The parameters contain information needed for the customer to complete the transaction.

        Used for both orders (payments) and payouts.
      type: object
      required:
        - parameters
      properties:
        parameters:
          type: array
          description: |
            Array of label-value pairs containing operation details from the payment provider.

            The specific parameters returned depend on the payment provider and method used.
          items:
            $ref: "#/components/schemas/V1OrderResponseOrderPaymentOperationParameter"
        deepLink:
          description: |
            A deeplink URL for redirection to a mobile application (e.g., banking app) associated with the payment instruction.
          nullable: true
          allOf:
            - $ref: "#/components/schemas/ProcessingDtoPaymentPageActionPaymentPageActionInstructionDeepLink"

    V1OrderResponseOrderPaymentOperationParameter:
      title: V1-Order-Response-OrderPaymentOperationParameter
      description: |
        A single operation reference parameter consisting of a human-readable label and its corresponding value.

        These parameters are provided by the payment provider and contain instruction or reference information relevant to the transaction.
      type: object
      required:
        - label
        - value
      properties:
        label:
          type: string
          description: "Human-readable name of the parameter."
          example: "Reference"
        value:
          type: string
          description: |
            The actual value of the parameter.

            This contains the specific data provided by the payment provider.
          example: "KT53386"
    ProcessingDtoPaymentPageActionPaymentPageActionInstructionDeepLink:
      title: "Apic-Contracts-Processing-Dto-PaymentPageAction-PaymentPageActionInstructionDeepLink"
      required:
        - url
      properties:
        url:
          type: "string"
          description: "The deeplink URL to open the target application."
          example: "bankapp://pay?id=123"
        appName:
          type: "string"
          nullable: true
          description: "The name of the application to be opened, if available."
          example: "MyBank App"
      type: "object"
    customerResponse:
      type: object
      properties:
        customerId:
          type: string
          nullable: true
          description: |
            An identifier for the customer provided when creating the order or payout.
          example: "56656"
        firstName:
          type: string
          nullable: true
          description: "First name of the customer."
          example: "John"
        lastName:
          type: string
          nullable: true
          description: "Last name of the customer."
          example: "Doe"
        middleName:
          type: string
          nullable: true
          description: "Middle name of the customer, if applicable."
          example: "James"
        phone:
          type: string
          nullable: true
          description: "Customer's phone number, in international format."
          example: "79221110500"
        email:
          type: string
          nullable: true
          description: "Email address of the customer."
          format: email
          example: "john.doe@mymail.com"
        affiliatedId:
          type: string
          nullable: true
          description: "An optional identifier provided by the merchant to facilitate custom payment routing."
          example: "afl_4848301"
        birthDate:
          type: string
          nullable: true
          description: "The customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          example: 1990-12-30
        billingAddress:
          type: object
          nullable: true
          description: "The billing address for the customer"
          properties:
            addressType:
              type: string
              nullable: true
              description: "Type of the address. billing - billing address, shipping - shipping address"
              enum:
                - billing
                - shipping
            address:
              nullable: true
              type: string
              description: "Address line."
              example: "7, Sunny street"
            region:
              type: string
              nullable: true
              description: "Region of the billing address."
              example: "Limassol"
            city:
              type: string
              nullable: true
              description: "City of the billing address."
              example: "Limassol"
            country:
              type: string
              nullable: true
              description: "Country code in ISO 3166-1 alpha-2 format."
              example: "CY"
            zipCode:
              type: string
              nullable: true
              description: "Postal code."
              example: "4141"
            state:
              type: string
              nullable: true
              description: "State or region."
              example: "CA"
      description: "Container for customer-specific information."
    CreatePayoutRequest:
      type: object
      title: V1-Payout-Request-CreatePayoutRequest
      description: The payload required to create a new payout request
      required:
        - shopId
        - payout
        - recipient
      properties:
        shopId:
          type: integer
          description: "The unique identifier of the shop initiating the payout. [How to get your shopId](/docs/common/getting-started/shop-id)"
          example: 2
        payout:
          $ref: "#/components/schemas/PayoutRequest"
        purpose:
          type: string
          description: The purpose or reason for the payout request.
          maxLength: 128
          nullable: true
        providerCode:
          type: string
          description: "Determines which payment provider should be used to process the payout."
          example: "connectpay"
          nullable: true
        acquirerCode:
          description: "Identifies the specific acquirer responsible for processing payouts."
          type: string
          example: "gcash"
          nullable: true
        instrumentType:
          description: "Specifies the instrument type. [See available instrument types](/docs/merchant/instrument-type)"
          type: string
          example: "wallet"
          enum:
            - card
            - bank_transfer
            - wallet
            - crypto_wallet
            - voucher
            - cash
          nullable: true
        webhookUrl:
          type: string
          nullable: true
          format: uri
          pattern: '^https:\/\/.*'
          example: "https://example.com/webhook"
          description: |
            This parameter allows you to specify a webhook URL for receiving notifications about order status changes for this specific payout.

            If provided, notifications about the payout status changes will be sent to this URL instead of the [general webhook URL](/docs/common/getting-started/callbacks) set for the shop.
        dataEntryMode:
          nullable: true
          description: |
            Method for data entry to process payout:

            **redirect** - the entity making the payout enters payment information on the provider's (acquirer's) page via redirect;

            **h2h (host2host)** - the entity making the payout enters payment information via our API;

            **qr** - the entity making the payout scans a QR code and enters information on the aggregator's side.
          type: string
          enum:
            - redirect
            - h2h
            - qr
        paymentSettingsAlias:
          type: string
          nullable: true
          example: "alias2"
          description: |
            Use this field to specify which alias should be applied for this operation. The alias ensures that the correct payment configuration is used.

            For more detailed information about how to use aliases, refer to the [Alias Documentation](/docs/merchant/alias)
        mcc:
          type: integer
          description: "Merchant Category Code (MCC) is a four-digit number that classifies the type of business or service for a transaction. This field is optional, but for card payments, it is recommended to provide the MCC if more than one code is configured for your payment settings. If only one MCC is configured, it will be used automatically."
          maxLength: 4
          minLength: 4
          nullable: true
          example: 5999
        customer:
          type: object
          nullable: true
          description: |
            Container for customer-specific information. This section contains details about the user who requested the payout.
          required:
            - firstName
            - lastName
          properties:
            customerId:
              type: string
              nullable: true
              description: "A unique identifier for the customer. The `customerId` can either be unique within a shop or across the entire company/merchant. To determine the setting for your shop, check the admin panel of your merchant account under the settings menu in the field 'External customer ID unique for'."
              example: "56656"
            firstName:
              type: string
              description: "First name of the customer."
              example: "John"
            lastName:
              type: string
              description: "Last name of the customer."
              example: "Doe"
            middleName:
              type: string
              nullable: true
              description: "Middle name of the customer, if applicable."
              example: "James"
            phone:
              type: string
              nullable: true
              description: "Customer's phone number, in international format."
              example: "79221110500"
            email:
              type: string
              nullable: true
              description: "Email address of the customer."
              format: email
              example: "john.doe@mymail.com"
            birthDate:
              description: "Customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
              type: string
              example: 1990-12-30
              nullable: true
            details:
              type: object
              description: Customer details
              nullable: true
              properties:
                addressData:
                  type: object
                  description: Customer address data
                  nullable: true
                  properties:
                    city:
                      description: City name
                      maxLength: 255
                      type: string
                      example: Beverly Hills
                      nullable: true
                    countryCode:
                      description: ISO 3166-1 alpha-2 country code
                      type: string
                      maxLength: 2
                      minLength: 2
                      example: US
                    state:
                      description: State or province name
                      type: string
                      maxLength: 255
                      example: California
                      nullable: true
                    zipCode:
                      description: Postal code
                      maxLength: 10
                      type: string
                      example: "90210"
                      nullable: true
                    address:
                      description: "Full street address of the customer"
                      type: string
                      nullable: true
                      example: 42, Sunset Blvd.
            metaData:
              type: object
              description: Customer metadata
              nullable: true
              properties:
                affiliatedId:
                  maxLength: 255
                  type: string
                  nullable: true
                  description: |
                    An optional identifier provided by the merchant to facilitate custom payment routing. 
                    This field allows you to pass any arbitrary value, which will be stored in the customer's record.
                  example: "afl_4848301"
        recipient:
          description: |
            Detailed information about the payout recipient.
            To know which fields need to be provided for each payout, first call the [Retrieve Required Payout Fields](/docs/merchant-api/post-app-external-v-1-payout-payoutfields-getfields) endpoint. It will return the required fields for creating the payout.

            **Behavior:**
            - If `recipient` data is provided with all required fields, those values are used for the payout
            - If `recipient` is not provided or has incomplete data, required fields will be requested on the payment page (when `dataEntryMode` supports it)

            **Priority rules when both `customer` and `recipient` are provided:**
            - If the company setting "Use customer data as payer information" is enabled, data from `customer` and `recipient` objects will be merged
            - Fields from `recipient` object take priority over corresponding fields from `customer` (including `recipient.personalData.id` over `customer.customerId`)
            - Missing fields in `recipient` will be supplemented from `customer` data

            For more details, see [Customer and Payer Data](/docs/merchant/person-data).
          allOf:
            - $ref: "#/components/schemas/Recipient"
        sender:
          description: |
            Details about the payout sender. For some providers, it is necessary to provide additional sender information for the payout.
            To know which fields need to be provided for each payout, first call the [Retrieve Required Payout Fields](/docs/merchant-api/post-app-external-v-1-payout-payoutfields-getfields) endpoint. It will return the required fields for creating the payout.
          allOf:
            - $ref: "#/components/schemas/Recipient"
        redirectUrls:
          type: object
          nullable: true
          properties:
            success:
              type: string
              nullable: true
              description: "URL to redirect to when the payout is successful."
              format: uri
              example: "https://example.com/success"
            failure:
              type: string
              nullable: true
              description: "URL to redirect to when the payout fails."
              format: uri
              example: "https://example.com/failure"
            inProgress:
              type: string
              nullable: true
              description: "URL to redirect to when the payout is in progress."
              format: uri
              example: "https://example.com/inProgress"
            pending:
              type: string
              nullable: true
              description: "URL to redirect to when the payout is pending."
              format: uri
              example: "https://example.com/pending"
          description: "Redirect URLs for the payout."
    payout.status:
      type: object
      required:
        - shopId
        - id
        - payoutNumber
        - payoutStatus
        - cost
        - payoutCreatedAt
        - payoutTransactions
      properties:
        shopId:
          type: integer
          description: "The unique identifier of the shop initiating the payout."
          example: 123
        id:
          type: integer
          description: "The internal unique identifier of the payout within the system. Used for referencing the payout when contacting technical support in case of any issues."
          example: 54222
        payoutStatus:
          type: string
          description: "Status of the payout. [Description of Statuses](/docs/merchant/orders/order-life-cycle#orderpayment-actions-and-conditions)"
          example: "in_progress"
          enum:
            - in_progress
            - failed
            - completed
            - cancelled
            - need_action
            - review
        payoutNumber:
          type: string
          description: "A unique identifier for the payout, generated by the merchant, and specific to each `shopId`."
          example: "56573FDFVFDBWF"
        purpose:
          type: string
          nullable: true
          description: "The purpose or reason for the payout request."
        cost:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "Total cost of the payout, formatted as a decimal string with a period (.) as the decimal separator."
              example: "56.99"
            currency:
              type: string
              description: "Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
              example: "USD"
            region:
              type: string
              description: "The ISO 3166-1 alpha-2 country code of payout country."
              example: "US"
          description: "Container for cost-related information."
        payoutCreatedAt:
          type: string
          description: "Date and time the payout was created, in RFC 3339 format including the UTC zone."
          example: "2023-08-29T15:34:56+03:00"
        reviewTimeout:
          type: integer
          nullable: true
          minimum: 1
          maximum: 1440
          description: |
            Time limit for submitting a decision on payouts that require manual antifraud review in minutes. Valid range: 1 to 1440 minutes (24 hours).

            This field is only present when `payoutStatus` is `review`. If no decision is submitted within this timeout period using the [Submit Antifraud Review Decision](/docs/merchant-api/submit-antifraud-review-decision) endpoint, the transaction will be automatically declined.

            For more information about the review process, see [Antifraud Manual Review](/docs/merchant/antifraud-review).
          example: 120
        payoutPaidAt:
          type: string
          description: "Date and time when the payout was successfully sent to the recipient, formatted according to RFC 3339, including the UTC time zone."
          example: "2023-08-29T15:34:56+03:00"
          nullable: true
        payoutTransactions:
          type: array
          description: "An array of payouts objects related to the payout. If the array is empty, it indicates that no payouts have been made for the payout yet. If an payout is paid with multiple payouts, there will be one object per payout in the array."
          items:
            $ref: "#/components/schemas/payout"
        customer:
          allOf:
            - $ref: "#/components/schemas/customerResponse"
          nullable: true
        payoutDetails:
          type: object
          description: Describes the details of the payout, which vary according to the `instrumentType` used.
          nullable: true
          properties:
            recipient:
              description: "The details of the entity receiving the payout. Contains information specific to the payment instrument type."
              nullable: true
              oneOf:
                - $ref: "#/components/schemas/CardPaymentDetailsPayout"
                - $ref: "#/components/schemas/BankTransferPaymentDetailsPayout"
                - $ref: "#/components/schemas/WalletPaymentDetailsPayout"
                - $ref: "#/components/schemas/RecipientPayoutDetailsCryptoWallet"
                - $ref: "#/components/schemas/PayoutDetailsVoucher"
            sender:
              nullable: true
              description: "The details of the entity initiating the payout. Contains information specific to the payment instrument type."
              oneOf:
                - $ref: "#/components/schemas/CardPaymentDetailsPayout"
                - $ref: "#/components/schemas/BankTransferPaymentDetailsSenderPayout"
                - $ref: "#/components/schemas/WalletPaymentDetailsPayout"
                - $ref: "#/components/schemas/SenderPayoutDetailsCryptoWallet"
                - $ref: "#/components/schemas/PayoutDetailsVoucher"
        statusReason:
          type: string
          nullable: true
          example: "The order amount is not equal to the amount of payments."
          description: |

            A short explanation of why the payout is in its current status (e.g., `need_action`, `failed`, or `cancelled`).

            This field may contain system-generated messages or error details from the payment provider.

            For example, if the total of completed payments does not match the order amount, the system sets the status to `need_action` and provides the message: "The order amount is not equal to the amount of payments."

            This field will remain empty for statuses such as `completed` or `in_progress`.
        description:
          type: string
          maxLength: 128
          description: "Optional text providing additional context for the payout."
          example: "Internal reference #123"
    CardPaymentDetailsPayout:
      type: object
      title: "instrumentType=card"
      properties:
        paymentSystem:
          type: string
          nullable: true
          description: |
            Brand of the card used in the transaction.

            visa - "Visa"

            mastercard - "MasterCard"

            jcb - "JCB"

            amex - "American Express"

            dci - "Diners Club International"

            unionpay - "UnionPay"

            upi - "UnionPay International"

            mir - "Mir"

            discover - "Discover"

            redcompra - "Redcompra"

            elo - "Elo"

            hipercard - "Hipercard"

            maestro - "Maestro"

            verve - "Verve"
          enum:
            - visa
            - mastercard
            - jcb
            - amex
            - dсi
            - unionpay
            - upi
            - mir
            - discover
            - redcompra
            - elo
            - hipercard
            - maestro
            - verve
        maskedCardNumber:
          type: string
          nullable: true
          description: |
            This field displays a partially obscured version of the card number to maintain security and privacy.
            Depending on the provider, the masked card number might show:

              - **The first 6 and last 4 digits**, with the intervening digits replaced by asterisks (e.g., 123456******1234)
              - **Only the last 4 digits** (e.g., **** **** **** 1234)
          example: "123456******1234"
    BankTransferPaymentDetailsPayout:
      type: object
      title: "instrumentType=bank_transfer"
      properties:
        accountNumber:
          type: string
          nullable: true
          description: The bank account number.
          example: "34543243243534333"
        transferType:
          nullable: true
          description: "Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type)"
          type: string
          enum:
            - swift
            - sepa
            - bank_wire
            - card2card
            - pix
            - sbp
            - online_banking
            - open_finance
            - virtual_account
            - qris
            - promptpay
            - thaiqr
            - spei
            - vietnambanksqr
            - vietqr
            - khipu
            - paysafecard
            - multibanco
            - bancontact
            - blik
            - p24
            - rapidtransfer
            - thb_qr
            - upi
            - upi_intent
            - sberbank
            - giropay
            - eps
            - account2card
            - fpx
            - trustly
            - wise
            - n26
            - pesalink
            - imps
            - upi_p2p
            - upi_fast_vip
            - mybank
            - tink
            - bizum
            - sofort
            - p2p
            - easypay
            - klarna
            - clabe
            - codi
            - rapipago
            - pse
    BankTransferPaymentDetailsSenderPayout:
      type: object
      title: "instrumentType=bank_transfer"
      properties:
        accountNumber:
          type: string
          nullable: true
          description: The bank account number.
          example: "34543243243534333"
    WalletPaymentDetailsPayout:
      type: object
      title: "instrumentType=wallet"
      properties:
        walletId:
          type: string
          nullable: true
          description: The identifier of the e-wallet.
          example: "34534534333"
    RecipientPayoutDetailsCryptoWallet:
      title: "instrumentType=crypto_wallet"
      type: object
      required:
        - blockchain
        - token_standard
      properties:
        recipientCryptoAddress:
          type: string
          nullable: true
          description: >
            The recipient's cryptocurrency wallet address.
          example: "0xAbC1234567890abcdef1234567890abcdef1234"
        recipientCryptoAddressMeta:
          type: string
          nullable: true
          description: >
            Additional metadata for the recipient's crypto wallet, such as a memo
            or tag required by certain blockchains.
          example: "Memo123"
        txHash:
          type: string
          nullable: true
          description: >
            The transaction hash of the crypto payout, usually provided by the
            blockchain after the transaction is broadcast.
          example: "0x123abc456def7890abc123def456ghi789jkl012"
        blockchain:
          type: string
          description: >
            The name of the blockchain used for this crypto payout, e.g. "Tron" if
            the transfer is on the TRON network.
          example: "Tron"
        tokenStandard:
          type: string
          description: >
            The token standard for this crypto payout, e.g. "TRC20" is used
            for TRON tokens.
          example: "TRC20"
        tronscanUrl:
          type: string
          nullable: true
          description: >
            A direct link to view transaction details on TronScan. Only relevant if
            `blockchain` is set to "Tron".
          example: "https://tronscan.org/#/transaction/0x123abc456def7890abc123def456ghi789jkl012"
        amlRisk:
          type: string
          enum: [Low, Medium, High, Severe]
          nullable: true
          description: >
            Indicates the Anti-Money Laundering (AML) risk level for this payout,
            which can be determined based on various AML checks.
          example: "Low"
    PayoutDetailsVoucher:
      title: "instrumentType=voucher"
      type: object
      properties:
        serialNumber:
          type: string
          nullable: true
          description: "A  serial number identifying the voucher for payout."
          example: "0xAbC1234567890abcdef1234567890abcdef1234"
    SenderPayoutDetailsCryptoWallet:
      title: "instrumentType=crypto_wallet"
      type: object
      properties:
        senderCryptoAddress:
          type: string
          nullable: true
          description: "The sender's cryptocurrency wallet address."
          example: "0xFEdcBA9876543210fedcba9876543210fedcba98"
        txHash:
          type: string
          nullable: true
          description: "The transaction hash of the cryptocurrency payout."
          example: "0x210fedcba9876543210fedcba9876543210fedcb"
        blockchain:
          type: string
          description: >
            The name of the blockchain on which this crypto transfer occurs.
          example: "Tron"
        tokenStandard:
          type: string
          description: >
            The specific token standard for this crypto transfer.
          example: "TRC20"
        senderCryptoAddressMeta:
          type: object
          nullable: true
          description: "Additional metadata for the sender address."
          example:
            destinationTag: "123456789"
        tronscanUrl:
          type: string
          nullable: true
          description: >
            A direct URL to view transaction details on TronScan.
            This is relevant only if blockchain is set to "Tron".
          example: "https://tronscan.org/#/transaction/0x123abc456def7890abc123def456ghi789jkl012"
        amlRisk:
          type: string
          enum: [Low, Medium, High, Severe]
          nullable: true
          description: >
            Indicates the Anti-Money Laundering (AML) risk level associated with
            this transaction.
          example: "Low"
    payout:
      type: object
      required:
        - transactionId
        - cost
        - provider
        - acquirer
        - status
        - instrumentType
      properties:
        transactionId:
          type: string
          description: "Identifier for the specific transaction assigned by our system"
          example: "79"
        providerTransactionId:
          description: "Identifier for the specific transaction assigned by the payment provider."
          type: string
          example: "990943"
        cost:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "The amount of the transaction. Formatted as a decimal string with a period (.) as the decimal separator."
              example: "56.99"
            currency:
              type: string
              description: "Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
              example: "USD"
          description: "Financial details of the payout"
        provider:
          type: object
          properties:
            code:
              type: string
              description: "Provider code."
              example: "fyst"
          description: "Information about the provider for this payout."
        acquirer:
          type: object
          properties:
            code:
              type: string
              description: "Acquirer code."
              example: "fyst"
          description: "Information about the acquirer for this payout."
        instrumentType:
          type: string
          description: "Specifies the payout instrument. [See available payment instruments](/docs/merchant/instrument-type)"
          example: "card"
          enum:
            - card
            - bank_transfer
            - wallet
            - crypto_wallet
            - voucher
            - cash
        status:
          type: object
          description: "Contains the status of the payout, including detailed information in case of payout failure."
          required:
            - status
          properties:
            status:
              type: string
              description: "The current state of the payout. [Description of Statuses](/docs/merchant/orders/order-life-cycle#orderpayment-actions-and-conditions)"
              example: failed
              enum:
                - in_progress
                - completed
                - cancelled
                - failed
                - review
            details:
              nullable: true
              description: "Provides additional error details if the payout fails."
              properties:
                errorId:
                  description: "A unique identifier for the error generated by the system, used for tracking and troubleshooting."
                  type: string
                  example: "61740c87-b60d-4578-bf25-575a8c68532e"
                  nullable: true
                providerMessage:
                  description: "An error message provided by the payment provider, offering insight into the reason for the failure."
                  example: "Payout method not found"
                  type: string
                  nullable: true
                code:
                  description: "An internal error code used by the system to categorize the type of error that occurred."
                  example: 401
                  type: integer
                  nullable: true
        recipient:
          description: |
            Information about the recipient collected during the payout attempt.

            This object is particularly useful for antifraud review processes, allowing merchants to make informed decisions based on comprehensive recipient information.
          nullable: true
          $ref: "#/components/schemas/V1OrdersResponsePersonDataResponse"
        operationReference:
          description: |
            Contains operation reference parameters received from the payment provider for instruction-based payment methods.

            This object provides label-value pairs with transaction details that may include reference codes, amounts, entity identifiers, account numbers, or other provider-specific information needed for transaction completion or reconciliation.

            For orders, this field is typically used in shop-hosted integrations where payment instructions are delivered directly via API. See [H2H Integration for Instructions](/docs/merchant/orders/shop-hosted) for implementation details.
          nullable: true
          allOf:
            - $ref: "#/components/schemas/V1OrderResponseOrderPaymentOperationReference"
    PayoutRequest:
      title: V1-Payout-Request-PayoutRequest
      description: Details of the payout.
      required:
        - cost
        - payoutNumber
      properties:
        cost:
          $ref: "#/components/schemas/CostRequest"
        payoutNumber:
          type: string
          description: |
            A unique identifier for the payout that you must generate on your side. The `payoutNumber` should be specific to the `shopId` or your company (depending on your company's settings) and must be unique for every order and payout within each `shopId` or your company (depending on your company's settings).

              The `payoutNumber` may contain only Latin letters (uppercase and lowercase), numbers, and hyphens. Hyphens cannot be at the beginning or end of the string.
          example: "43242332"
        region:
          type: string
          nullable: true
          description: "For some providers, it is mandatory to specify the payout region. The region should be specified in ISO 3166-1 alpha-2 code format."
        cryptoTokenStandard:
          type: string
          nullable: true
          description: |
            The token standard for cryptocurrency payouts.

            **When to use:**
            - Required when using token-based cryptocurrencies (e.g., USDT, USDC) with `crypto_currency_code` format in `cost.currency`
            - Not required for native cryptocurrencies (BTC, ETH, SOL, TRX, LTC)
            - Not required when using `asset_code` format (e.g., USDT_TRC20) in `cost.currency`

            **Examples:**
            - "TRC20" for USDT on Tron network
            - "ERC20" for tokens on Ethereum network
            - "BEP20" for tokens on Binance Smart Chain

            **Important:** Use the value from the `cryptoTokenStandard` column in the [supported cryptocurrencies table](/docs/merchant/crypto#supported-currencies).

            **Two methods for specifying cryptocurrency:**
            - Method 1: Use `crypto_currency_code` (e.g., "USDT") in `cost.currency` + specify `cryptoTokenStandard` (e.g., "TRC20")
            - Method 2: Use `asset_code` (e.g., "USDT_TRC20") in `cost.currency` - no need to specify `cryptoTokenStandard`
          example: "TRC20"
        description:
          type: string
          maxLength: 128
          description: "Optional text providing additional context for the payout."
          example: "Internal reference #123"
        localDateTime:
          description: Local date and time of the order in payer's timezone. Need only in h2h orders. Format ISO 8601 (YYYY-MM-DD HH:MM:SS).
          type: string
          nullable: true
          example: "2025-03-31T15:16:23Z"
      type: object
    CostRequest:
      title: V1-Order-Request-CostRequest
      required:
        - amount
        - currency
      properties:
        amount:
          description: Defines the total payout amount, formatted as a decimal string with a period (.) as the decimal separator. For fiat currencies, the number of decimal places should comply with the ISO 4217 standard for the specified currency. If a cryptocurrency is used, specify the amount to match the token's precision.
          type: string
          pattern: '[0-9]*(\.[0-9]*)?'
          example: "100.50"
        currency:
          description: |
            Specifies the currency for the payout.

            **For fiat currencies:** Use the ISO 4217 alphabetic code format (3 uppercase letters).
            - Example: "USD", "EUR", "PHP"

            **For cryptocurrencies,** there are two methods to specify the currency:

            **Method 1: Using crypto_currency_code**
            - Use the cryptocurrency symbol (e.g., "USDT", "BTC", "ETH")
            - For token-based cryptocurrencies, you must also specify `cryptoTokenStandard` field in the payout object
            - For native cryptocurrencies (BTC, ETH, SOL, TRX, LTC), `cryptoTokenStandard` is not required
            - Example: "USDT" with cryptoTokenStandard: "TRC20"
            - Example: "BTC" (no cryptoTokenStandard needed)

            **Method 2: Using asset_code**
            - Use the full asset code that includes the blockchain/token standard
            - No need to specify `cryptoTokenStandard` separately
            - Example: "USDT_TRC20", "USDT_ERC20", "USDC_TRC20"
            - Example: "BTC" (same for native cryptocurrencies)

            For a full list of supported cryptocurrencies and their formats, see the [Cryptocurrency Reference Guide](/docs/merchant/crypto#supported-currencies).
          type: string
          example: "PHP"
      type: object
    PayoutResponse:
      title: V1-Payout-Response-PayoutResponse
      required:
        - status
        - payoutNumber
      properties:
        payoutStatus:
          type: string
          description: "The current status of the payout operation. [See more info](/docs/merchant/payouts/scenarios#payout-life-cycle)"
          enum:
            - registered
            - in_progress
            - completed
            - failed
            - cancelled
            - need_action
            - review
        payoutNumber:
          type: string
          description: "Unique code identifying the specific payout."
          example: "payout-123456"
        payoutLink:
          type: string
          nullable: true
          description: "A link to the payout details page."
          example: "https://payout-123456.com"
      type: object
    CurrencyAlpha3Type:
      description: "An ISO 4217 currency code representing the currency."
      type: string
      example: USD
    PaymentMethodResponse:
      title: Payment Method Details
      type: object
      description: "Details of a payment method available to the shop."
      required:
        - providerCode
        - instrumentType
        - isDefault
        - currencies
        - regions
        - acquirerCode
        - allowedCards
        - dataEntryModes
      properties:
        providerCode:
          description: "Determines which payment provider should be used to process the payment."
          type: string
          example: "d24"
        acquirerCode:
          description: "Identifies the specific acquirer responsible for processing payments."
          type: string
          example: "Directa24"
        instrumentType:
          description: "Specifies the instrument type. [See available instrument types](/docs/merchant/instrument-type)"
          type: string
          enum:
            - card
            - bank_transfer
            - wallet
            - crypto_wallet
            - voucher
            - cash
          example: card
        entryMode:
          description: "Applicable only for `instrumentType` == `card`. Specifies the method by which payment data is entered. [Payment Entry Modes for instrument type card](/docs/merchant/instrument-type#payment-entry-modes-for-payment-instrument-card)."
          type: string
          example: "cnp"
          enum:
            - cnp
            - card_present
            - moto
            - recurring
            - saved_card
            - apple_pay
            - google_pay
            - samsung_pay
          nullable: true
        dataEntryModes:
          description: |
            Methods for customer data entry to process payment:

            **redirect** - the customer enters payment information on the provider's (acquirer's) page via redirect;

            **h2h (host2host)** - the customer enters payment information on our payment page;

            **qr** - the customer scans a QR code and enters information on the aggregator's side;

            **instruction** - provides payment instructions to the customer, such as manual payment steps.

            **iframe** - embeds the payment form directly to the payment page, offering a seamless user experience without redirecting the customer to a new page.

            **html** - the payment details or form are delivered as HTML content.

          type: array
          items:
            type: string
            enum:
              - redirect
              - h2h
              - qr
              - instruction
              - iframe
              - html
          example:
            - redirect
        allowedCards:
          description: "Applicable only for `instrumentType` == `card`. Specifies the credit or debit card brands that can be used with this payment method."
          type: array
          items:
            type: string
          example: ["visa"]
        transferType:
          description: |
            **Deprecated:** This field is deprecated and will be removed in future releases.

            Applicable only for `instrumentType` == `bank_transfer`. Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type)

            It is retained for backward compatibility. Use `transferTypes` instead.
            If a payment method supports only one transfer type, it will be returned here.
            If multiple transfer types are available, this field will be `null`, and you should use `transferTypes`.
          type: string
          enum:
            - swift
            - sepa
            - bank_wire
            - card2card
            - pix
            - sbp
            - online_banking
            - open_finance
            - virtual_account
            - qris
            - promptpay
            - thaiqr
            - spei
            - vietnambanksqr
            - vietqr
            - khipu
            - paysafecard
            - multibanco
            - bancontact
            - blik
            - p24
            - rapidtransfer
            - thb_qr
            - upi
            - upi_intent
            - sberbank
            - giropay
            - eps
            - account2card
            - fpx
            - trustly
            - wise
            - n26
            - pesalink
            - imps
            - upi_p2p
            - upi_fast_vip
            - mybank
            - tink
            - bizum
            - sofort
            - p2p
            - easypay
            - klarna
            - clabe
            - codi
            - rapipago
            - pse
          example: bank_wire
          nullable: true
        transferTypes:
          description: |
            An array of available bank transfer types for the specified payment method.
            Applicable only for `instrumentType` == `bank_transfer`. Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type)
          type: array
          items:
            type: string
            enum:
              - swift
              - sepa
              - bank_wire
              - card2card
              - pix
              - sbp
              - online_banking
              - open_finance
              - virtual_account
              - qris
              - promptpay
              - thaiqr
              - spei
              - vietnambanksqr
              - vietqr
              - khipu
              - paysafecard
              - multibanco
              - bancontact
              - blik
              - p24
              - rapidtransfer
              - thb_qr
              - upi
              - upi_intent
              - sberbank
              - giropay
              - eps
              - account2card
              - fpx
              - trustly
              - wise
              - n26
              - pesalink
              - imps
              - upi_p2p
              - upi_fast_vip
              - mybank
              - tink
              - bizum
              - sofort
              - p2p
              - easypay
              - klarna
              - clabe
              - codi
              - rapipago
              - pse
          example: bank_wire
          nullable: true
        currencies:
          description: |
            A list of currency codes supported by this payment instrument.

            For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters. 

            For cryptocurrencies, a specific format is used; a full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies)."
          type: array
          example: ["USD"]
          items:
            type: string
        regions:
          type: array
          description: "A list of regions where this payment method is available. Each region will be specified by its ISO 3166-1 alpha-2 code"
          example: ["BR"]
          items:
            type: string
            pattern: "^[A-Z]{2}$"
        isDefault:
          description: "Specifies whether this payment method is set as the default for this shop. When creating an order ([Create Order](/docs/merchant-api/create-order)), if the `paymentSettings` object is not explicitly provided, the payment will be processed using this default payment method."
          example: false
          type: boolean
        paymentSettingsAlias:
          description: |
            A unique identifier assigned to a specific payment configuration. Use this alias when creating orders to ensure the correct payment settings are applied. This field is optional and will be provided in the response only if the payment method has been configured with an alias.

            For more detailed information about how to use aliases, refer to the [Alias Documentation](/docs/merchant/alias)
          example: "testAlias"
          nullable: true
          type: string
    RecipientPersonalData:
      type: object
      nullable: true
      description: "Personal identification and contact information."
      properties:
        firstName:
          type: string
          description: "The first name."
          example: "John"
          nullable: true
        lastName:
          type: string
          description: "The last name."
          example: "Smith"
          nullable: true
        middleName:
          type: string
          description: "The middle name, if any."
          example: "Alexander"
          nullable: true
        phone:
          type: string
          description: "The phone number, including the country code."
          example: "+15557654321"
          nullable: true
        email:
          type: string
          description: "The email address."
          example: "john.smith@example.com"
          nullable: true
        birthDate:
          type: string
          description: "The date of birth in ISO 8601 format (YYYY-MM-DD)."
          example: "1990-12-30"
          nullable: true
        ipAddress:
          type: string
          description: "The IP address."
          example: "1.1.1.1"
          nullable: true
        id:
          type: string
          description: "The ID of the person."
          nullable: true
        beneficiaryName:
          type: string
          description: "The name of the beneficiary."
          example: "John"
          nullable: true
        beneficiarySurname:
          type: string
          description: "The surname of the beneficiary."
          example: "Doe"
          nullable: true
    RecipientAddress:
      type: object
      nullable: true
      description: "Address information."
      properties:
        countryCode:
          type: string
          description: "The ISO 3166-1 alpha-2 country code of the location."
          example: "US"
          nullable: true
        state:
          type: string
          description: "The state of the address."
          example: "NY"
          nullable: true
        region:
          type: string
          description: "The region code."
          example: "US"
          nullable: true
        city:
          type: string
          description: "The city of the address."
          example: "New York"
          nullable: true
        zipCode:
          type: string
          description: "The zip code of the address."
          example: "10001"
          nullable: true
        address:
          type: string
          description: "The complete address line"
          example: "456 Liberty Ave."
          nullable: true
        street:
          type: string
          description: "The name of the street without the building number or extra address details."
          example: "Liberty Ave."
          nullable: true
    RecipientDocuments:
      type: object
      nullable: true
      description: "Document identification."
      properties:
        identityDocumentId:
          type: string
          description: "The identification document number."
          example: "AB1234567"
          nullable: true
        TIN:
          type: string
          description: "The Individual Taxpayer Identification Number, applicable in some jurisdictions."
          example: "123456789012"
          nullable: true
        RUT:
          type: string
          description: "Unique Taxpayer Identification Number (RUT), used primarily in Chile."
          example: "123456785"
          nullable: true
        documentNumber:
          type: string
          description: "Document number for identification purposes."
          example: "DOC12345678"
          nullable: true
        documentType:
          type: string
          description: "Specifies the type of identification document provided."
          example: "passport"
          nullable: true
    RecipientCardData:
      type: object
      description: "Information required for processing a payout via credit card"
      nullable: true
      properties:
        cardNumber:
          type: string
          description: "The card number."
          example: "4111111111111111"
          nullable: true
        cardHolderName:
          type: string
          description: "Name printed on the card."
          example: "JOHN A DOE"
          nullable: true
        expireMonth:
          type: string
          description: "Expiration month of the card."
          example: "12"
          nullable: true
        expireYear:
          type: string
          description: "Expiration year of the card."
          example: "2023"
          nullable: true
    RecipientCryptoWalletData:
      type: object
      description: "Information required for processing a payout via crypto wallet."
      nullable: true
      properties:
        cryptoWalletId:
          type: string
          description: "The unique identifier of the  cryptocurrency wallet."
          nullable: true
          example: "0x1234567890abcdef1234567890abcdef1234567"
        cryptoWalletMetaTag:
          type: string
          description: "An optional tag, memo, or destination tag required for certain cryptocurrencies"
          example: "123456"
          nullable: true
    RecipientWalletData:
      type: object
      description: "Information required for processing a payout via e-wallet."
      nullable: true
      properties:
        walletType:
          type: string
          description: "The type of e-wallet "
          nullable: true
        walletId:
          type: string
          description: "The e-wallet identifier."
          example: "eWallet12345"
          nullable: true
        walletName:
          type: string
          description: "The e-wallet name."
          example: "eWalletName"
          nullable: true
        walletHolderName:
          type: string
          description: "The name of the e-wallet holder."
          example: "John Doe"
          nullable: true
    PayerBankTransferData:
      type: object
      description: "Information required for processing a payment via bank transfer. Applicable only when `instrumentType` is `bank_transfer`."
      nullable: true
      properties:
        bankCode:
          type: string
          description: "The specific code of the bank."
          example: "BangkokBank"
          nullable: true
        accountName:
          type: string
          description: "The name associated with the bank account."
          example: "BangkokBank Account Name"
          nullable: true
        accountNumber:
          type: string
          description: "The bank account number."
          example: "12345"
          nullable: true
        accountType:
          type: string
          description: "The type of bank account (e.g., Savings, Checking)."
          example: "Savings"
          nullable: true
        bankName:
          type: string
          description: "The name of the bank."
          example: "Big Bank"
          nullable: true
        bankBranch:
          type: string
          description: "The branch of the bank where the account is held."
          example: "Downtown Branch"
          nullable: true
        bankCity:
          type: string
          description: "The city where the bank is located."
          example: "New York"
          nullable: true
        bankAddress:
          type: string
          description: "The primary address of the bank."
          example: "123 Bank St."
          nullable: true
        bankAccountUserId:
          type: string
          description: "The user ID of the bank account."
          example: "1234567890"
          nullable: true
        bankZipCode:
          type: string
          description: "The postal code of the bank's address."
          example: "10001"
          maxLength: 10
          nullable: true
        bankProvince:
          type: string
          description: "The province or state of the bank's location, if applicable."
          example: "NY"
          nullable: true
        bankArea:
          type: string
          description: "Bank area."
          example: "Manhattan"
          nullable: true
        routingNumber:
          type: string
          description: "The routing number of the bank."
          example: "021000021"
          nullable: true
        iban:
          type: string
          description: "International Bank Account Number."
          example: "DE89370400440532013000"
          nullable: true
        bankBic:
          type: string
          description: "The Bank Identifier Code (BIC)."
          example: "BBANKNYXXXX"
          nullable: true
    RecipientBankTransferData:
      type: object
      description: "Information required for processing a payout via bank transfer."
      nullable: true
      properties:
        accountNumber:
          type: string
          description: "The bank account number."
          example: "123456789012"
          nullable: true
        accountType:
          type: string
          description: "The type of bank account (e.g., Savings, Checking)."
          example: "Savings"
          nullable: true
        accountName:
          type: string
          description: "The name associated with the bank account."
          example: "John A. Doe"
          nullable: true
        bankName:
          type: string
          description: "The name of the bank."
          example: "Big Bank"
          nullable: true
        bankBranch:
          type: string
          description: "The branch of the bank where the account is held."
          example: "Downtown Branch"
          nullable: true
        bankCode:
          type: string
          description: "The specific code of the bank, often used in domestic transactions."
          example: "001"
          nullable: true
        bankCity:
          type: string
          description: "The city where the bank is located."
          example: "New York"
          nullable: true
        bankAddress:
          type: string
          description: "The primary address of the bank."
          example: "123 Bank St."
          nullable: true
        bankAccountUserId:
          type: string
          description: "The user ID of the bank account."
          example: "1234567890"
          nullable: true
        bankZipCode:
          type: string
          description: "The postal code of the bank's address."
          example: "10001"
          maxLength: 10
          nullable: true
        bankProvince:
          type: string
          description: "The province or state of the bank's location, if applicable."
          example: "NY"
          nullable: true
        bankArea:
          type: string
          description: "Bank area"
          example: "Manhattan"
          nullable: true
        routingNumber:
          type: string
          description: "The routing number of the bank, required for bank transfers in certain countries."
          example: "021000021"
          nullable: true
        iban:
          type: string
          description: "International Bank Account Number."
          example: "DE89370400440532013000"
          nullable: true
        bankBic:
          type: string
          description: "The Bank Identifier Code (BIC), used in international transactions."
          example: "BBANKNYXXXX"
          nullable: true
        transitNumber:
          type: string
          description: "The transit number used to identify the bank branch."
          example: "12345"
          nullable: true
        financialInstitutionNumber:
          type: string
          description: "The number that identifies the financial institution."
          example: "001"
          nullable: true
        transferType:
          description: "The type of bank transfer to be processed."
          type: string
          nullable: true
    payoutData:
      type: object
      nullable: true
      description: "Details related to the payout, including fee responsibility and currency."
      properties:
        feeBear:
          type: string
          description: "Indicates who bears the fee for the transaction."
          nullable: true
        sourceCurrency:
          type: string
          nullable: true
          description: |
            The source currency in which the sender's or recipient's account is denominated.

            When using cryptocurrency, see details about [sourceCurrency](/docs/merchant/crypto#using-source-currency-provider-specific)
          example: "USD"
        payoutChannel:
          type: string
          description: "The channel used for the payout."
          example: "internal"
          nullable: true
    Recipient:
      type: object
      properties:
        personalData:
          $ref: "#/components/schemas/RecipientPersonalData"
        addressData:
          $ref: "#/components/schemas/RecipientAddress"
        documentData:
          $ref: "#/components/schemas/RecipientDocuments"
        cardData:
          $ref: "#/components/schemas/RecipientCardData"
        walletData:
          $ref: "#/components/schemas/RecipientWalletData"
        bankTransferData:
          $ref: "#/components/schemas/RecipientBankTransferData"
        payoutData:
          $ref: "#/components/schemas/payoutData"
        cryptoWalletData:
          $ref: "#/components/schemas/RecipientCryptoWalletData"

    RequiredPayoutFieldsResponse:
      type: object
      description: "Information about the mandatory data needed to initiate a payout."
      required:
        - key
        - label
        - category
        - validation
      properties:
        key:
          type: string
          description: "The name of the parameter expected in the [payout request](/docs/merchant-api/post-app-external-v-1-payout-payout-create) within the `recipient` or `sender` object."
          example: firstName
        label:
          type: string
          description: "Human-readable name for the `key` parameter. Can be used for displaying to the user on the front end."
          example: First Name
        category:
          type: string
          example: personalData
          description: |
            Indicates in which object the `key` parameter should be passed in during a payout request.

            **personalData** - Personal identification and contact information of the recipient or sender.

            **addressData** - Address information for the payout recipient or sender.

            **billingAddressData** - Billing address information for the payout recipient or sender.

            **shippingAddressData** - Shipping address information for the payout recipient or sender.

            **documentData** - Information required for verifying the identity of the recipient or sender.

            **cardData** - Information required for processing a payout via debit/credit card for the recipient or sender.

            **walletData** - Information required for processing a payout via e-wallet for the recipient or sender.

            **bankTransferData** - Information required for processing a payout via bank transfer for the recipient or sender.

            **payoutData** - Information related to the payout details, such as fee responsibility and source currency.


            **cryptoWalletData** - Information required for processing a payout via cryptocurrency wallet.
          enum:
            - personalData
            - addressData
            - billingAddressData
            - shippingAddressData
            - documentData
            - cardData
            - walletData
            - bankTransferData
            - payoutData
            - cryptoWalletData
        validation:
          type: object
          description: "Object containing validation information for the value passed for the `key` parameter during a payout request."
          required:
            - type
            - required
          properties:
            pattern:
              type: string
              example: ^.{1-50}$
              nullable: true
              description: "Validation requirements for the value passed for the `key` parameter during a payout request, provided in regex format."
            minLenght:
              type: integer
              nullable: true
              description: "Minimum length requirement for the value passed for the `key` parameter."
              example: 1
            maxLenght:
              type: integer
              nullable: true
              description: "Maximum length requirement for the value passed for the `key` parameter."
              example: 50
            type:
              type: string
              example: text
              description: |
                The field type for the `key` value, which can be displayed on the front end for the user.

                **date** - date in ISO 8601 format, e.g., YYYY-MM-DD

                **text** - text field

                **email** - email field

                **tel** - phone number field

                **select** - dropdown list with a single selection

                **number** - number field

                **isMultiple** - dropdown list with multiple selections

                **checkbox** - checkbox selection
              enum:
                - date
                - text
                - email
                - tel
                - select
                - number
                - isMultiple
                - checkbox
            required:
              type: boolean
              description: "Indicates whether the `key` and its value are mandatory for initiating a payout."
              example: true
        options:
          type: array
          nullable: true
          description: |
            Array of objects containing information about acceptable values. The `key` should be passed with one of the acceptable values to initiate a payout.

            If this array contains elements, you must choose one of these values and cannot pass a custom value.
          items:
            type: object
            required:
              - value
              - label
            properties:
              value:
                type: string
                nullable: true
                example: C
                description: "Acceptable value"
              label:
                type: string
                nullable: true
                description: "Human-readable text description of the value."
                example: Checking account
    PayoutMethodResponse:
      title: Payout Method Details
      description: Details of a payout method available to the shop.
      required:
        - providerCode
        - instrumentType
        - isDefault
        - dataEntryModes
        - currencies
        - regions
        - acquirerCode
        - allowedCards
      properties:
        providerCode:
          description: Determines which payout provider should be used to process the payout.
          type: string
          example: connectpay
        acquirerCode:
          description: "Identifies the specific acquirer responsible for processing payments."
          type: string
          example: Gcash
        instrumentType:
          description: Specifies the instrument type for the payout.
          type: string
          enum:
            - card
            - bank_transfer
            - wallet
            - crypto_wallet
            - voucher
            - cash
            - apple_pay
            - google_pay
          example: wallet
        entryMode:
          type: string
          description: "This field specifies the method by which payment data is entered and should only be used when `instrumentType` == `card`. [Payment Entry Modes for instrument type card](/docs/merchant/instrument-type#payment-entry-modes-for-payment-instrument-card)"
          example: null
          enum:
            - cnp
            - card_present
            - moto
            - recurring
            - saved_card
            - redirect
            - apple_pay
            - google_pay
          nullable: true
        dataEntryModes:
          description: |
            Methods for data entry to process payout:

            **redirect** - the entity making the payout enters payment information on the provider's (acquirer's) page via redirect;

            **h2h (host2host)** - the entity making the payout enters payment information via our API;

            **qr** - the entity making the payout scans a QR code and enters information on the aggregator's side.
          type: array
          items:
            type: string
            enum:
              - redirect
              - h2h
              - qr
        allowedCards:
          description: "Applicable only for `instrumentType` == `card`. Specifies the credit or debit card brands that can be used with this payout method."
          type: array
          items:
            type: string
          example: ["visa"]
        transferType:
          description: |
            **Deprecated:** This field is deprecated and will be removed in future releases.

            Applicable only for `instrumentType` == `bank_transfer`. Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type)

            It is retained for backward compatibility. Use `transferTypes` instead.
            If a payment method supports only one transfer type, it will be returned here.
            If multiple transfer types are available, this field will be `null`, and you should use `transferTypes`.
          type: string
          enum:
            - swift
            - sepa
            - bank_wire
            - card2card
            - pix
            - sbp
            - online_banking
            - open_finance
            - virtual_account
            - qris
            - promptpay
            - thaiqr
            - spei
            - vietnambanksqr
            - vietqr
            - khipu
            - paysafecard
            - multibanco
            - bancontact
            - blik
            - p24
            - rapidtransfer
            - thb_qr
            - upi
            - upi_intent
            - sberbank
            - giropay
            - eps
            - account2card
            - fpx
            - trustly
            - wise
            - n26
            - pesalink
            - imps
            - upi_p2p
            - upi_fast_vip
            - mybank
            - tink
            - bizum
            - sofort
            - p2p
            - easypay
            - klarna
            - clabe
            - codi
            - rapipago
            - pse
          example: bank_wire
          nullable: true
        transferTypes:
          description: |
            An array of available bank transfer types for the specified payment method.
            Applicable only for `instrumentType` == `bank_transfer`. Specifies the type of bank transfer. See details about [transferType](/docs/merchant/instrument-type)
          type: array
          items:
            type: string
            enum:
              - swift
              - sepa
              - bank_wire
              - card2card
              - pix
              - sbp
              - online_banking
              - open_finance
              - virtual_account
              - qris
              - promptpay
              - thaiqr
              - spei
              - vietnambanksqr
              - vietqr
              - khipu
              - paysafecard
              - multibanco
              - bancontact
              - blik
              - p24
              - rapidtransfer
              - thb_qr
              - upi
              - upi_intent
              - sberbank
              - giropay
              - eps
              - account2card
              - fpx
              - trustly
              - wise
              - n26
              - pesalink
              - imps
              - upi_p2p
              - upi_fast_vip
              - mybank
              - tink
              - bizum
              - sofort
              - p2p
              - easypay
              - klarna
              - clabe
              - codi
              - rapipago
              - pse
          example: bank_wire
          nullable: true
        currencies:
          description: |
            A list of currency codes supported by this payout instrument.

            For fiat currencies, use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.

            For cryptocurrencies, a specific format is used; a full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies)."
          example: ["PHP"]
          type: array
          items:
            type: string
        regions:
          type: array
          description: A list of regions where this payout method is available. Each region will be specified by its ISO 3166-1 alpha-2 code
          items:
            type: string
            pattern: "^[A-Z]{2}$"
          example: ["PH"]
        isDefault:
          description: "This parameter is currently not in use and can be ignored. Specifies whether this payout method is set as the default for this shop. When creating an payout ([Create Order](/docs/merchant-api/create-order)), if the `paymentSettings` object is not explicitly provided, the payment will be processed using this default payment method."
          example: false
          type: boolean
        paymentSettingsAlias:
          description: |
            A unique identifier assigned to a specific payout configuration. Use this alias when creating orders to ensure the correct payout settings are applied. This field is optional and will be provided in the response only if the payout method has been configured with an alias.

            For more detailed information about how to use aliases, refer to the [Alias Documentation](/docs/merchant/alias)
          example: "testAlias"
          nullable: true
          type: string
      type: object

    payout.cancelPayoutRequest:
      required:
        - payoutNumber
        - shopId
      type: object
      properties:
        payoutNumber:
          type: string
          description: "Unique code identifying the specific payout."
          example: "PAYOUT-123456"
        shopId:
          type: integer
          description: "Unique identifier for the shop where the payout is being placed."
          example: "1234"

    payout.cancelOperationResponse:
      required:
        - operationType
        - payoutNumber
      type: object
      properties:
        payoutNumber:
          type: string
          description: "Unique code identifying the specific payout."
          example: "PAYOUT-123456"
        operationType:
          type: string
          description: "Operations type"
          example: "cancel"
          enum:
            - cancel
    payout.rejectPayoutRequest:
      required:
        - payoutNumber
        - shopId
      type: object
      properties:
        payoutNumber:
          type: string
          description: "Unique code identifying the specific payout."
          example: "PAYOUT-123456"
        shopId:
          type: integer
          description: "Unique identifier for the shop where the payout is being placed."
          example: "1234"
    payout.rejectOperationResponse:
      required:
        - operationType
        - payoutNumber
      type: object
      properties:
        payoutNumber:
          type: string
          description: "Unique code identifying the specific payout."
          example: "PAYOUT-123456"
        operationType:
          type: string
          description: "Operations type"
          example: "reject"
          enum:
            - reject
    callbackPayout:
      type: object
      required:
        - data
      properties:
        data:
          $ref: "#/components/schemas/payout.status"
    createCustomerRequest:
      type: object
      required:
        - customer
      properties:
        shopId:
          type: string
          description: |
            The unique identifier of the shop within the merchant company. If not provided, the customer will be unique across the entire company. If provided, the customer will be unique within this shop.
          nullable: true
          example: "456"
        customer:
          type: object
          required:
            - firstName
            - lastName
            - email
            - saveCard
          properties:
            customerId:
              type: string
              description: |
                The identifier of the customer within the merchant's system. Must be unique within the company or shop.
              nullable: true
              example: "cust789"
            firstName:
              type: string
              description: "The customer's first name."
              example: "John"
            lastName:
              type: string
              description: "The customer's last name."
              example: "Doe"
            middleName:
              type: string
              description: "The customer's middle name, if applicable."
              nullable: true
              example: "A"
            phone:
              type: string
              description: "The customer's phone number ."
              nullable: true
              example: "+1234567890"
            email:
              type: string
              description: "The customer's email address."
              example: "john.doe@example.com"
            birthDate:
              type: string
              description: "The customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
              nullable: true
              example: 1990-12-30
            saveCard:
              type: boolean
              description: "Whether to save the card details for the customer."
              example: true
            metaData:
              type: object
              description: Customer metadata
              nullable: true
              properties:
                affiliatedId:
                  maxLength: 255
                  type: string
                  nullable: true
                  description: |
                    An optional identifier provided by the merchant to facilitate custom payment routing. 
                    This field allows you to pass any arbitrary value, which will be stored in the customer's record.
                  example: "afl_4848301"
            details:
              type: object
              description: Customer details
              nullable: true
              properties:
                addressData:
                  type: object
                  description: Customer address data
                  nullable: true
                  properties:
                    city:
                      description: City name
                      maxLength: 255
                      type: string
                      example: Beverly Hills
                      nullable: true
                    countryCode:
                      description: ISO 3166-1 alpha-2 country code
                      type: string
                      maxLength: 2
                      minLength: 2
                      example: US
                    state:
                      description: State or province name
                      type: string
                      maxLength: 255
                      example: California
                      nullable: true
                    zipCode:
                      description: Postal code
                      maxLength: 10
                      type: string
                      example: "90210"
                      nullable: true
                    address:
                      description: "Full street address of the customer"
                      type: string
                      nullable: true
                      example: 42, Sunset Blvd.
    createCustomerResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - customerId
            - firstName
            - lastName
            - email
          properties:
            customerId:
              type: string
              description: "The unique identifier of the customer."
              example: "cust789"
            firstName:
              type: string
              description: "The first name of the customer."
              example: "John"
            lastName:
              type: string
              description: "The last name of the customer."
              example: "Doe"
            middleName:
              type: string
              description: "The middle name of the customer, if provided."
              nullable: true
              example: "A"
            phone:
              type: string
              description: "The customer's phone number, if provided."
              nullable: true
              example: "+1234567890"
            email:
              type: string
              description: "The customer's email address."
              example: "john.doe@example.com"
            birthDate:
              type: string
              description: "The customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
              nullable: true
              example: 1990-12-30
            affiliatedId:
              maxLength: 255
              type: string
              nullable: true
              description: |
                An optional identifier provided by the merchant to facilitate custom payment routing. 
                This field allows you to pass any arbitrary value, which will be stored in the customer's record.
              example: "afl_4848301"
            billingAddress:
              type: object
              nullable: true
              description: "The billing address for the customer"
              properties:
                addressType:
                  type: string
                  nullable: true
                  description: "Type of the address. billing - billing address, shipping - shipping address"
                  enum:
                    - billing
                    - shipping
                address:
                  nullable: true
                  type: string
                  description: "Address line."
                  example: "7, Sunny street"
                region:
                  type: string
                  nullable: true
                  description: "Region of the billing address."
                  example: "Limassol"
                city:
                  type: string
                  nullable: true
                  description: "City of the billing address."
                  example: "Limassol"
                country:
                  type: string
                  nullable: true
                  description: "Country code in ISO 3166-1 alpha-2 format."
                  example: "CY"
                zipCode:
                  type: string
                  nullable: true
                  description: "Postal code."
                  example: "4141"
                state:
                  type: string
                  nullable: true
                  description: "State or region."
                  example: "CA"
    CustomerListResponse:
      title: V1-Customer-Response-CustomerListResponse
      type: object
      required:
        - customers
      properties:
        customers:
          description: "List of customer information."
          type: array
          items:
            $ref: "#/components/schemas/CustomerResponse"
        shopId:
          description: "Shop identifier. If this is null instead of a shop ID, it means the customer is associated with the company rather than a specific shop."
          type: string
          nullable: true
          example: "456"
    CustomerResponse:
      type: object
      required:
        - customerId
        - firstName
        - lastName
        - email
      properties:
        customerId:
          description: "The unique identifier of the customer provided by the merchant's system."
          type: string
          example: "cust789"
        firstName:
          description: "The first name of the customer."
          type: string
          example: "John"
        lastName:
          description: "The last name of the customer."
          type: string
          example: "Doe"
        middleName:
          description: "The middle name of the customer, if provided."
          type: string
          nullable: true
          example: "A"
        phone:
          description: "The customer's phone number."
          type: string
          nullable: true
          example: "+1234567890"
        email:
          description: "The customer's email address."
          type: string
          example: "john.doe@example.com"
        birthDate:
          description: "Customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          type: string
          example: 1990-12-30
          nullable: true
        affiliatedId:
          maxLength: 255
          type: string
          nullable: true
          description: |
            An optional identifier provided by the merchant to facilitate custom payment routing. 
            This field allows you to pass any arbitrary value, which will be stored in the customer's record.
          example: "afl_4848301"
        billingAddress:
          type: object
          nullable: true
          description: "The billing address for the customer"
          properties:
            addressType:
              type: string
              nullable: true
              description: "Type of the address. billing - billing address, shipping - shipping address"
              enum:
                - billing
                - shipping
            address:
              nullable: true
              type: string
              description: "Address line."
              example: "7, Sunny street"
            region:
              type: string
              nullable: true
              description: "Region of the billing address."
              example: "Limassol"
            city:
              type: string
              nullable: true
              description: "City of the billing address."
              example: "Limassol"
            country:
              type: string
              nullable: true
              description: "Country code in ISO 3166-1 alpha-2 format."
              example: "CY"
            zipCode:
              type: string
              nullable: true
              description: "Postal code."
              example: "4141"
            state:
              type: string
              nullable: true
              description: "State or region."
              example: "CA"

    V1CryptoWalletRequestCreateCustomerCryptoWalletRequest:
      title: V1-CryptoWallet-Request-CreateCustomerCryptoWalletRequest
      type: object
      required:
        - shopId
        - customerId
        - providerCode
        - cryptoCurrency
      properties:
        shopId:
          type: string
          example: "1234"
          description: |
            The identifier of the shop where the wallet for the customer will be created.
        customerId:
          type: string
          description: |
            The unique identifier of the customer for whom the wallet is being created.
            This customer must already exist in the system. If the customer has not been created yet, use the [Create New Customer](/docs/merchant-api/create-new-customer) endpoint.
          example: "56656"
        providerCode:
          type: string
          description: |
            The code of the crypto provider that will manage this wallet.
          example: "crypto2b"
        cryptoCurrency:
          type: string
          description: |
            The cryptocurrency to be used for this wallet (e.g., BTC, ETH, USDT).
          example: "USDT"
        tokenStandard:
          type: string
          nullable: true
          example: "TRC20"
          description: |
            The standard of the cryptocurrency token.

            This field is required for tokens (such as USDT) and not required for native cryptocurrencies (BTC, ETH, SOL, TRX, LTC).

            A full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies).
        webhookUrl:
          type: string
          nullable: true
          description: |
            A callback URL for receiving notifications about wallet activity (deposits).
          example: "https://example.com"
        accountCurrency:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/V1CryptoWalletDtoAccountCurrency"
    V1CryptoWalletDtoAccountCurrency:
      required:
        - currency
      properties:
        currency:
          description: |
            The merchant account currency.
            This can be either a fiat currency
            (e.g. "USD", "EUR"; ISO 4217 alphabetic code format, consisting of 3 uppercase letters) or a cryptocurrency (e.g. "BTC", "ETH").
            Some providers require specifying an account currency in addition to
            the actual cryptocurrency for the wallet. In those cases, use this
            field to indicate in which currency the merchant's account 
            will be denominated.
          type: string
          example: USDT
        networkTokenStandard:
          description: |
            The token standard applicable to the merchant account currency, if any.
            Used for certain cryptocurrencies (e.g. "ERC-20" for tokens
            on the Ethereum network). If you're using a fiat currency (such as "USD"
            or "EUR"), or a cryptocurrency without a distinct token standard,
            leave this as null or omit it entirely.
          type: string
          example: ERC-20
          nullable: true
      type: object
    V1CryptoWalletResponseCreateCustomerCryptoWalletResponse:
      title: V1-CryptoWallet-Response-CreateCustomerCryptoWalletResponse
      type: object
      required:
        - providerCode
        - customerId
        - shopId
        - walletAddress
      properties:
        providerCode:
          type: string
          description: |
            The crypto provider managing this newly created wallet.
          example: "crypto2b"
        customerId:
          type: string
          description: |
            The unique identifier of the customer who owns this wallet.
          example: "56656"
        shopId:
          type: string
          description: |
            The shop ID associated with this wallet.
          example: "1234"
        walletAddress:
          type: string
          description: |
            The address of the created cryptocurrency wallet. Customers can deposit
            funds to this address.
          example: "TTnWEKycig1hmD3FZNnTR2mCpkF7g9DuSo"
    V1CryptoWalletResponseGetCustomerCryptoWalletsResponse:
      title: V1-CryptoWallet-Response-GetCustomerCryptoWalletsResponse
      type: object
      required:
        - shopId
        - customerId
        - cryptoWallets
      properties:
        shopId:
          type: string
          description: |
            The shop identifier where these crypto wallets are registered.
          example: "1234"
        customerId:
          type: string
          description: |
            The unique identifier of the customer who owns these wallets.
          example: "56656"
        cryptoWallets:
          type: array
          description: |
            A list of crypto wallet objects for the specified customer.
          items:
            $ref: "#/components/schemas/V1CryptoWalletResponseCryptoWalletResponse"

    V1CryptoWalletResponseCryptoWalletResponse:
      title: V1-CryptoWallet-Response-CryptoWalletResponse
      type: object
      required:
        - providerCode
        - walletAddress
        - cryptoCurrency
      properties:
        providerCode:
          type: string
          description: |
            The code of the crypto provider that manages this wallet.
          example: "crypto2b"
        wallet:
          type: string
          description: |
            The wallet address where customers can deposit the specified cryptocurrency.
          example: "TTnWEKycig1hmD3FZNnTR2mCpkF7g9DuSo"
        currency:
          type: string
          description: |
            The cryptocurrency code used by this wallet (e.g., BTC, ETH, or USDT).
          example: "USDT"
        tokenStandard:
          type: string
          nullable: true
          example: "TRC20"
          description: |
            The standard of the cryptocurrency token.

            This field is required for tokens (such as USDT) and not required for native cryptocurrencies (BTC, ETH, SOL, TRX, LTC).

            A full list of supported cryptocurrencies is available [here](/docs/merchant/crypto#supported-currencies).
        accountCurrency:
          type: string
          nullable: true
          description: |
            The account currency specified when creating this crypto wallet.
            This can be a fiat currency (e.g., "USD", "EUR") or a cryptocurrency
            (e.g., "BTC", "ETH", "USDT"). Some providers require an account currency
            in addition to the wallet's cryptocurrency for settlement or balance
            denominating.
          example: USDT
        accountCurrencyTokenStandard:
          type: string
          nullable: true
          example: ERC-20
          description: |
            The token standard for the account currency, if it is a token (e.g., "ERC-20", "TRC20").
            If the account currency is a fiat currency or a native cryptocurrency
            without a specific token standard, this field will be null.
    recurringDetails:
      type: object
      required:
        - id
        - orderNumber
        - status
        - amount
        - currency
        - schedule
        - createdAt
      properties:
        id:
          type: string
          description: "A unique identifier for this recurring subscription."
          example: "sub_54222"
        orderNumber:
          type: string
          description: "The order number associated with this recurring subscription."
          example: "ORDER-324234"
        status:
          type: string
          enum: [active, canceled, failed, completed]
          description: |

            The current status of this subscription:

            - **active**: The subscription is currently active and recurring charges can occur.

            - **canceled**: The subscription has been canceled; no further charges will be made.

            - **failed**: The subscription encountered an issue.

            - **completed**: The subscription has concluded because it reached its defined end (all payments completed or the end date was reached).
          example: "active"
        customerId:
          type: string
          description: "The unique ID of the customer linked to this subscription."
          example: "cust789"
        amount:
          type: string
          nullable: true
          description: "The amount charged for each recurring payment."
          example: "56.99"
        currency:
          type: string
          nullable: true
          description: "The currency used for each recurring payment, in ISO 4217 format."
          example: "USD"
        nextChargeDate:
          type: string
          nullable: true
          description: "The date and time of the next scheduled charge (if any)."
          example: "2024-01-01T09:00:00Z"
        schedule:
          type: object
          required:
            - billingIntervalQuantity
            - intervalType
          properties:
            billingIntervalQuantity:
              type: integer
              description: "Number of interval units between recurring charges."
              example: 1
            intervalType:
              type: string
              enum: [day, week, month, year]
              description: "Defines the unit of measure for the billing interval."
              example: "month"
            endDate:
              type: string
              description: "The date after which no more recurring charges will be performed, in YYYY-MM-DD format."
              example: "2024-12-01T00:00:00Z"
            paymentCount:
              type: integer
              description: "The total number of payments to be made before ending the subscription."
              example: 3
            paymentsCompleted:
              type: integer
              nullable: true
              description: "Number of successfully completed payments for this subscription."
              example: 1
        createdAt:
          type: string
          description: "The date and time when this subscription was initially created."
          example: "2023-09-01T10:00:00Z"
    V1OrderResponseOrderChargebacksResponse:
      title: V1-Order-Response-OrderChargebacksResponse
      description: Response containing list of orders with chargebacks for a shop.
      required:
        - shopId
        - orders
      properties:
        shopId:
          description: Shop identifier.
          type: integer
          example: 123
        orders:
          description: List of orders with chargebacks.
          type: array
          items:
            $ref: "#/components/schemas/V1OrderResponseOrderWithChargebacksResponse"
      type: object
    V1OrderResponseOrderWithChargebacksResponse:
      title: V1-Order-Response-OrderWithChargebacksResponse
      description: Order information with its chargeback payments.
      required:
        - orderNumber
        - payments
      properties:
        orderNumber:
          description: Order number.
          type: string
          example: "12345"
        payments:
          description: List of payments with chargebacks.
          type: array
          items:
            $ref: "#/components/schemas/V1OrderResponsePaymentDetailsWithChargebacksResponse"
      type: object
    V1OrderResponsePaymentDetailsWithChargebacksResponse:
      title: V1-Order-Response-PaymentDetailsWithChargebacksResponse
      description: Payment details with chargeback information.
      required:
        - paymentId
        - status
        - chargebackDetails
      properties:
        paymentId:
          description: Payment identifier.
          type: integer
          example: "12345"
        cost:
          description: Cost of the payment.
          nullable: true
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "Amount of the payment."
              example: "100.00"
            currency:
              type: string
              description: "Currency of the payment."
              example: "USD"
        status:
          $ref: "#/components/schemas/ProcessingEnumPaymentPaymentStatus"
        chargebackDetails:
          type: array
          items:
            $ref: "#/components/schemas/V1OrderResponseOrderPaymentChargebackDetailsResponse"
      type: object
    ProcessingEnumPaymentPaymentStatus:
      title: " "
      type: string
      enum:
        - in_progress
        - completed
        - cancelled
        - failed
        - need_action
        - authorized
        - overwrite
        - review
    ProcessingEnumPaymentChargebackStatus:
      title: Apic-Contracts-Processing-Enum-Payment-ChargebackStatus
      type: string
      enum:
        - open
        - open_undefined
        - approved
        - closed
    V1ThreeDsRequestProcessVerificationRequest:
      title: V1-ThreeDs-Request-ProcessVerificationRequest
      description: |
        Request object for submitting 3-D Secure (3DS) verification results.
      required:
        - status
        - acsFullResponse
      properties:
        status:
          $ref: "#/components/schemas/ProcessingEnumThreeDsVerificationResultStatus"
        acsFullResponse:
          type: string
          description: |
            The complete ACS (Access Control Server) response received from the payment provider after 3DS authentication.
          example: "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjEyMzQ1Njc4OTAtMTIzNC0xMjM0LTEyMzQtMTIzNDU2Nzg5MCIsImF1dGhlbnRpY2F0aW9uVmFsdWUiOiJZIn0="
        merchantId:
          type: string
          description: |
            Optional merchant identifier. This field is used to identify the specific merchant account when processing the 3DS verification result.
          maxLength: 16
          minLength: 1
          nullable: true
          example: "1234567890123456"
      type: object
    ProcessingEnumThreeDsVerificationResultStatus:
      title: " "
      description: |
        The result status of a 3-D Secure (3DS) verification process. This status indicates the outcome of the customer's authentication attempt during the 3DS flow.

        **ok** - The 3DS authentication was successful. The customer has been successfully authenticated and the payment can proceed.

        **fail** - The 3DS authentication failed. The customer's authentication attempt was unsuccessful, and the payment should be declined.

        **timeout** - The 3DS authentication process timed out. The customer did not complete the authentication within the allowed time period.
      type: string
      enum:
        - ok
        - fail
        - timeout
      example: "ok"
    CreateP2PRequest:
      type: object
      required:
        - shopId
        - p2p
        - p2pSettings
        - providerCode
        - recipient
        - sender
      description: "Request body to create a new P2P transaction."
      properties:
        shopId:
          type: integer
          description: "Unique identifier of the shop performing the transaction."
          example: 1001
        p2p:
          $ref: "#/components/schemas/P2PTransactionData"
        purpose:
          type: string
          description: "Purpose or reason for the payment."
          maxLength: 128
          nullable: true
          example: "Payment for invoice #1234"
        providerCode:
          type: string
          description: "Code of the provider handling the P2P transfer."
          example: "connectpay"
        webhookUrl:
          type: string
          nullable: true
          format: uri
          description: >
            An optional webhook URL to receive status updates for this P2P transaction.
            If provided, this URL will be used instead of the default webhook for the shop.
          example: "https://example.com/webhook"
        customer:
          $ref: "#/components/schemas/P2PCustomer"
        recipient:
          $ref: "#/components/schemas/P2PRecipient"
        sender:
          $ref: "#/components/schemas/P2PSender"
        paymentPageDesign:
          $ref: "#/components/schemas/PaymentPageDesign"
        browser:
          type: object
          nullable: true
          description: "Contains browser and device details from the payer."
          properties:
            ipAddress:
              type: string
              nullable: true
              description: "Payer's IP address."
              example: "1.2.3.4"
            acceptHeader:
              type: string
              nullable: true
              description: "The Accept header from the payer's browser."
              example: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8"
            colorDepth:
              type: number
              nullable: true
              description: "Screen color depth in bits."
              example: 24
            javaEnabled:
              type: boolean
              nullable: true
              description: "Indicates whether Java is enabled in the browser."
              example: false
            javascriptEnabled:
              type: boolean
              nullable: true
              description: "Indicates whether JavaScript is enabled in the browser."
              example: true
            acceptLanguage:
              type: string
              nullable: true
              description: "The Accept-Language header from the browser."
              example: "en-GB"
            screenWidth:
              type: number
              nullable: true
              description: "Screen width in pixels."
              example: 412
            screenHeight:
              type: number
              nullable: true
              description: "Screen height in pixels."
              example: 846
            timeZone:
              type: number
              nullable: true
              description: "Time zone offset from UTC in hours."
              example: 0
            userAgent:
              type: string
              nullable: true
              description: "The User-Agent string from the payer's browser."
              example: "Mozilla/5.0 (Linux; Android 10; SM-G965F Build/QP1A.190711.020; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/106.0.5249.126 Mobile Safari/537.36"

    P2PTransactionData:
      type: object
      required:
        - cost
        - p2pNumber
      properties:
        cost:
          $ref: "#/components/schemas/P2PCost"
        p2pNumber:
          type: string
          description: >
            A unique identifier for the p2p transaction that you must generate on your side. The `p2pNumber` should be specific to the `shopId` or your company (depending on your company's settings).
            The `p2pNumber` may contain only Latin letters (uppercase and lowercase), numbers, and hyphens. Hyphens cannot be at the beginning or end of the string.
          example: "P2P-ABC-123456"
        localDateTime:
          type: string
          nullable: true
          description: >
            Represents the local date and time of the transaction including timezone information in ISO 8601 format. 
                This information is used for proper processing. If this value is not provided, the system's current time will be used.
          example: "2023-03-06T14:15:23+00:00"
        description:
          type: string
          maxLength: 128
          nullable: true
          description: |
            Optional text providing additional context for the P2P transaction. This field can be used to store an internal reference, note, or any information that helps identify or describe the transaction.
          example: "Internal reference #P2P-2024-001"
        region:
          type: string
          nullable: true
          description: |
            For some providers, it is mandatory to specify the region where the P2P transaction is being processed. The region should be specified using the ISO 3166-1 alpha-2 country code format (e.g., "US" for United States, "PH" for Philippines).
          example: "PH"
    P2PCost:
      type: object
      required:
        - amount
        - currency
      description: "Details of the transfer amount and currency."
      properties:
        amount:
          type: string
          description: >
            Represents the total amount for this transaction in a decimal string format. Follow ISO 4217 decimal precision standards.
          example: "100.50"
        currency:
          type: string
          description: >
            Specifies the currency.
            Use the ISO 4217 alphabetic code format, consisting of 3 uppercase letters.
          example: "USD"
    P2PCustomer:
      type: object
      nullable: true
      description: "Information about the customer initiating the transaction."
      properties:
        customerId:
          type: string
          description: "External customer ID in the merchant's system, if available."
          example: "cust789"
          nullable: true
        firstName:
          type: string
          description: "Customer's first name."
          example: "John"
          nullable: true
        lastName:
          type: string
          description: "Customer's last name."
          example: "Doe"
          nullable: true
        middleName:
          type: string
          description: "Customer's middle name, if applicable."
          nullable: true
          example: "James"
        phone:
          type: string
          description: "Customer's phone number."
          nullable: true
          example: "+1234567890"
        email:
          type: string
          format: email
          description: "Customer's email address."
          example: "john.doe@example.com"
          nullable: true
        details:
          type: object
          description: Customer details
          nullable: true
          properties:
            addressData:
              type: object
              description: Customer address data
              nullable: true
              properties:
                city:
                  description: City name
                  maxLength: 255
                  type: string
                  example: Beverly Hills
                  nullable: true
                countryCode:
                  description: ISO 3166-1 alpha-2 country code
                  type: string
                  maxLength: 2
                  minLength: 2
                  example: US
                state:
                  description: State or province name
                  type: string
                  maxLength: 255
                  example: California
                  nullable: true
                zipCode:
                  description: Postal code
                  maxLength: 10
                  type: string
                  example: "90210"
                  nullable: true
                address:
                  description: "Full street address of the customer"
                  type: string
                  nullable: true
                  example: "42, Sunset Blvd."
        metaData:
          type: object
          description: "Additional metadata about the customer."
          properties:
            affiliatedId:
              type: string
              nullable: true
              description: "An optional identifier provided by the merchant to facilitate custom payment routing. This field allows you to pass any arbitrary value, which will be stored in the customer's record."
              example: "afl_4848301"
          nullable: true
        birthDate:
          description: "Customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          type: string
          example: 1990-12-30
          nullable: true
    P2PRecipient:
      type: object
      required:
        - personalData
        - addressData
      description: "Information about the recipient who will receive the funds."
      properties:
        personalData:
          $ref: "#/components/schemas/P2PRecipientPersonalData"
        addressData:
          $ref: "#/components/schemas/P2PRecipientAddressData"
        cardData:
          $ref: "#/components/schemas/P2PRecipientCardData"
        walletData:
          $ref: "#/components/schemas/P2PRecipientWalletData"
        bankData:
          $ref: "#/components/schemas/P2PRecipientBankData"

    P2PRecipientPersonalData:
      type: object
      required:
        - firstName
        - lastName
      description: "Recipient's personal details such as name."
      properties:
        firstName:
          type: string
          description: "Recipient's first name."
          example: "Alice"
        lastName:
          type: string
          description: "Recipient's last name."
          example: "Brown"
        phone:
          type: string
          nullable: true
          description: "Recipient's phone number."
          example: "+1234567890"
        email:
          type: string
          nullable: true
          description: "Recipient's email address."
        birthDate:
          description: "Recipient's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          type: string
          example: 1990-12-30
          nullable: true
    P2PRecipientAddressData:
      type: object
      required:
        - countryCode
        - street
      description: "Address details for the recipient."
      properties:
        countryCode:
          type: string
          description: "ISO 3166-1 alpha-2 code of the recipient's country."
          example: "US"
        state:
          type: string
          nullable: true
          description: "State (relevant for US/CA)."
          example: "NY"
        street:
          type: string
          description: "Street portion of the address."
          example: "456 Liberty Ave."

    P2PRecipientCardData:
      type: object
      description: "Card information if the recipient is receiving funds to a card."
      required:
        - cardNumber
      properties:
        cardNumber:
          type: string
          description: "Recipient's card number."
          example: "4111111111111111"

    P2PRecipientWalletData:
      type: object
      required:
        - walletId
      description: "Recipient's wallet information if using a digital wallet."
      properties:
        walletId:
          type: string
          description: "The wallet identifier for the recipient."
          example: "wallet-12345"
    P2PRecipientBankData:
      description: |
        Bank account information if the recipient is receiving funds 
        to a bank account. Exactly **one** of the following sets of fields 
        must be provided to determine the bank details:
        - **Routing number + Bank account number (BAN)**
        - **IBAN**
        - **Bank Identification Code (BIC) + Bank account number (BAN)**
      oneOf:
        - type: object
          title: "Routing number + BAN"
          description: "Routing number + Bank account number (BAN)"
          required:
            - accountNumber
            - routingNumber
          properties:
            accountNumber:
              type: string
              description: "Recipient's bank account number."
              example: "9876543210"
            routingNumber:
              type: string
              description: "Routing number for the recipient's bank."
              example: "021000021"
        - type: object
          title: "IBAN"
          description: "IBAN"
          required:
            - iban
          properties:
            iban:
              type: string
              description: "International Bank Account Number."
              example: "DE89370400440532013000"
        - type: object
          title: "BIC + BAN"
          description: "Bank account number (BAN) + Bank Identification Code (BIC)"
          required:
            - accountNumber
            - bankBic
          properties:
            accountNumber:
              type: string
              description: "Recipient's bank account number."
              example: "9876543210"
            bankBic:
              type: string
              description: "Bank BIC (Bank Identifier Code)."
              example: "BBANKUS44XXX"
    P2PSender:
      type: object
      required:
        - personalData
        - addressData
      description: "Information about the sender who is sending the funds."
      properties:
        personalData:
          $ref: "#/components/schemas/P2PSenderPersonalData"
        addressData:
          $ref: "#/components/schemas/P2PSenderAddressData"
        cardData:
          $ref: "#/components/schemas/P2PSenderCardData"
        walletData:
          $ref: "#/components/schemas/P2PSenderWalletData"
        bankData:
          $ref: "#/components/schemas/P2PSenderBankData"

    P2PSenderPersonalData:
      type: object
      required:
        - firstName
        - lastName
      description: "Sender's personal details such as name."
      properties:
        firstName:
          type: string
          description: "Sender's first name."
          example: "Bob"
        lastName:
          type: string
          description: "Sender's last name."
          example: "Green"
        phone:
          type: string
          nullable: true
          description: "Sender's phone number."
          example: "+1234567890"
        email:
          type: string
          nullable: true
          description: "Sender's email address."
        birthDate:
          description: "Sender's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          type: string
          example: 1990-12-30
          nullable: true
    P2PSenderAddressData:
      type: object
      required:
        - countryCode
        - street
      description: "Address details for the sender."
      properties:
        countryCode:
          type: string
          description: "ISO 3166-1 alpha-2 code of the sender's country."
          example: "US"
        state:
          type: string
          nullable: true
          description: "State (relevant for US/CA)."
          example: "CA"
        street:
          type: string
          description: "Street portion of the address."
          example: "123 Apple St."

    P2PSenderCardData:
      type: object
      required:
        - cardNumber
        - cardHolderName
        - expireMonth
        - expireYear
        - cvv
      description: "Card details if the sender is paying from a card."
      properties:
        cardNumber:
          type: string
          description: "Sender's card number."
          example: "4111111111111111"
        cardHolderName:
          type: string
          description: "Name on the sender's card."
          example: "JOHN A DOE"
        expireMonth:
          type: string
          description: "Card's expiration month (MM)."
          example: "12"
        expireYear:
          type: string
          description: "Card's expiration year (YYYY)."
          example: "2024"
        cvv:
          type: string
          description: "Card security code (3-4 digits)."
          example: "123"

    P2PSenderWalletData:
      type: object
      required:
        - walletId
      description: "Sender's wallet information if using a digital wallet."
      properties:
        walletId:
          type: string
          description: "The wallet identifier for the sender."
          example: "wallet-98765"
    P2PSenderBankData:
      description: |
        Bank account information if the sender is sending funds from a bank account. 
        Exactly **one** of the following sets of fields must be provided to determine the bank details:
        - **Routing number + Bank account number (BAN)**
        - **IBAN**
        - **Bank Identification Code (BIC) + Bank account number (BAN)**
      oneOf:
        - type: object
          title: "Routing number + BAN"
          description: "Routing number + Bank account number (BAN)"
          required:
            - accountNumber
            - routingNumber
          properties:
            accountNumber:
              type: string
              description: "Sender's bank account number."
              example: "9876543210"
            routingNumber:
              type: string
              description: "Routing number for the sender's bank."
              example: "021000021"

        - type: object
          title: "IBAN"
          description: "IBAN"
          required:
            - iban
          properties:
            iban:
              type: string
              description: "International Bank Account Number."
              example: "DE89370400440532013000"

        - type: object
          title: "BIC + BAN"
          description: "Bank Identification Code (BIC) + Bank account number (BAN)"
          required:
            - accountNumber
            - bankBic
          properties:
            accountNumber:
              type: string
              description: "Sender's bank account number."
              example: "9876543210"
            bankBic:
              type: string
              description: "Bank BIC (Bank Identifier Code)."
              example: "BBANKUS44XXX"
    PaymentPageDesign:
      type: object
      description: "Optional settings for customizing the payment page experience."
      properties:
        alias:
          type: string
          nullable: true
          description: "Payment page style or alias."
          example: "default"
        format:
          type: string
          nullable: true
          description: |
            Specifies how the payment form is presented to the user:
            - **[redirect](/docs/merchant/gateway_aggregator/orders/payment-page-options/payment-gate-hosted)**: The customer is redirected to our hosted payment page.
            - **[iframe](/docs/merchant/gateway_aggregator/orders/payment-page-options/merchant-hosted#iframe)**: The payment form is embedded directly within your website for a seamless user experience without leaving your site.
            - **[shop_hosted](/docs/merchant/gateway_aggregator/orders/payment-page-options/merchant-hosted#pci-dss-compliant)**: The card data is collected on your page and sent to our gateway via a host-to-host request.
          example: "redirect"
          enum:
            - redirect
            - iframe
            - shop_hosted
        language:
          type: string
          nullable: true
          description: "Language code (ISO 639-1). Defaults to automatic detection if not provided."
          example: "en"

    P2PResponse:
      type: object
      required:
        - p2pNumber
        - p2pStatus
      description: "Response data returned after a successful P2P transaction creation."
      properties:
        p2pNumber:
          type: string
          description: "The unique P2P transaction number provided by the merchant."
          example: "P2P-ABC-123456"
        p2pStatus:
          type: string
          description: "The current status of the P2P transfer."
          enum:
            - registered
            - in_progress
            - completed
            - failed
            - cancelled
            - need_action
            - review
          example: "in_progress"

    P2PStatusResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          description: "The details of the P2P transaction."
          required:
            - shopId
            - id
            - p2pStatus
            - p2pNumber
            - cost
            - p2pCreatedAt
            - p2pTransactions
            - customer
          properties:
            shopId:
              type: integer
              description: "The unique identifier of the shop initiating the p2p transaction."
              example: 123
            id:
              type: integer
              description: "The internal unique identifier of the p2p transaction within the system. Used for referencing the payout when contacting technical support in case of any issues."
              example: 54222
            p2pStatus:
              type: string
              description: "Current status of the P2P transaction."
              enum:
                - in_progress
                - failed
                - completed
                - cancelled
                - need_action
                - review
              example: "in_progress"
            p2pNumber:
              type: string
              description: "A unique identifier for the payout, generated by the merchant, and specific to each `shopid`."
              example: "56573FDFVFDBWF"
            purpose:
              type: string
              description: "The purpose or reason for the p2p transaction."
              example: "string"
              nullable: true
            cost:
              type: object
              description: "Container for cost-related information."
              required:
                - amount
                - currency
              properties:
                amount:
                  type: string
                  description: "Total cost of the p2p transaction, formatted as a decimal string with a period (.) as the decimal separator."
                  example: "56.99"
                currency:
                  type: string
                  description: "Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
                  example: "USD"
            p2pCreatedAt:
              type: string
              description: "Date and time the p2p transaction was created, in RFC 3339 format including the UTC zone."
              example: "2023-08-29T15:34:56+03:00"
            p2pPaidAt:
              type: string
              description: "Date and time when the p2p transaction was successfully sent to the recipient, formatted according to RFC 3339, including the UTC time zone."
              example: "2023-08-29T15:34:56+03:00"
              nullable: true
            p2pTransactions:
              type: array
              description: "An array of p2p transactions objects. If the array is empty, it indicates that no p2p transactions have been made yet."
              items:
                $ref: "#/components/schemas/P2PTransactionItem"
            customer:
              $ref: "#/components/schemas/P2PCustomerInfo"
            p2pDetails:
              $ref: "#/components/schemas/P2PDetails"
            statusReason:
              type: string
              nullable: true
              description: "Explanation of why the transaction is in its current status, if applicable."
              example: "status reason"
    P2PTransactionItem:
      type: object
      description: "Individual transaction record within the P2P operation."
      properties:
        transactionId:
          type: string
          description: "Identifier for the specific transaction assigned by our system"
          example: "79"
        providerTransactionId:
          type: string
          description: "Identifier for the specific transaction assigned by the payment provider."
          example: "990943"
        cost:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: string
              description: "The amount of the transaction. Formatted as a decimal string with a period (.) as the decimal separator."
              example: "56.99"
            currency:
              type: string
              description: "Specifies the currency in ISO 4217 alphabetic code format, consisting of 3 uppercase letters."
              example: "USD"
        provider:
          type: object
          properties:
            code:
              type: string
              description: "Code of the payment provider."
              example: "fyst"
        status:
          type: object
          required:
            - status
          description: "Contains the status of the payout, including detailed information in case of payout failure."
          properties:
            status:
              type: string
              enum:
                - in_progress
                - completed
                - cancelled
                - failed
                - review
              description: "The current state of the p2p transaction."
              example: "in_progress"
            details:
              type: object
              nullable: true
              description: "Provides additional error details if the transaction fails."
              properties:
                errorId:
                  type: string
                  description: "A unique identifier for the error generated by the system, used for tracking and troubleshooting."
                  example: "61740c87-b60d-4578-bf25-575a8c68532e"
                providerMessage:
                  type: string
                  description: "An error message provided by the payment provider, offering insight into the reason for the failure."
                  example: "p2p method not found"
                code:
                  type: integer
                  description: "An internal error code used by the system to categorize the type of error that occurred."
                  example: 401
    P2PCustomerInfo:
      type: object
      description: "Container for customer-specific information."
      required:
        - customerId
      properties:
        customerId:
          type: string
          description: "An identifier for the customer provided when creating the p2p transaction."
          example: "56656"
        firstName:
          type: string
          description: "Customer's first name."
          example: "John"
        lastName:
          type: string
          description: "Customer's last name."
          example: "Doe"
        middleName:
          type: string
          nullable: true
          description: "Customer's middle name, if any."
          example: "James"
        phone:
          type: string
          nullable: true
          description: "Customer's phone number."
          example: "79221110500"
        email:
          type: string
          format: email
          description: "Customer's email address."
          example: "john.doe@mymail.com"
        affiliatedId:
          type: string
          nullable: true
          description: "An optional identifier provided by the merchant to facilitate custom payment routing."
          example: "afl_4848301"
        birthDate:
          type: string
          nullable: true
          description: "The customer's date of birth in the format (ISO 8601: YYYY-MM-DD)."
          example: 1990-12-30
        billingAddress:
          type: object
          nullable: true
          description: "The billing address for the customer"
          properties:
            addressType:
              type: string
              nullable: true
              description: "Type of the address. billing - billing address, shipping - shipping address"
              enum:
                - billing
                - shipping
            address:
              nullable: true
              type: string
              description: "Address line."
              example: "7, Sunny street"
            region:
              type: string
              nullable: true
              description: "Region of the billing address."
              example: "Limassol"
            city:
              type: string
              nullable: true
              description: "City of the billing address."
              example: "Limassol"
            country:
              type: string
              nullable: true
              description: "Country code in ISO 3166-1 alpha-2 format."
              example: "CY"
            zipCode:
              type: string
              nullable: true
              description: "Postal code."
              example: "4141"
            state:
              type: string
              nullable: true
              description: "State or region."
              example: "CA"
    P2PDetails:
      type: object
      required:
        - recipient
        - sender
      description: "Details about the sender and recipient in the P2P transaction."
      properties:
        recipient:
          oneOf:
            - type: object
              title: "Card"
              description: "Recipient uses a card (masked card number only)."
              required:
                - maskedCardNumber
              properties:
                maskedCardNumber:
                  type: string
                  nullable: false
                  description: "Masked card number for the recipient."
                  example: "123456******1234"
            - type: object
              title: "Routing number + BAN"
              description: "Routing number + Bank account number (BAN)."
              required:
                - routingNumber
                - accountNumber
              properties:
                routingNumber:
                  type: string
                  nullable: false
                  description: "Routing number for the recipient's bank."
                  example: "021000021"
                accountNumber:
                  type: string
                  nullable: false
                  description: "Bank account number if recipient uses bank transfer."
                  example: "123456789012"
            - type: object
              title: "IBAN"
              description: "IBAN."
              required:
                - iban
              properties:
                iban:
                  type: string
                  nullable: false
                  description: "Bank account number if recipient uses IBAN."
                  example: "DE89370400440532013000"
            - type: object
              title: "BIC + BAN"
              description: "Bank Identification Code (BIC) + Bank account number (BAN)."
              required:
                - bankBic
                - accountNumber
              properties:
                bankBic:
                  type: string
                  nullable: false
                  description: "Bank identifier code for the recipient's bank."
                  example: "BBANKNYXXXX"
                accountNumber:
                  type: string
                  nullable: false
                  description: "Bank account number if recipient uses bank transfer."
                  example: "123456789012"
            - type: object
              title: "walletid"
              description: "Wallet Id."
              required:
                - walletId
              properties:
                walletId:
                  type: string
                  nullable: false
                  description: "The wallet identifier."
                  example: "wallet-98765"
          description: "Information about the recipient's  details."
        sender:
          oneOf:
            - type: object
              title: "Card"
              description: "Sender uses a card (masked card number only)."
              required:
                - maskedCardNumber
              properties:
                maskedCardNumber:
                  type: string
                  nullable: false
                  description: "Masked card number for the sender."
                  example: "123456******1234"

            - type: object
              title: "Routing number + BAN"
              description: "Routing number + Bank account number (BAN)."
              required:
                - routingNumber
                - accountNumber
              properties:
                routingNumber:
                  type: string
                  nullable: false
                  description: "Routing number for the sender's bank."
                  example: "021000021"
                accountNumber:
                  type: string
                  nullable: false
                  description: "Bank account number if sender uses bank transfer."
                  example: "123456789012"

            - type: object
              title: "IBAN"
              description: "IBAN."
              required:
                - iban
              properties:
                iban:
                  type: string
                  nullable: false
                  description: "Bank account number if sender uses IBAN."
                  example: "DE89370400440532013000"

            - type: object
              title: "BIC + BAN"
              description: "Bank Identification Code (BIC) + Bank account number (BAN)."
              required:
                - bankBic
                - accountNumber
              properties:
                bankBic:
                  type: string
                  nullable: false
                  description: "Bank identifier code for the sender's bank."
                  example: "BBANKNYXXXX"
                accountNumber:
                  type: string
                  nullable: false
                  description: "Bank account number if sender uses bank transfer."
                  example: "123456789012"
            - type: object
              title: "walletid"
              description: "Wallet Id."
              required:
                - walletId
              properties:
                walletId:
                  type: string
                  nullable: false
                  description: "The wallet identifier."
                  example: "wallet-98765"
          description: "Information about the sender's account details or card."
x-webhooks:
  newPet:
    post:
      summary: "Callback"
      description: "To promptly inform merchants about changes in the status of processed orders, we send POST requests with order data to the merchant's endpoint.\n We include a control signature in the headers, `api-notification-sign` (SHA512), to safeguard the security and authenticity of the data received.\n[See how to configure callback.](/docs/common/getting-started/callbacks)"
      operationId: callback
      tags:
        - Order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/order.status"

  payout-callback:
    post:
      summary: "Callback Payout"
      description: "To promptly inform merchants about changes in the status of processed payouts, we send POST requests with order data to the merchant's endpoint.\n We include a control signature in the headers, `api-notification-sign` (SHA512), to safeguard the security and authenticity of the data received.\n[See how to configure callback.](/docs/common/getting-started/callbacks)"
      operationId: callbackPayout
      tags:
        - Payout
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/callbackPayout"

  p2p-callback:
    post:
      summary: "Callback P2P"
      description: "To promptly inform merchants about changes in the status of processed P2P transactions, we send POST requests with P2P transaction data to the merchant's endpoint.\n We include a control signature in the headers, `api-notification-sign` (SHA512), to safeguard the security and authenticity of the data received.\n[See how to configure callback.](/docs/common/getting-started/callbacks)"
      operationId: callbackP2P
      tags:
        - P2P
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/P2PStatusResponse"

  chargeback-callback:
    post:
      summary: "Callback Chargeback"
      description: "To promptly inform merchants about new chargebacks, we send POST requests with chargeback data to the merchant's endpoint.\n[See how to configure callback.](/docs/common/getting-started/callbacks)"
      operationId: callbackChargeback
      tags:
        - Chargeback
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V1OrderResponseOrderChargebacksResponse"
