Koin Support Services API

openapi: 3.0.3
info:
  title: Antifraud Access Support Services 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: Support Services
paths:
  /v1/antifraud/evaluations/{id}:
    get:
      tags:
      - Support Services
      summary: Retrieve Evaluation Status
      description: API to retrieve the status of an antifraud evaluation.
      operationId: evaluationStatusUsingGET
      parameters:
      - name: id
        in: path
        description: Could be either Evaluation ID returned by api on evaluation :evaluation_id or reference id sent by client on evaluation :store.reference_id
        required: true
        style: simple
        schema:
          type: string
      - name: field
        in: query
        description: Indicates which field should be used to look up the case (evalaution_id or reference_id). By default its value is EVALUATION_ID.
        required: false
        schema:
          type: string
          enum:
          - EVALUATION_ID
          - REFERENCE_ID
          default: EVALUATION_ID
      responses:
        '200':
          description: Antifraud analysis status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardApiResponse'
              examples:
                Evaluation Response:
                  value: '{"id": "05OBS9CRU0VNKZ9","evaluation_id": "70691872-f9a8-40c5-952a-72f79b32733b","status": "approved","score": 0,"analysis_type": "automatic"}'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                Bad Request:
                  value: '{ "code": 400, "message": "field must be in [EVALUATION_ID, REFERENCE_ID]" }'
        '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." }'
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value: '{ "code": 404, "message": "Case not found for id 123456 and idName REFERENCE_ID" }'
        '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" }'
      x-readme:
        samples-enabled: false
    delete:
      tags:
      - Support Services
      summary: Cancel Evaluation
      description: 'API to notify if the order was canceled either by the store or the buyer before completition of the Antifraud analysis.

        The query parameter in the URL :id Could be either Evaluation ID returned by api on evaluation :evaluationId or reference id sent by client on evaluation :store.referenceId'
      operationId: cancelEvaluationUsingDELETE
      parameters:
      - name: id
        in: path
        description: Could be either Evaluation ID returned by api on evaluation :evaluation_id or reference id sent by client on evaluation :store.reference_id
        required: true
        style: simple
        schema:
          type: string
      - name: field
        in: query
        description: Indicates which field should be used to look up the case (evalaution_id or reference_id). By default its value is EVALUATION_ID.
        required: false
        schema:
          type: string
          enum:
          - EVALUATION_ID
          - REFERENCE_ID
          default: EVALUATION_ID
      responses:
        '200':
          description: Cancel response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardApiCancelResponse'
              examples:
                Cancel:
                  value: '{"id": "05OBS9CRU0VNKZ9","evaluation_id": "70691872-f9a8-40c5-952a-72f79b32733b","status": "denied"}'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                Bad Request:
                  value: '{ "code": 400, "message": "field must be in [EVALUATION_ID, REFERENCE_ID]" ] }'
        '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." }'
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value: '{ "code": 404, "message": "Case not found for id 123456 and idName REFERENCE_ID" }'
        '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" }'
      x-readme:
        samples-enabled: false
  /v1/antifraud/notifications/{id}:
    patch:
      tags:
      - Support Services
      summary: Send Notifications
      description: "API to send notifications about an evaluated transaction.\nThe types of notifications:\n- RFI: Notify a request for information (internal, from a bank, or from any entity)\n- Chargeback: Notify a chargeback (internal, from a bank, or from any entity)\n- Status \n   - Collected: Transaction payment was settled\n   - Not Collected: Transaction payments was failed\n   - Cancelled: Transaction was cancelled\n   - Finalized: Transaction finalized OK\n   - Refunded: Transaction payment was refunded\n   - Authorized: Transaction payment was authorized\n   - Recovering: In case a strategy has been applied, informs the result. See [Strategies](https://api-koin.readme.io/reference/strategies)\n- Info: Other type of information"
      operationId: sendEvaluationUpdatesUsingPATCH
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AntiFraudNotification'
            examples:
              Chargeback:
                value:
                  type: CHARGEBACK
                  notification_date: '2021-02-23T14:10:44.307Z'
                  message: Notification about...
                  sub_type: FRAUD
              RFI:
                value:
                  type: RFI
                  sub_type: FRAUD
                  message: Notification about...
                  notification_date: '2021-02-23T14:10:44.307Z'
              Info:
                value:
                  type: INFO
                  message: Notification about...
                  notification_date: '2021-02-23T14:10:44.307Z'
              Status:
                value:
                  type: STATUS
                  sub_type: COLLECTED
                  authorization_code: '123456'
                  payment_id: '123456'
                  message: Notification about...
                  notification_date: '2021-02-23T14:10:44.307Z'
              Recovering:
                value:
                  type: STATUS
                  sub_type: RECOVERING
                  strategies:
                  - type: VerificationCode
                    results:
                    - channel: Mail
                      status: Accept
                  message: Notification about...
                  notification_date: '2021-02-23T14:10:44.307062Z'
              Refunded:
                value:
                  type: STATUS
                  sub_type: REFUNDED
                  full: true
                  message: Notification about...
                  notification_date: '2021-02-23T14:10:44.307Z'
      parameters:
      - name: id
        in: path
        description: Could be either Evaluation ID returned by api on evaluation :evaluation_id or reference id sent by client on evaluation :store.reference_id
        required: true
        style: simple
        schema:
          type: string
      - name: field
        in: query
        description: Indicates which field should be used to look up the case (evalaution_id or reference_id). By default its value is EVALUATION_ID.
        required: false
        schema:
          type: string
          enum:
          - EVALUATION_ID
          - REFERENCE_ID
          default: EVALUATION_ID
      responses:
        '200':
          description: Notifications response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                Bad Request:
                  value: '{ "code": 400, "message": "Validation errors", "causes": [ "type 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." }'
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value: '{ "code": 404, "message": "Case not found for id 123456 and idName REFERENCE_ID" }'
        '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" }'
      x-readme:
        samples-enabled: false
  /v1/antifraud/healthCheck:
    get:
      tags:
      - Support Services
      summary: Service Health Check
      description: API to get information about the server health
      operationId: healthCheckUsingGET
      responses:
        '200':
          description: HealthCheck response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
              examples:
                OK:
                  value: '{"message": "N/A","status": "OK","version": "unknown"}'
                Error:
                  value: '{"message": "N/A","status": "ERROR","version": "unknown"}'
