openapi: 3.0.0
info:
  title: P2P API
  description: |
    This document serves as the API documentation for our Agents services, designed for merchant integration.

    ## Before you start

    Before you begin working with the API endpoints, make sure that you have visited [Getting started page](../common/getting-started) and review the [Operation Types and the Sequence of API Calls](/docs/agent/operation-types) page.


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

  version: 0.0.1
servers:
  - url: "https://gateway.fundix.me"
    description: Base URL for the production API endpoints.
#  - url: "https://gateway.stage.fundix.me"
#    description: Base URL for the test API endpoints.
paths:
  /api/v1/agents/payment-method-types:
    get:
      tags:
        - Agents
      summary: Get available payment method types
      description: Retrieves a list of available payment method types for a shop based on provided criteria.
      operationId: get_app_external_v1_agents_paymentmethodtype_paymentmethodtype_get
      parameters:
        - name: shopId
          in: query
          description: The shop ID for which to retrieve payment method types. [How to get your shopId](../common/getting-started/shop-id)
          required: true
          schema:
            type: string
            example: "43223"
        - name: operationType
          in: query
          description: "Type of operation. [Learn about payin / payout operations](../agent/operation-types)"
          required: true
          schema:
            type: string
            enum:
              - payin
              - payout
            example: payin
        - name: amount
          in: query
          description: The amount of the transaction for which the payment method is requested. Formatted as a decimal string with a period (.) as the decimal separator.
          schema:
            type: number
            example: "100.00"
        - name: currency
          in: query
          description: Currency, specified as a three-letter ISO 4217 currency code in uppercase.
          schema:
            type: string
            maxLength: 3
            minLength: 3
            example: USD
      responses:
        "200":
          description: List of available payment methods for a shop
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PaymentMethodTypeResponse"
                type: object
  /api/v1/agents/sessions:
    post:
      tags:
        - Agents
      summary: Initialize a new session
      description: |
        Initializes a new session for a P2P operation. This endpoint does not create an operation; it only creates a session required for creating an operation. To create an operation, you need to first call this endpoint to initialize a session, and then use the data from its response to call the [Create a new P2P operation](/docs/agent-api/post-app-external-v-1-agents-operation-operation-makebysession) endpoint.

        This endpoint should be called after obtaining data from the Get available payment method types endpoint, as the information from that response is needed to provide data for this request.

      operationId: post_app_external_v1_agents_session_session_init
      requestBody:
        description: Details required to initialize a new session.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InitSessionRequest"
      responses:
        "200":
          description: Session initialization details
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/InitSessionResponse"
                type: object
  /api/v1/agents/sessions/{id}:
    get:
      tags:
        - Agents
      summary: Retrieve session details
      description: Retrieves details of a specific session by its ID.
      operationId: get_app_external_v1_agents_session_session_get
      parameters:
        - name: id
          in: path
          description: The unique identifier of the session.
          required: true
          schema:
            type: string
            example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      responses:
        "200":
          description: Session details
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/InitSessionResponse"
                type: object

  /api/v1/agents/operations:
    post:
      tags:
        - Agents
      summary: Create a new P2P operation
      description: |

        Initiates a new P2P operation based on the provided session details.


        **To create an operation, follow these steps**:

        1. [Retrieve the available methods](/docs/agent-api/get-app-external-v-1-agents-paymentmethodtype-paymentmethodtype-get).

        2. Select the appropriate method.

        3. [Create a P2P session](/docs/agent-api/post-app-external-v-1-agents-session-session-init) using the data from step 2.

        4. Obtain the list of required data (payerRequisites) for the operation and collect this information from your customer. The `payerRequisites` object, which contains the required data for the operation, should be collected by the merchant from their customer and then provided in this method. `The payerRequisites` object template is received by the merchant in the response from step 3.

        5. Create the operation using the data from step 4.
      operationId: post_app_external_v1_agents_operation_operation_makebysession
      requestBody:
        description: Details required to create a new P2P operation.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MakeOperationBySessionRequest"
      responses:
        "200":
          description: |
            This response provides operation details. The `operation` field contains the current operation details, including all relevant information such as status, amount, and currency. 

            The `parent` field is used only if the current operation is a correction. If a correction has been made from the back office (`isCorrection` is `true`), the `parent` field will contain the details of the original operation before the correction. If no corrections have been made (`isCorrection` is `false`), the `parent` field will be null.

            When creating an operation, the response will always return the `parent` object as null.

            Therefore:
            - `operation`: Always contains the details of the current operation.
            - `parent`: Contains the original operation details only if a correction was made; otherwise, it is null.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/OperationDetailsResponse"
                type: object
  /api/v1/agents/operations/{shopId}/{operationNumber}:
    get:
      tags:
        - Agents
      summary: Retrieve P2P operation details
      description: Retrieves details of a specific P2P operation by its operation number.
      operationId: get_app_external_v1_agents_operation_operation_getbynumber
      parameters:
        - name: shopId
          in: path
          description: "ID of the shop where the operation is placed. [How to get your shopId](../common/getting-started/shop-id)"
          required: true
          schema:
            type: integer
            example: 121
        - name: operationNumber
          in: path
          description: The unique identifier of the operation.
          required: true
          schema:
            type: string
            example: "12345"
      responses:
        "200":
          description: |
            This response provides operation details. The `operation` field contains the current operation details, including all relevant information such as status, amount, and currency. 

            The `parent` field is used only if the current operation is a correction. If a correction has been made from the back office (`isCorrection` is `true`), the `parent` field will contain the details of the original operation before the correction. If no corrections have been made (`isCorrection` is `false`), the `parent` field will be null.

            Therefore:
            - `operation`: Always contains the details of the current operation.
            - `parent`: Contains the original operation details only if a correction was made; otherwise, it is null.
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data:
                    $ref: "#/components/schemas/OperationDetailsResponse"
                type: object
  /api/v1/upload:
    post:
      tags:
        - Agents
      summary: Upload a file
      description: |
        Uploads multiple files and returns the unique identifiers (UUIDs) of the uploaded files. 

        :::warning
        The examples provided in the right menu may not be accurate. Please ignore them.
        The correct cURL example is:

        :::

        ```
        curl -L -X POST 'https://gateway.stage.fundix.me/api/v1/upload' \
        -H 'Content-Type: multipart/form-data' \
        -H 'Accept: application/json' \
        -H 'Api-Access-Token: ' \
        -F 'files[]=@/path/to/file/image.jpg' \
        -F 'files[]=@/path/to/file/image2.png'
        ```
      operationId: post_app_external_v1_uploadfile_upload
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                "files[]":
                  type: array
                  items:
                    type: string
                    format: binary
                    pattern: "^@.*$"
      responses:
        200:
          description: A successful upload returns the UUIDs of the uploaded files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
                      example: dbf4320a-54b3-4556-92d4-fd4ebbd0d070.jpg
