openapi: 3.0.0
info:
  version: 1.0.0
  title: ows-payee API Specifications
servers:
  - url: "https://qa-ows-payee.theorchard.io"
    description: QA server
paths:
  /hello/:
    get:
      summary: Check the health of the application.
      responses:
        200:
          description: 200 OK

  /account-payee/{account_payee_id}/tax-details:
    get:
      summary: Get tax information for a Payee
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayeeTaxInfoDetailSchema"
    post:
      summary: Create tax details for a payee
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: Creates tax details for a payee
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTaxDetailsSchema"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayeeTaxInfoDetailSchema"
        "400":
          description:
            Invalid or incomplete data in the request body, or Payoneer
            request error
        "500":
          description: Internal server error, something unexpected happened

  /account-payee/{account_payee_id}/knr-details:
    get:
      summary: Get knr information for a Payee
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayeeKnrInfoDetailSchema"
        "404":
          description: Knr details document not found for a given payee_account_id
    post:
      summary: Create knr details for a payee
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: Creates knr details for a payee
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateKnrDetailsSchema"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayeeKnrInfoDetailSchema"
        "400":
          description: Invalid or incomplete data in the request body

  /account-payee/{account_payee_id}/resync-payment-readiness:
    post:
      summary: Resync payment readiness
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResyncPaymentReadinessSchema"
        "400":
          description: Invalid account_payee_id

  /account-payee/tax-details-dataloader:
    post:
      summary: Dataload tax details by revision ids for a payee
      requestBody:
        description: Tax details ids and payee ids pairs
        required: false
        content:
          application/json:
            schema:
              items:
                type: array
                description: List of tax details revisions
                items:
                  $ref: "#/components/schemas/DataloadTaxDetailsRequestSchema"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: List of tax details revisions
                items:
                  anyOf:
                    - $ref: "#/components/schemas/DataloadTaxDetailsResponseSchema"
                    - $ref: "#/components/schemas/DataloadTaxDetailsResponseErrorSchema"
        "400":
          description: Invalid or incomplete data in the request body

  /account-payee/knr-details-dataloader:
    post:
      summary: Dataload knr details by revision ids for a payee
      requestBody:
        description: Knr details ids and payee ids pairs
        required: false
        content:
          application/json:
            schema:
              type: array
              description: List of knr details revisions
              items:
                anyOf:
                  - $ref: "#/components/schemas/DataloadTaxDetailsRequestSchema"
                  - $ref: "#/components/schemas/DataloadTaxDetailsRequestSchema"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                description: List of knr details revisions
                items:
                  anyOf:
                    - $ref: "#/components/schemas/DataloadKnrDetailsResponseSchema"
                    - $ref: "#/components/schemas/DataloadTaxDetailsResponseErrorSchema"
        "400":
          description: Invalid or incomplete data in the request body

  /account-payee/{account_payee_id}/tax-details/receipt:
    get:
      summary: Get tax information for a Payee as a PDF file.
        The file has the same data as PayeeTaxInfoDetailSchema.
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/pdf:
              schema:
                type: string
                format: binary

  /account-payee/{account_payee_id}/tax-details-history:
    get:
      summary: Get tax details history for a Payee
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: List of tax details revisions
                    items:
                      $ref: "#/components/schemas/PayeeKnrDetailsRevision"
        "401":
          description: Invalid payee_account_id owner

  /account-payee/{account_payee_id}/knr-details-history:
    get:
      summary: Get knr details history for a Payee
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: List of knr details revisions
                    items:
                      $ref: "#/components/schemas/PayeeKnrDetailsRevision"
        "401":
          description: Invalid payee_account_id owner

  /account-payee/{account_payee_id}/payoneer-status:
    get:
      summary: get payee payoneer account status.
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Get payoneer account status
                example:
                  status: "INIT"
        "401":
          description: Invalid payee_account_id owner
        "500":
          description: Internal server error, something unexpected happened

  /account-payee/{account_payee_id}/payoneer-account:
    delete:
      summary: Release payee from payoneer.
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_payee_id:
                    type: integer
                    description: Payee id
                example:
                  account_payee_id: 123
        "401":
          description: Invalid payee_account_id owner
        "500":
          description: Internal server error, something unexpected happened

  /account-payee/{account_payee_id}/validate-session-id:
    get:
      summary: Validate payee payoneer session id.
      parameters:
        - in: path
          name: account_payee_id
          required: true
          schema:
            type: integer
          description: id of payee
        - in: query
          name: session_id
          schema:
            type: string
            format: uuid
          required: true
          description: payoneer session id
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id_is_valid:
                    type: boolean
                    description: Is session id valid
                example:
                  session_id_is_valid: true
        "401":
          description: Invalid payee_account_id owner
        "400":
          description: Invalid or incomplete data in request
        "500":
          description: Internal server error, something unexpected happened

  /account-payee/{account_payee_id}/tax-details/receipt-url:
    get:
      summary: Get tax information for a Payee as a link to a PDF file in S3.
        Returns a link instead of the file so the response can be passed via GraphQL.
        The file has the same data as PayeeTaxInfoDetailSchema.
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  receipt_url:
                    type: string
                    description: The S3 URL with the PDF file
                example:
                  receipt_url: "https://aws.s3.presigned.url.example.com"

  /account-payee/{account_payee_id}/move-payoneer-program:
    post:
      summary: Move Payoneer program
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: Programs ids
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MovePayoneerProgramSchema"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MovePayoneerProgramResponse"
        "400":
          description:
            Invalid or incomplete data in the request body, or Payoneer
            request error
        "500":
          description: Internal server error, something unexpected happened

  /account-payee/{account_payee_id}/program/{program_id}/payoneer-status:
    get:
      summary: Get payee Payoneer payee status.
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
        - description: id of payee
          name: program_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetPayeeStatusResponse"
        "500":
          description: Internal server error, something unexpected happened

  /payoneer/registration-link:
    post:
      summary: Creates a new Payoneer registration link
      requestBody:
        description: Creates a new Payoneer registration link
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePayoneerRegistrationLinkSchema"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePayoneerRegistrationLinkResponseSchema"
        "400":
          description: Invalid or incomplete data in the request body
        "500":
          description: Internal server error, something unexpected happened

  /payoneer/programs/{program_id}/mass-payouts:
    post:
      summary: Creates Payoneer mass payouts
      parameters:
        - description: Payoneer program id of the program of the payouts
          name: program_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        description: Creates Payoneer mass payouts
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePayoneerMassPayoutsSchema"
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePayoneerMassPayoutsSchema"
        "400":
          description: Invalid or incomplete data in the request body
        "500":
          description: Internal server error, something unexpected happened

  /account-payee/{account_payee_id}/payee-payoneer-details:
    get:
      summary: Get payee Payoneer details.
      parameters:
        - description: id of payee
          name: account_payee_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayeePayoneerDetailsResponseSchema"
        "401":
          description: Invalid payee_account_id owner
        "500":
          description: Internal server error, something unexpected happened