components:
  schemas:
    UnAuthorizedResponse:
      title: UnAuthorized Response
      type: object
      properties:
        code:
          type: integer
          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
    AntiFraudNotification:
      title: notification
      type: object
      required:
      - type
      - notification_date
      discriminator:
        propertyName: type
        mapping:
          CHARGEBACK: '#/components/schemas/ChargebackNotification'
          INFO: '#/components/schemas/InfoNotification'
          STATUS: '#/components/schemas/StatusNotification'
          RFI: '#/components/schemas/RFINotification'
      oneOf:
      - $ref: '#/components/schemas/ChargebackNotification'
      - $ref: '#/components/schemas/InfoNotification'
      - $ref: '#/components/schemas/StatusNotification'
      - $ref: '#/components/schemas/RFINotification'
      properties:
        type:
          type: string
          description: Notification type
          enum:
          - CHARGEBACK
          - INFO
          - STATUS
          - RFI
    ImageNotification:
      title: ImageNotification
      type: object
      properties:
        document_id:
          type: string
          description: Image identifier
          example: '123456789'
        category:
          type: string
          description: Image category
          example: IDENTITY_CARD_FRONT
        url:
          type: string
          description: Image url
          example: https://url.com/1.jpeg
        created:
          type: string
          description: Image created date
          example: '2021-02-23T14:10:44.307062Z'
    BadResponse:
      title: Bad Response
      type: object
      properties:
        code:
          type: integer
          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]'
    StrategiesNotification:
      title: StrategiesNotification
      type: object
      properties:
        type:
          type: string
          description: Strategy type
          enum:
          - DocumentScan
          - VerificationCode
          - CollectAuthRecovery
        results:
          type: array
          items:
            $ref: '#/components/schemas/ResultsNotification'
    RFINotification:
      required:
      - type
      - notification_date
      title: RFI
      type: object
      properties:
        type:
          type: string
          description: Notification Type
          enum:
          - RFI
          default: RFI
        sub_type:
          type: string
          description: Notification subtype
          enum:
          - FRAUD
          - NON_FRAUD
          - PENDING
        message:
          type: string
          description: Descriptive message about notification
          example: Notification about...
        notification_date:
          type: string
          description: Notification date
          example: '2021-02-23T14:10:44.307062Z'
        details:
          type: object
          description: Notification details. It's a set of key/value pairs
          additionalProperties:
            type: string
    InfoNotification:
      required:
      - type
      - notification_date
      title: INFO
      type: object
      properties:
        type:
          type: string
          description: Notification Type
          enum:
          - INFO
          default: INFO
        message:
          type: string
          description: Descriptive message about notification
          example: Notification about...
        notification_date:
          type: string
          description: Notification date
          example: '2021-02-23T14:10:44.307062Z'
        details:
          type: object
          description: Notification details. It's a set of key/value pairs
          additionalProperties:
            type: string
    HealthCheckResponse:
      title: Health check response
      type: object
      properties:
        message:
          type: string
          description: response message
          example: N/A
        status:
          type: string
          description: Health Status
          enum:
          - OK
          - ERROR
        version:
          type: string
          description: application version
          example: unknown
    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'
    StandardApiCancelResponse:
      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
        message:
          type: string
          description: Response message applies only for error cases
        status:
          type: string
          description: Transaction status
          enum:
          - approved
          - denied
          - received
    StatusNotification:
      title: STATUS
      type: object
      required:
      - type
      - notification_date
      - sub_type
      properties:
        type:
          type: string
          description: Notification Type
          enum:
          - STATUS
          default: STATUS
        sub_type:
          type: string
          description: Notification subtype
          enum:
          - COLLECTED
          - NOT_COLLECTED
          - CANCELLED
          - FINALIZED
          - RECOVERING
          - REFUNDED
          - AUTHORIZED
        message:
          type: string
          description: Descriptive message about notification
          example: Notification about...
        notification_date:
          type: string
          description: Notification date
          example: '2021-02-23T14:10:44.307062Z'
        details:
          type: object
          description: Notification details. It's a set of key/value pairs
          additionalProperties:
            type: string
        reason:
          type: string
          description: Reason for the notification. Applies to CANCELLED and NOT_COLLECTED sub_types. For CANCELLED sub_type, allowed values are COLLECT_ERROR, REQUESTED_BY_CUSTOMER, REQUESTED_BY_COMMERCE. For NOT_COLLECTED sub_type, it is a free text field.
          example: COLLECT_ERROR
        suspect:
          type: boolean
          description: Indicates whether the transaction is suspected of fraud. Applies to NOT_COLLECTED sub_type.
          example: true
        authorization_code:
          type: string
          description: Authorization code. Applies to COLLECTED sub_type.
          example: '123456'
        payment_id:
          type: string
          description: Payment Identifier. Applies to COLLECTED sub_type.
          example: '123456'
        full:
          type: boolean
          description: Indicates if it is a full refund. Applies to REFUNDED sub_type.
          example: true
        strategies:
          type: array
          description: Strategies applied. Applies to RECOVERING sub_type.
          items:
            $ref: '#/components/schemas/StrategiesNotification'
    ResultsNotification:
      title: ResultsNotification
      type: object
      properties:
        channel:
          type: string
          description: Channel applied to strategy
          example: Mail
        provider:
          type: string
          description: Provider for the strategy. Used in case of CollectAuthRecovery strategy
          enum:
          - 3DS2
        mode:
          type: string
          description: Mode for the strategy. Used in case of CollectAuthRecovery strategy
          enum:
          - FRICTIONLESS
          - CHALLENGE
        status:
          type: string
          description: 'Strategy status '
          enum:
          - Accept
          - Reject
        reason:
          type: string
          description: Extra additional information of the strategy applied
        images:
          type: array
          items:
            $ref: '#/components/schemas/ImageNotification'
    ChargebackNotification:
      required:
      - type
      - notification_date
      title: CHARGEBACK
      type: object
      properties:
        type:
          type: string
          description: Notification Type
          enum:
          - CHARGEBACK
          default: CHARGEBACK
        sub_type:
          type: string
          description: Notification subtype
          enum:
          - FRAUD
          - NON_FRAUD
          - PENDING
        message:
          type: string
          description: Descriptive message about notification
          example: Notification about...
        notification_date:
          type: string
          description: Notification date
          example: '2021-02-23T14:10:44.307062Z'
        details:
          type: object
          description: Notification details. It's a set of key/value pairs
          additionalProperties:
            type: string