components:
  schemas:
    MakeOperationBySessionRequest:
      title: V1-Agents-Operation-Request-MakeOperationBySessionRequest
      required:
        - sessionId
        - payerRequisites
      properties:
        sessionId:
          type: string
          description: The unique identifier of the session.
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        operationNumber:
          type: string
          description: The unique identifier of the operation.
          example: "99999"
          nullable: true
        payerRequisites:
          type: array
          description: "The structure of the data to be sent is received from the response of the [Initialize a new session](/docs/agent-api/post-app-external-v-1-agents-session-session-init) endpoint. You need to pass all the data from the `payerRequisites` array object, adding a field called `value` and filling it with the appropriate information: recipient's information if `operationType = payout`, or payer's information if `operationType = payin`."
          items:
            oneOf:
              - $ref: "#/components/schemas/FileType"
              - $ref: "#/components/schemas/NumberType"
              - $ref: "#/components/schemas/StringType"
      type: object
    OperationDetailsResponse:
      title: V1-Operation-Response-OperationDetailsResponse
      required:
        - operation
      properties:
        operation:
          $ref: "#/components/schemas/ShopOperationResponse"
        parent:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/ShopOperationResponse"
      type: object
    PaymentMethodTypeResponse:
      title: V1-Agents-PaymentMethodType-Response-PaymentMethodTypeResponse
      required:
        - instrumentType
        - minAmount
        - maxAmount
        - id
        - name
        - country
        - currency
      properties:
        id:
          type: string
          description: "The unique identifier of the payment method type. Used in the body of the [Initialize a new session endpoint](/docs/agent-api/post-app-external-v-1-agents-session-session-init) request to create a session."
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        name:
          type: string
          description: The name of the payment method type.
          example: "Bank Transfer"
        instrumentType:
          type: string
          description: "Enumerates the various types of payment instruments that can be used in transactions. Each type represents a different method of payment handling and processing. [Learn about type](../agent/instrument-type)"
          enum:
            - card
            - ewallet
            - mobile_billing
            - cash
            - payment_kiosk
            - online_bank
            - prepaid_card
            - bank_transfer
            - crypto_currency
            - e_voucher
            - other
        country:
          description: "The country code where this payment method is available, following the ISO 3166-1 alpha-2 standard"
          type: string
          maxLength: 2
          minLength: 2
          example: US
        currency:
          description: "Currency in which the operation is conducted, specified as a three-letter ISO 4217 currency code in uppercase"
          type: string
          maxLength: 3
          minLength: 3
          example: USD
        minAmount:
          type: string
          description: "The minimum amount allowed for transactions using this payment method, formatted as a decimal string with a period (.) as the decimal separator. The fractional part may appear only if it exists."
          example: "10"
        maxAmount:
          type: string
          description: "The minimum amount allowed for transactions using this payment method, formatted as a decimal string with a period (.) as the decimal separator. The fractional part may appear only if it exists."
          example: "1999.99"
      type: object
    InitSessionRequest:
      title: V1-Agents-Session-Request-InitSessionRequest
      required:
        - operationType
        - shopId
        - payerId
        - amount
        - paymentMethodTypeId
        - currency
      properties:
        paymentMethodTypeId:
          type: string
          description: "The unique identifier of the payment method type. Pass the `id` parameter received in the response of the [Get available payment method types endpoint](/docs/agent-api/get-app-external-v-1-agents-paymentmethodtype-paymentmethodtype-get) of the selected payment method."
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        operationType:
          type: string
          description: "Type of operation. [Learn about payin / payout operations](../agent/operation-types)"
          enum:
            - payin
            - payout
        shopId:
          type: integer
          description: The identifier of the shop for which the session is being created. [How to get your shopId](../common/getting-started/shop-id)
          example: 43432
        operationNumber:
          type: string
          description: The unique operation number in the merchant's system. Generated on your side at your discretion.
          example: "99999"
          nullable: true
        payerId:
          type: string
          description: The unique identifier of the payer in the merchant's system. Generated on your side at your discretion. The 'payerId' 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: "payer123"
        amount:
          type: string
          description: The amount of the operation. Formatted as a decimal string with a period (.) as the decimal separator.
          minimum: 0
          exclusiveMinimum: true
          example: "100.25"
        currency:
          description: Currency in which the operation is conducted, specified as a three-letter ISO 4217 currency code in uppercase.
          type: string
          maxLength: 3
          minLength: 3
          example: USD
      type: object
    InitSessionResponse:
      title: V1-Agents-Session-Response-InitSessionResponse
      required:
        - expiredAt
        - payerRequisites
        - sessionId
        - paymentMethodRequisites
      properties:
        sessionId:
          type: string
          description: The unique identifier of the session.
          example: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        expiredAt:
          type: string
          description: The expiration date and time of the session (RFC 3339 format including the UTC zone). After this time, the session will expire and creating an operation with this `sessionId` will not be possible.
          example: "2024-02-06T10:49:46+00:00"
        payerRequisites:
          type: array
          description: "A list of requisite fields for payin or payout operations. These fields need to be filled with the recipient's information if the `operationType = payout`, or with the payer's information if the `operationType = payin`."
          items:
            $ref: "#/components/schemas/PayerRequisitesResponse"
        paymentMethodRequisites:
          type: array
          description: "Details of the payment method requisites to be shown to the customer. For payin operations, it helps the customer understand where to transfer the money. For payout operations, it shows the customer where the money came from."
          items:
            $ref: "#/components/schemas/PaymentMethodRequisitesResponse"
      type: object
    ShopOperationResponse:
      title: V1-Operation-Response-ShopOperationResponse
      required:
        - type
        - id
        - shopId
        - paymentMethodRequisites
        - payerId
        - amount
        - registeredAt
        - updatedAt
        - status
        - isCorrection
        - payerDetails
        - currency
      properties:
        type:
          description: "The type of operation [Learn about payin / payout operations](../agent/operation-types)."
          type: string
          enum:
            - payin
            - payout
        id:
          type: integer
          description: Unique identifier of the operation.
          example: 1
        shopId:
          type: integer
          description: Unique identifier of the shop. [How to get your shopId](../common/getting-started/shop-id)
          example: 1
        operationNumber:
          type: string
          description: Unique identifier of the operation in the merchant's system.
          example: "99999"
          nullable: true
        paymentMethodRequisites:
          type: array
          description: Requisites associated with the payment method used in the operation. These details should be shown to the customer. For payin operations, it helps the customer understand where to transfer the money. For payout operations, it shows the customer where the money came from.
          items:
            $ref: "#/components/schemas/PaymentMethodRequisitesResponse"
        payerId:
          type: string
          description: Unique identifier of the payer in the merchant's system.
          example: "111"
        amount:
          type: string
          description: The operation's original amount as specified at the time of operation creation.
          example: "100.25"
        currency:
          type: string
          maxLength: 3
          minLength: 3
          example: USD
          description: The operation's original currency as specified at the time of operation creation, represented as a three-letter ISO 4217 currency code in uppercase.
        settlementAmount:
          type: string
          description: The amount of the operation in the settlement currency after conversion.
          example: "1.25"
          nullable: true
        settlementCurrency:
          type: string
          description: The currency of the operation after conversion, represented as a three-letter ISO 4217 currency code in uppercase..
          example: "USD"
          nullable: true
        registeredAt:
          description: Date and time when the operation was registered, in RFC 3339 format including the UTC zone.
          type: string
          example: "2023-09-01T13:00:00+00:00"
        updatedAt:
          description: Date and time of the last update to the operation, in RFC 3339 format including the UTC zone.
          type: string
          example: "2023-09-01T13:00:00+00:00"
        status:
          type: string
          enum:
            - created
            - canceled
            - captured
          description: The current status of the operation. [See about statuses](../agent/operation_status)
        isCorrection:
          type: boolean
          description: Indicates whether the operation has been corrected. If `false`, the operation has not undergone any corrections. If `true`, the operation has been corrected, a process that can only be performed from the back office. Upon the operation's creation, `isCorrection` is always set to `false`. If `isCorrection` is `true`, the original operation will be found in the `parent` object, and the current corrected operation will be in the `operation` object. The current operation is always found in the `operation` object.
        payerDetails:
          type: array
          description: "The data you provided when creating the operation in the `payerRequisites` array of objects."
          items:
            oneOf:
              - $ref: "#/components/schemas/FileTypeResponse"
              - $ref: "#/components/schemas/NumberTypeResponse"
              - $ref: "#/components/schemas/StringTypeResponse"
        info:
          nullable: true
          type: object
          description: Information related to the operation's acceptance or decline. This object is populated when an operation is accepted or declined from the back office.
          properties:
            comment:
              nullable: true
              type: string
              description: Optional comment provided by the back office operator when accepting or declining the operation.
              example: "Payment verified and approved by the financial department"
            reason:
              nullable: true
              type: string
              description: The reason for declining the operation. This field is required when declining an operation from the back office.
              enum:
                - not_executed
                - wrong_credentinal
                - wrong_amount
                - other
              example: "not_executed"
            file:
              nullable: true
              type: string
              description: "File identifier for the transaction confirmation document. When accepting an operation, the back office operator can attach a file as proof of the transaction."
      type: object
    PayerRequisitesResponse:
      title: V1-Agents-Session-Response-PayerRequisitesResponse
      required:
        - name
        - title
        - type
      properties:
        name:
          type: string
          description: Name of the payer detail field.
          example: "Email"
        title:
          type: string
          description: Display title of the payer detail field.
          example: "Email"
        type:
          type: string
          description: "Type of the payer detail field. Indicates the expected data format."
          enum:
            - string
            - file
            - number
      type: object
    FileType:
      title: type = file
      required:
        - value
        - name
        - title
        - type
      properties:
        value:
          type: string
          description: "The value of the file type field. You need to first upload the file using the [Upload a file endpoint](/docs/agent-api/post-app-external-v-1-uploadfile-upload), obtain the UUID from its response, and then pass that UUID in this field."
          example: "8753563761887472837432"
        name:
          type: string
          description: Name of the payer detail field.
          example: "Identification Document"
        type:
          type: string
          enum:
            - file
          example: "file"
      type: object
    NumberType:
      title: type = number
      required:
        - value
        - name
        - title
        - type
      properties:
        value:
          type: number
          description: The value of the number type field. You can pass either integer values or floating-point numbers (formatted as a decimal with a period (.) as the decimal separator), depending on your needs.
          example: 987654321
        name:
          type: string
          description: Name of the payer detail field.
          example: "Wallet ID"
        type:
          type: string
          enum:
            - number
          example: "number"
      type: object
    StringType:
      title: type = string
      required:
        - value
        - name
        - title
        - type
      properties:
        value:
          type: string
          description: The value of the string type field.
          example: "johndoe@example.com"
        name:
          type: string
          description: Name of the payer detail field.
          example: "email"
        type:
          type: string
          enum:
            - string
          example: "string"
      type: object

    FileTypeResponse:
      title: type = file
      required:
        - value
        - name
        - title
        - type
      properties:
        name:
          type: string
          description: Name of the payer detail field.
          example: "Identification Document"
        title:
          type: string
          description: Display title of the payer detail field.
          example: "Identification Document"
        type:
          type: string
          enum:
            - file
          example: "file"
        value:
          type: string
          description: "The value of the file type field."
          example: "8753563761887472837432"
      type: object
    NumberTypeResponse:
      title: type = number
      required:
        - value
        - name
        - title
        - type
      properties:
        name:
          type: string
          description: Name of the payer detail field.
          example: "Wallet ID"
        title:
          type: string
          description: Display title of the payer detail field.
          example: "Recipient Wallet ID"
        type:
          type: string
          enum:
            - number
          example: "number"
        value:
          type: number
          description: The value of the number type field.
          example: 987654321
      type: object
    StringTypeResponse:
      title: type = string
      required:
        - value
        - name
        - title
        - type
      properties:
        name:
          type: string
          description: Name of the payer detail field.
          example: "email"
        title:
          type: string
          description: Display title of the payer detail field.
          example: "E-mail"
        type:
          type: string
          enum:
            - string
          example: "string"
        value:
          type: string
          description: The value of the string type field.
          example: "johndoe@example.com"
      type: object
    PaymentMethodRequisitesResponse:
      title: V1-Operation-Response-PaymentMethodRequisitesResponse
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Name of the requisite.
          example: "IBAN"
        value:
          type: string
          description: Value of the requisite.
          example: "37737 38883 88383"
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Api-Access-Token
      in: header
x-webhooks:
  newPet:
    post:
      summary: "Callback"
      description: |
        To promptly inform merchants about changes in the status of processed operations, we send POST requests with operation data to the merchant's endpoint. We include a control signature in the headers, `api-notification-sign` (SHA512), to safeguard the security and authenticity of the data received. [See how to configure callback.](../common/getting-started/callbacks) 

        The format of the callback is identical to the response format of the [Retrieve P2P operation](/docs/agent-api/get-app-external-v-1-agents-operation-operation-getbynumber) details endpoint.
      operationId: callback
      tags:
        - Agents
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: |
                This response provides operation details. The `operation` field contains the current operation details, including all relevant information such as status, amount, and currency. 

                The `parent` field is used only if the current operation is a correction. If a correction has been made from the back office (`isCorrection` is `true`), the `parent` field will contain the details of the original operation before the correction. If no corrections have been made (`isCorrection` is `false`), the `parent` field will be null.

                Therefore:
                - `operation`: Always contains the details of the current operation.
                - `parent`: Contains the original operation details only if a correction was made; otherwise, it is null.
              properties:
                data:
                  $ref: "#/components/schemas/OperationDetailsResponse"
security:
  - ApiKeyAuth: []
