openapi: 3.0.3
info:
  title: Antifraud Access WireTransfer API
  description: Antifraud services
  license:
    name: Apache License Version 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '2.0'
servers:
- url: https://api-sandbox.koin.com.br
  description: Sandbox domain url
tags:
- name: WireTransfer
paths:
  /v1/antifraud/evaluations:
    post:
      tags:
      - WireTransfer
      summary: Create Evaluation
      description: Receives a new transaction for antifraud analysis.
      operationId: createWireTransferUsingPOST
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WireTransferAntiFraud'
            examples:
              Wiretransfer:
                value:
                  type: WireTransfer
                  sla_date: '2023-02-10T13:51:48.000Z'
                  order_date: '2023-02-03T13:51:48.000Z'
                  execution_date: '2023-02-03T13:51:48.000Z'
                  instant: true
                  callback_url: https://postman-echo.com/post
                  transfer_type: TRANSFER
                  device:
                    ipv4: 35.139.105.100
                    location:
                      latitude: -14.56532789616039
                      longitude: -28.48945822129388
                    merchant_device: 411db886-eea4-4ea6-84bb-9d48e171c415
                    session_id: 0e986bae-8738-4cbf-b596-863704e562a9
                  store:
                    code: Jwhllcslhx
                    category: '1234'
                  transaction:
                    country_code: BR
                    total_amount:
                      currency: USD
                      value: 8008.99
                    reference_id: '12345'
                    business_id: '9876654'
                    sequence: 1
                  account_from:
                    user_id: ddb6dd01-8be9-4f91-9ff3-ae2d57086454
                    number: '1234567'
                    bank_code: '1234'
                    bank_name: HSBC
                    holder: ZuinCpmwjsd
                    currency_code: USD
                    type: BUSINESS
                    status: TO_VALIDATE
                    creation_date: '2021-07-23T16:00:00.307062Z'
                  account_to:
                    user_id: bfafbd30-f171-4bd3-bb66-220a2e0bbad0
                    number: '1234567'
                    bank_code: '2345'
                    bank_name: Banktest
                    holder: IyaeVfeygvh
                    currency_code: USD
                    type: PERSONAL
                    status: OK
                    creation_date: '2021-07-23T16:00:00.307062Z'
      responses:
        '200':
          description: Evaluation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardApiResponse'
              examples:
                Evaluation response:
                  value: '{ "id": "VEFRUD8HUR25N4992221", "evaluation_id": "31ff2cc8-199e-4c3c-ba2d-4d85b88bd9f2", "status": "received", "score": 50, "analysis_type": "AUTOMATIC" }'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                Bad Request:
                  value: '{ "code": 400, "message": "Validation errors", "causes": [ "device.ip must not be blank" ] }'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnAuthorizedResponse'
              examples:
                Unauthorized Request:
                  value: '{ "code": 401, "message": "Store does not have access to path." }'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                Error:
                  value: '{ "code": 500, "message": "Critical error in service for caseId db9279fd-2cc2-4672-aa13-1f02af50c488" }'