components:
  schemas:
    PayeePayoneerDetailsResponseSchema:
      title: Payee Payoneer details response
      type: object
      properties:
        payee_name:
          type: string
      required:
        - payee_name

    CreatePayoneerRegistrationLinkSchema:
      title: Payoneer create registration link POST request body
      type: object
      properties:
        account_payee_id:
          type: integer
          description: The payee's ID
        payoneer_program_id:
          type: integer
          description: The Payoneer program id to use on registration
        payoneer_session_id:
          type: string
          description: The Payoneer session id to use on registration
        payee:
          type: object
          properties:
            first_name:
              type: string
              description: The Payee first name to use on Payoneer registration
            last_name:
              type: string
              description: The Payee last name to use on Payoneer registration
            email:
              type: string
              description: The Payee email to use on Payoneer registration
      example:
        account_payee_id: 123
        payoneer_program_id: 456
        payee:
          first_name: "John"
          last_name: "Doe"
          email: "johndoe@fakeemail.com"
    CreatePayoneerRegistrationLinkResponseSchema:
      title: Payoneer create registration link response body
      type: object
      properties:
        account_payee_id:
          type: integer
          description: The payee's ID
        payoneer_session_id:
          type: string
          description: The session id generated for this payee
        registration_link:
          type: string
          description: The Payoneer registration link for this payee
        token:
          type: string
          description: The token returned by Payoneer
      example:
        account_payee_id: 123
        payoneer_session_id: "123SessionId456"
        registration_link: "http://payouts.sandbox.payoneer.com/partners/lp.aspx?token=7293f06a1d524e6f80a4f0f414b0f0962010B7745A"
        token: "7293f06a1d524e6f80a4f0f414b0f0962010B7745A"
    CreatePayoneerMassPayoutsSchema:
      title: Creates Payoneer mass payouts
      type: object
      properties:
        client_reference_id:
          type: string
          description: The client's reference ID
        account_payee_id:
          type: string
          description: The payee's ID
        description:
          type: string
          description: The mass payouts' description (Provided description will be overridden by the account payment description if it exists)
        currency:
          type: string
          description: The currency for the payouts
        amount:
          type: number
          description: The amount to pay
      example:
        client_reference_id: "456"
        account_payee_id: "123"
        description: "Information about Payout"
        currency: "USD"
        amount: 1000
    PayeeTaxInfoDetailSchema:
      title: Tax information details
      type: object
      properties:
        account_payee_id:
          type: number
          description: Id of a payee
        vat_number:
          type: string
          description: The Payee's VAT ID
        country_of_tax_residence_code:
          type: string
          description: Country code where Payee has tax residence
        local_tax_id:
          type: string
          description: Local tax ID (relevant for ES taxes)
        address:
          type: object
          properties:
            address1:
              type: string
              description: Payee's address for tax purposes
            address2:
              type: string
              description: Payee's address for tax purposes
            city:
              type: string
              description: Payee's city for tax purposes
            province:
              type: string
              description: Payee's province for tax purposes
            zip:
              type: string
              description: Payee's zip code for tax purposes
            country_code:
              type: string
              description: Payee's country code for tax purposes
      example:
        account_payee_id: 1
        vat_number: "821018768"
        address:
          address1: "Down the line street"
          address2: "Some Alternative address"
          country_of_tax_residence_code: "USA"
          city: "New York"
          province: "Quebec"
          zip: "10001"
    PayeeKnrInfoDetailSchema:
      title: Knr information details
      type: object
      properties:
        account_payee_id:
          type: number
          description: Id of a payee
        w_form:
          type: object
          properties:
            w_form_type:
              type: string
              description: W-Form type
            w_form_expiry:
              type: string
              description: W Form expiry date
        sap_vendor_id:
          type: number
          description: Sap vendor id
      example:
        account_payee_id: 1
        w_form:
          w_form_type: "W9"
          w_form_expiry: "2022-11-21T17:51:32Z"
        sap_vendor_id: 123
    ResyncPaymentReadinessSchema:
      title: Resync payment readiness response
      type: object
      properties:
        account_payee_id:
          type: number
          description: Id of a payee
      example:
        account_payee_id: 1
    CreateTaxDetailsSchema:
      title: Schema for creating tax details for a VAT/nonVAT registered payee
      type: object
      properties:
        vat_number:
          type: string
          description: The Payee's VAT ID
        country_of_tax_residence_code:
          type: string
          description: Country code where Payee has tax residence
        local_tax_id:
          type: string
          description: Local tax ID (relevant for ES taxes)
        is_vat_registered:
          type: boolean
          description: VAT registration flag  (relevant for ES taxes)
        address:
          type: object
          properties:
            address1:
              type: string
              description: Payee's address for tax purposes
            address2:
              type: string
              description: Payee's address for tax purposes
            city:
              type: string
              description: Payee's city for tax purposes
            province:
              type: string
              description: Payee's province for tax purposes
            zip:
              type: string
              description: Payee's zip code for tax purposes
            country_code:
              type: string
              description: Payee's country code for tax purposes
      example:
        vat_number: "821018768"
        country_of_tax_residence_code: "USA"
        address:
          address1: "Down the line street"
          address2: "Alternative address"
          zip: "10001"
          country_code: "USA"
          city: "New York"
          province: "Quebec"
    CreateKnrDetailsSchema:
      title: Schema for creating knr details for payee
      type: object
      properties:
        w_form_type:
          type: string
          description: W-Form type
        w_form_expiry:
          type: string
          description: W Form expiry date
        sap_vendor_id:
          type: number
          description: Sap vendor id
      example:
        w_form:
          w_form_type: "W9"
          w_form_expiry: "2022-11-21T17:51:32Z"
        sap_vendor_id: 123

    PayeeKnrDetailsRevision:
      title: Tax information details
      type: object
      properties:
        account_payee_id:
          type: number
          description: Id of a payee
        revision:
          type: string
          description: id of revision
      example:
        account_payee_id: 1
        revision: "asdKHAkhbas-a98kHBASKDasd-asd"
    DataloadTaxDetailsRequestSchema:
      title: Dataload request array item
      type: object
      properties:
        accountPayeeId:
          type: integer
          description: The payee's ID
        revision:
          type: string
          description: payee's details document revision id
      example:
        account_payee_id: 1
        revision: "asdKHAkhbas-a98kHBASKDasd-asd"

    DataloadTaxDetailsResponseSchema:
      title: Dataload response array error item
      type: object
      properties:
        data:
          $ref: "#/components/schemas/PayeeTaxInfoDetailSchema"

    DataloadTaxDetailsResponseErrorSchema:
      title: Dataload response array error item
      type: object
      properties:
        error:
          type: string
          description: payee's details document revision id
      example:
        error: "You do not have access to this resource!"

    DataloadKnrDetailsResponseSchema:
      title: Dataload response array error item
      type: object
      properties:
        data:
          $ref: "#/components/schemas/PayeeKnrInfoDetailSchema"

    MovePayoneerProgramSchema:
      title: Move Payoneer Program request data
      type: object
      properties:
        existing_payoneer_program_id:
          type: number
          description: Existing payoneer program id
        new_payoneer_program_id:
          type: number
          description: New payoneer program id

    MovePayoneerProgramResponse:
      title: MOve Payoneer program response from service
      type: object
      properties:
        result:
          type: object
          properties:
            payee_id:
              type: string
            adopted_to_partner_id:
              type: number
            adopted_payee_id:
              type: string
            date_adopted:
              type: string
          example:
            payee_id: "test5972600"
            adopted_to_partner_id: 123456
            adopted_payee_id: "test5972600"
            date_adopted: "2021-03-24T14:45:43-04:00"

    GetPayeeStatusResponse:
      title: Get payee status response
      type: object
      properties:
        result:
          type: object
          properties:
            account_id:
              type: string
            status:
              type: object
              properties:
                type:
                  type: number
                description:
                  type: string
            registration_date:
              type: string
            payout_method:
              type: object
              properties:
                type:
                  type: string
                currency:
                  type: string