components:
  schemas:
    UnAuthorizedResponse:
      title: UnAuthorized Response
      type: object
      properties:
        code:
          type: string
          description: Status code
          example: '401'
        message:
          type: string
          description: Error message
          example: Validation errors
    StrategyResponse:
      title: StrategyResponse
      type: object
      properties:
        type:
          type: string
          description: Strategy type, see [Strategies](https://api-koin.readme.io/reference/strategies)
          enum:
          - VerificationCode
          - DocumentScan
          - ManualVerification
          - CollectAuthRecovery
        link:
          type: string
          description: Url for access the strategy page
        channels:
          type: string
          description: Channels for the strategy
          enum:
          - Mail
          - Phone
        provider:
          type: string
          description: Provider for the strategy in case of CollectAuthRecovery strategy
          enum:
          - 3DS2
        mode:
          type: string
          description: Mode for the strategy in case of CollectAuthRecovery strategy
          enum:
          - FRICTIONLESS
          - CHALLENGE
        code:
          type: string
          description: Code in case of verification code strategy
    BadResponse:
      title: Bad Response
      type: object
      properties:
        code:
          type: string
          description: Status code
          example: '400'
        message:
          type: string
          description: Error message
          example: Validation errors
        causes:
          type: array
          items:
            type: string
          example: '[device.ip must not be blank]'
    TransferDeviceData:
      title: device
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseDeviceData'
    Location:
      title: location
      required:
      - latitude
      - longitude
      type: object
      properties:
        latitude:
          type: number
          description: Device latitude
          format: double
          example: -34.56532789616039
        longitude:
          type: number
          description: Device longitude
          format: double
          example: -58.48945822129388
    Amount:
      title: total_amount
      type: object
      required:
      - currency_code
      - value
      properties:
        currency_code:
          type: string
          description: Three-letter currency code as described in the ISO 4217 international standard
          example: USD
        value:
          type: number
          description: Amount value
          format: bigdecimal
          example: 8008.99
    BaseDeviceData:
      title: device
      type: object
      properties:
        ipv4:
          type: string
          description: The original ipv4 address from the browser. Required if ipv6 is blank
          example: 70.56.69.13
        ipv6:
          type: string
          description: The original ipv6 address from the browser. Required if ipv4 is blank
          example: 2001:0db8:85a3:0000:0000:8a2e:0370:7334
        location:
          $ref: '#/components/schemas/Location'
        merchant_device:
          type: string
          description: Id of the device, identified by the merchant in their internal systems
          example: 234c20c3-45de-41bf-b243-87ad5$RTbc3b
        session_id:
          type: string
          description: Value generated by the javascript/sdk snippet of our device fingerprint solution
          example: 5b8c20c3-45de-41bf-b243-87ad5d21bc3b
    StandardApiResponse:
      title: StandardApiResponse
      type: object
      properties:
        analysis_type:
          type: string
          description: Resolution type
          enum:
          - AUTOMATIC
          - MANUAL
        evaluation_id:
          type: string
          description: antifraud provider identifier
        id:
          type: string
          description: Client transaction identifier
        score:
          type: integer
          description: Evaluation score
        status:
          type: string
          description: Transaction status
          enum:
          - approved
          - denied
          - received
        strategies:
          type: array
          items:
            $ref: '#/components/schemas/StrategyResponse'
    AccountFrom:
      title: account_from
      type: object
      required:
      - user_id
      allOf:
      - $ref: '#/components/schemas/BaseAccount'
    TransactionData:
      title: transaction
      required:
      - reference_id
      - country_code
      - total_amount
      type: object
      properties:
        reference_id:
          type: string
          description: Client transaction identifier
          example: FGCCCEA53JYSHXX
        business_id:
          type: string
          description: Unique identifier for the store where the transaction takes place.
          example: 6LVHR8W0V7BYEQX
        sequence:
          type: string
          description: Sequence number
          example: '1'
        country_code:
          type: string
          description: Use the country code of the store site's location where the transaction takes place. This ensures alignment with the store's geographical context. Two-letter code as described in the ISO 3166 international standard
          example: AR
        total_amount:
          $ref: '#/components/schemas/Amount'
          description: Represents transaction total amount on local currency
        channel:
          type: string
          description: Indicates sales channel
    AccountTo:
      title: account_to
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseAccount'
    WireTransferAntiFraud:
      title: Wire Transfer AntiFraud Data
      required:
      - transaction
      - type
      - account_from
      - account_to
      - order_date
      - transfer_type
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          enum:
          - WireTransfer
          type: string
          description: Antifraud type
          default: WireTransfer
        device:
          $ref: '#/components/schemas/TransferDeviceData'
        store:
          $ref: '#/components/schemas/Store'
        transaction:
          $ref: '#/components/schemas/TransactionData'
        account_from:
          $ref: '#/components/schemas/AccountFrom'
          description: Wire transfer origin account
        account_to:
          $ref: '#/components/schemas/AccountTo'
          description: Wire transfer destination account
        order_date:
          type: string
          description: Date order is issued
          example: '2021-07-23T16:00:00.307062Z'
        execution_date:
          type: string
          description: Date order is actually executed
          example: '2021-07-23T16:00:00.307062Z'
        instant:
          type: boolean
          description: Represents if the transfer will be scheduled or executed now
        transfer_type:
          type: string
          description: Transfer type
          enum:
          - DEPOSIT
          - WITHDRAW
          - TRANSFER
        sla_date:
          type: string
          description: The date that the evaluation is expected to be resolved
          example: '2021-07-23T16:00:00.307062Z'
        callback_url:
          type: string
          description: A publicly accessible HTTPS endpoint where your application will receive asynchronous notifications about the status of the evaluation.
          example: http://domain/service
    BaseAccount:
      title: BaseAccount
      type: object
      required:
      - number
      - bank_name
      - bank_code
      - holder
      properties:
        number:
          type: string
          description: Account number
          example: 0007895241236987
        bank_name:
          type: string
          description: Account bank name
          example: 6LVHR8W0V7BYEQX
        bank_code:
          type: string
          description: Account bank code
          example: '1145'
        holder:
          type: string
          description: Account holder name
          example: Hugo Sconochini
        currency_code:
          type: string
          description: Three-letter currency code as described in the ISO 4217 international standard
          example: USD
        type:
          type: string
          description: Account type
          enum:
          - PERSONAL
          - BUSINESS
        status:
          type: string
          description: Account status
          enum:
          - OK
          - TO_VALIDATE
          - BLOCKED
        creation_date:
          type: string
          description: Account creation date
          example: '2021-07-23T16:00:00.307062Z'
        user_id:
          type: string
          description: User identification
          example: user12
    Store:
      title: store
      type: object
      properties:
        code:
          type: string
          description: Merchant code name
          example: Hellmans
        category:
          type: string
          description: Merchant category name. Four-digit code as described in the ISO 18245 international standard. See [MCC](https://classification.codes/classifications/industry/mcc/)
          example: '0763'