Koin Ecommerce API

openapi: 3.2.0
info:
  title: Antifraud Access Ecommerce 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: Ecommerce
paths:
  /v1/antifraud/pre-evaluations:
    post:
      tags:
      - Ecommerce
      summary: Create Pre-Evaluation
      description: Receives a new transaction for antifraud analysis, its meant to be used before payment authorization.
      operationId: createPreEvaluationUsingPOST
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EcommerceAntiFraud'
            examples:
              Ecommerce:
                value:
                  buyer:
                    address:
                      city: sao paulo
                      complement: Dsauvybixo
                      country_code: BR
                      neighborhood: Iwewsfjyol
                      number: '1234'
                      state: sao paulo
                      street: One street
                      zip_code: '12345'
                    birth_date: '1980-05-06'
                    document:
                      nationality: BR
                      number: '11123456'
                      type: CPF
                    email: test@gmail.com
                    full_name: Dgvwicjiqr Amdbvqkbja
                    gender: MALE
                    id: '1234'
                    phone:
                      area_code: '1265'
                      number: '12345678'
                      type: MOBILE
                  callback_url: https://postman-echo.com/post
                  device:
                    ipv4: 191.111.186.20
                    location:
                      latitude: -14.11132789616039
                      longitude: -48.44445822129388
                    merchant_device: b3692474-a298-41be-8b1c-938965d5b5ed
                    session_id: 40151f31-dff5-46ab-b6f7-2191bf992003
                  items:
                  - category:
                      id: '17877451306'
                      name: Vtiqzgxlwh
                    discount_amount:
                      currency: USD
                      value: 2344
                    id: '17803811909'
                    name: Aszmxlpebz
                    price:
                      currency: USD
                      value: 8008.99
                    quantity: 3
                    seller_id: '16223265193'
                    service_date: '2023-02-10T13:50:31.000Z'
                    type: Generic
                  payments:
                  - amount:
                      currency: USD
                      value: 8008.99
                    concept: Ergvekrvit Prtldbjwjs
                    details:
                      bin: '424242'
                      brand_name: Visa
                      eci: '123'
                      expiration_month: '03'
                      expiration_year: '2032'
                      last_digits: '4444'
                    id: '12345'
                    installments: 11
                    method: CreditCard
                    payer:
                      address:
                        city: sao paulo
                        complement: Vzeiidkesz
                        country_code: BR
                        full_address: Zluqwxxdhc 10091
                        neighborhood: Fcbcwsgudy
                        state: sao paulo
                        zip_code: '15060'
                      birth_date: '1978-04-29'
                      document:
                        nationality: BR
                        number: '12345678'
                        type: CPF
                      email: test@gmail.com
                      first_name: Spoignvdki
                      gender: OTHER
                      id: '12345'
                      last_name: Rljwjfspta
                      phone:
                        area_code: '123'
                        number: '1234567'
                        type: MOBILE
                    subscription: false
                  service_date: '2023-02-02T13:50:31.000Z'
                  shipping:
                    address:
                      city: sao paulo
                      complement: Vpqbsrobnf
                      country_code: BR
                      full_address: Uychukpruh 10666
                      neighborhood: Pnddnuzvys
                      state: sao paulo
                      zip_code: '18476'
                    delivery:
                      by: DHL
                      date: '2023-02-10T13:50:31.000Z'
                      type: EXPRESS
                    price:
                      currency: USD
                      value: 45.99
                  sla_date: '2023-02-10T13:50:31.000Z'
                  store:
                    category: '17057'
                    code: Hrrnhqqisi
                    latitude: -34.56532789616039
                    longitude: -58.48945822129388
                    merchant_type: shopping
                  transaction:
                    agency_id: AGEN-12345
                    business_id: '1234567'
                    country_code: BR
                    reference_id: '123456'
                    sequence: 1
                    listener_mode: false
                    total_amount:
                      currency: USD
                      value: 8008.99
                  client_info:
                    creation_date: '1978-04-29T17:10:35.387Z'
                    classification: GOLD
                    customer_order:
                      currency_code: USD
                      value: 45.99
                    days_since_first_order: 45
                    days_since_last_order: 10
                    cancelled_orders: 3
                    average_order:
                      currency_code: USD
                      value: 45.99
                    cash_orders: 3
                    card_orders: 6
                    bank_orders: 4
                    debit_orders: 2
                    super_segmentation: potential
                    purchase_power: pph
                    year_first_purchase: 2024
                    purchases_30_days: 12
                    purchases_60_days: 22
                    purchases_lifetime: 32
                  strategies_data:
                    collect_auth_supported: true
                    acquirer_bin: '408956'
                    acquirer: WDP
                    merchant_id: BRLIARLEGAPR
                    mcc: '1234'
                    merchant_descriptor: DAGS_TEST_3DS
                  type: Ecommerce
      responses:
        '200':
          description: Evaluation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardApiPreEvalResponse'
              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" }'
  /v1/antifraud/evaluations:
    post:
      tags:
      - Ecommerce
      summary: Create Evaluation
      description: Receives a new transaction for antifraud analysis, if used with pre-evaluation it should be called after the payment authorization. Its mandatory to reuse the reference_id from pre-evaluation.
      operationId: createEvaluationUsingPOST
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EcommerceAntiFraud'
            examples:
              Ecommerce:
                value:
                  buyer:
                    address:
                      city: sao paulo
                      complement: Dsauvybixo
                      country_code: BR
                      neighborhood: Iwewsfjyol
                      number: '1234'
                      state: sao paulo
                      street: One street
                      zip_code: '12345'
                    birth_date: '1980-05-06'
                    document:
                      nationality: BR
                      number: '11123456'
                      type: CPF
                    email: test@gmail.com
                    full_name: Dgvwicjiqr Amdbvqkbja
                    gender: MALE
                    id: '1234'
                    phone:
                      area_code: '1265'
                      number: '12345678'
                      type: MOBILE
                  callback_url: https://postman-echo.com/post
                  device:
                    ipv4: 191.111.186.20
                    location:
                      latitude: -14.11132789616039
                      longitude: -48.44445822129388
                    merchant_device: b3692474-a298-41be-8b1c-938965d5b5ed
                    session_id: 40151f31-dff5-46ab-b6f7-2191bf992003
                  items:
                  - category:
                      id: '17877451306'
                      name: Vtiqzgxlwh
                    discount_amount:
                      currency: USD
                      value: 2344
                    id: '17803811909'
                    name: Aszmxlpebz
                    price:
                      currency: USD
                      value: 8008.99
                    quantity: 3
                    seller_id: '16223265193'
                    service_date: '2023-02-10T13:50:31.000Z'
                    type: Generic
                  payments:
                  - amount:
                      currency: USD
                      value: 8008.99
                    concept: Ergvekrvit Prtldbjwjs
                    details:
                      bin: '424242'
                      brand_name: Visa
                      eci: '123'
                      expiration_month: '03'
                      expiration_year: '2032'
                      last_digits: '4444'
                    id: '12345'
                    installments: 11
                    method: CreditCard
                    payer:
                      address:
                        city: sao paulo
                        complement: Vzeiidkesz
                        country_code: BR
                        full_address: Zluqwxxdhc 10091
                        neighborhood: Fcbcwsgudy
                        state: sao paulo
                        zip_code: '15060'
                      birth_date: '1978-04-29'
                      document:
                        nationality: BR
                        number: '12345678'
                        type: CPF
                      email: test@gmail.com
                      first_name: Spoignvdki
                      gender: OTHER
                      id: '12345'
                      last_name: Rljwjfspta
                      phone:
                        area_code: '123'
                        number: '1234567'
                        type: MOBILE
                    subscription: false
                  service_date: '2023-02-02T13:50:31.000Z'
                  shipping:
                    address:
                      city: sao paulo
                      complement: Vpqbsrobnf
                      country_code: BR
                      full_address: Uychukpruh 10666
                      neighborhood: Pnddnuzvys
                      state: sao paulo
                      zip_code: '18476'
                    delivery:
                      by: DHL
                      date: '2023-02-10T13:50:31.000Z'
                      type: EXPRESS
                    price:
                      currency: USD
                      value: 45.99
                  sla_date: '2023-02-10T13:50:31.000Z'
                  store:
                    category: '17057'
                    code: Hrrnhqqisi
                    latitude: -34.56532789616039
                    longitude: -58.48945822129388
                    merchant_type: shopping
                  transaction:
                    agency_id: AGEN-12345
                    business_id: '1234567'
                    country_code: BR
                    reference_id: '123456'
                    sequence: 1
                    listener_mode: false
                    total_amount:
                      currency: USD
                      value: 8008.99
                  client_info:
                    creation_date: '1978-04-29T17:10:35.387Z'
                    classification: GOLD
                    customer_order:
                      currency_code: USD
                      value: 45.99
                    days_since_first_order: 45
                    days_since_last_order: 10
                    cancelled_orders: 3
                    average_order:
                      currency_code: USD
                      value: 45.99
                    cash_orders: 3
                    card_orders: 6
                    bank_orders: 4
                    debit_orders: 2
                    super_segmentation: potential
                    purchase_power: pph
                    year_first_purchase: 2024
                    purchases_30_days: 12
                    purchases_60_days: 22
                    purchases_lifetime: 32
                  strategies_data:
                    collect_auth_supported: true
                    acquirer_bin: '408956'
                    acquirer: WDP
                    merchant_id: BRLIARLEGAPR
                    mcc: '1234'
                    merchant_descriptor: DAGS_TEST_3DS
                  type: Ecommerce
      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:
    Financing:
      title: Financing
      type: object
      properties:
        recipient:
          $ref: '#/components/schemas/Recipient'
      allOf:
      - $ref: '#/components/schemas/Item'
      - type: object
        properties:
          type:
            type: string
            enum:
            - Financing
    Phone:
      title: phone
      required:
      - number
      type: object
      properties:
        area_code:
          type: string
          description: Phone area code. If the country code is also available, include the full combination (country code + area code) for better context, though the country code is optional.
          example: '11'
        number:
          type: string
          description: Phone number
          example: '45669874'
        type:
          type: string
          description: Phone type
          example: Mobile
    Insurance:
      title: Insurance
      type: object
      properties:
        expiration_date:
          type: string
          format: 'date-time. Format "yyyy-MM-dd''T''HH:mm:ss.SSS''Z''" as described in the ISO 8601 '
          example: '2021-02-23T14:10:44.307062Z'
        installment:
          type: number
          format: bigdecimal
        subscription_date:
          type: string
          format: 'date-time. Format "yyyy-MM-dd''T''HH:mm:ss.SSS''Z''" as described in the ISO 8601 '
          example: '2021-02-23T14:10:44.307062Z'
        type:
          type: string
    Flight:
      title: Flight
      type: object
      required:
      - id
      - price
      - quantity
      - itinerary_type
      - routes
      - passengers
      properties:
        discount_amount:
          $ref: '#/components/schemas/DiscountAmount'
          description: Item price discount
        id:
          type: string
          description: Item id
          example: '13238487'
        itinerary_type:
          type: string
          description: Itinerary type
          enum:
          - MULTIDESTINATION
          - ONEWAY
          - ROUND_TRIP
        passengers:
          uniqueItems: true
          description: Passengers list
          type: array
          items:
            $ref: '#/components/schemas/Passenger'
        price:
          $ref: '#/components/schemas/Price'
          description: Item price
        quantity:
          type: integer
          description: Item quantity
          format: int32
          example: 5
        route_type:
          type: string
          description: Route type
          enum:
          - DOMESTIC
          - INTERNATIONAL
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
        seller_id:
          type: string
          description: Item seller
          example: Some Seller
    Lodging:
      title: Lodging
      type: object
      required:
      - checkin_date
      - checkout_date
      - nights
      - address
      properties:
        address:
          $ref: '#/components/schemas/Address'
        checkin_date:
          type: string
          description: 'Checkin date. Date format "yyyy-MM-dd''T''HH:mm:ss.SSS''Z''" as described in the ISO 8601 '
          example: '2021-10-02T14:10:44'
        checkout_date:
          type: string
          description: 'Checkout date. Date format "yyyy-MM-dd''T''HH:mm:ss.SSS''Z''" as described in the ISO 8601 '
          example: 2021-11-02T14:10
        guests:
          uniqueItems: true
          description: guests
          type: array
          items:
            $ref: '#/components/schemas/Person'
        lodger:
          description: lodger details
          $ref: '#/components/schemas/Lodger'
        nights:
          type: integer
          description: Number of nights
          example: 8
        refundable:
          type: boolean
          description: is refundable
          example: true
      allOf:
      - $ref: '#/components/schemas/Item'
      - type: object
        properties:
          type:
            type: string
            enum:
            - Lodging
    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]'
    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'
        latitude:
          type: number
          description: Store latitude coordinate
          format: double
          example: -34.56532789616039
        longitude:
          type: number
          description: Store longitude coordinate
          format: double
          example: -58.48945822129388
        merchant_type:
          type: string
          description: Type of merchant or store
          example: shopping
    DropOff:
      title: drop_off
      type: object
      allOf:
      - $ref: '#/components/schemas/CarDelivery'
    UnAuthorizedResponse:
      title: UnAuthorized Response
      type: object
      properties:
        code:
          type: integer
          description: Status code
          example: 401
        message:
          type: string
          description: Error message
          example: Validation errors
    ClientInfo:
      title: Client Information
      type: object
      properties:
        creation_date:
          type: string
          format: date-time
          description: Client creation date
          example: '1978-04-29T17:10:35.387Z'
        classification:
          type: string
          description: Client classification level
          example: GOLD
        customer_order:
          $ref: '#/components/schemas/Amount'
          description: Customer order amount
        days_since_first_order:
          type: integer
          description: Days since first order
          example: 45
        days_since_last_order:
          type: integer
          description: Days since last order
          example: 10
        cancelled_orders:
          type: integer
          description: Number of cancelled orders
          example: 3
        average_order:
          $ref: '#/components/schemas/Amount'
          description: Average order value in six months
        cash_orders:
          type: integer
          description: Number of cash paid orders
          example: 3
        card_orders:
          type: integer
          description: Number of card paid orders
          example: 6
        bank_orders:
          type: integer
          description: Number of bank check paid orders
          example: 4
        debit_orders:
          type: integer
          description: Number of debit paid orders
          example: 2
        super_segmentation:
          type: string
          description: Super segmentation category
          example: potential
        purchase_power:
          type: string
          description: Purchase power classification
          example: pph
        year_first_purchase:
          type: integer
          description: Year of first purchase
          example: 2024
        purchases_30_days:
          type: integer
          description: Number of purchases in last 30 days
          example: 12
        purchases_60_days:
          type: integer
          description: Number of purchases in last 60 days
          example: 22
        purchases_lifetime:
          type: integer
          description: Total lifetime purchases
          example: 32
    CreditCard:
      title: CreditCard
      type: object
      properties:
        installments:
          type: integer
          description: Number of installments.
          format: int32
          example: 12
      allOf:
      - $ref: '#/components/schemas/BaseCardPayment'
    EcommerceAntiFraud:
      title: Ecommerce AntiFraud Data
      required:
      - buyer
      - items
      - payments
      - transaction
      - type
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          enum:
          - Ecommerce
          description: Antifraud type
          default: Ecommerce
        buyer:
          $ref: '#/components/schemas/Buyer'
        device:
          $ref: '#/components/schemas/DeviceData'
        store:
          $ref: '#/components/schemas/Store'
        items:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Generic'
            - $ref: '#/components/schemas/CarRental'
            - $ref: '#/components/schemas/Lodging'
            - $ref: '#/components/schemas/Flight'
            - $ref: '#/components/schemas/Education'
            - $ref: '#/components/schemas/CellphoneInsurance'
            - $ref: '#/components/schemas/CarPenaltyFee'
            - $ref: '#/components/schemas/TravelInsurance'
            - $ref: '#/components/schemas/Tour'
            - $ref: '#/components/schemas/Ticket'
            - $ref: '#/components/schemas/TransferDS'
            - $ref: '#/components/schemas/Financing'
            discriminator:
              propertyName: type
              mapping:
                Generic: '#/components/schemas/Generic'
                CarRental: '#/components/schemas/CarRental'
                Lodging: '#/components/schemas/Lodging'
                Flight: '#/components/schemas/Flight'
                Education: '#/components/schemas/Education'
                CellphoneInsurance: '#/components/schemas/CellphoneInsurance'
                CarPenaltyFee: '#/components/schemas/CarPenaltyFee'
                TravelInsurance: '#/components/schemas/TravelInsurance'
                Tour: '#/components/schemas/Tour'
                Ticket: '#/components/schemas/Ticket'
                Transfer: '#/components/schemas/TransferDS'
                Financing: '#/components/schemas/Financing'
        payments:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Cash'
            - $ref: '#/components/schemas/CreditCard'
            - $ref: '#/components/schemas/GiftCard'
            - $ref: '#/components/schemas/DebitCard'
            - $ref: '#/components/schemas/PrePaidCard'
            - $ref: '#/components/schemas/PIX'
            - $ref: '#/components/schemas/Wallet'
            - $ref: '#/components/schemas/Points'
            - $ref: '#/components/schemas/Promissory'
            - $ref: '#/components/schemas/Transfer'
            - $ref: '#/components/schemas/Asynchronous'
            discriminator:
              propertyName: method
        shipping:
          $ref: '#/components/schemas/Shipping'
        transaction:
          $ref: '#/components/schemas/TransactionData'
        service_date:
          type: string
          description: Date which the service will take place
          example: '2021-10-23T10:00:00.307062Z'
        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
        client_info:
          $ref: '#/components/schemas/ClientInfo'
          description: Client information and historical data
        strategies_data:
          $ref: '#/components/schemas/StrategiesData'
          description: Optional data for fraud prevention strategies
    Route:
      title: route
      type: object
      required:
      - segments
      properties:
        position:
          type: integer
        provider:
          type: string
          description: Route provider
        segments:
          uniqueItems: true
          type: array
          description: Route segments list
          items:
            $ref: '#/components/schemas/Segment'
    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 to enumerate retries
          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
        listener_mode:
          type: boolean
          description: Indicates if the transaction is in listener mode. When `true`, the transaction is processed for data collection and model training purposes only, and the evaluation result is always ACCEPT.
          example: true
        total_amount:
          $ref: '#/components/schemas/Amount'
          description: Represents transaction total amount on local currency
        redirected:
          type: boolean
          description: Represents if the payment had a redirection
        asynchronous:
          title: asynchronous
          type: boolean
          description: Indicates if corresponds to the second asynchronous evaluation
        channel:
          type: string
          description: Represents sales channel
        business_unit:
          type: string
          description: Represents business unit or business model
        agency_id:
          type: string
          description: Represents the identifier of the agency for sales of external sellers
        mode:
          type: string
          description: Represents the sale mode
          enum:
          - OFFLINE
          - ONLINE
    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
    GiftCard:
      title: GiftCard
      properties:
        id:
          type: string
          description: Payment unique identifier
          example: 02BF653185664752AA5F8B7415BD5043
        method:
          type: string
          description: Payment method used for the buyer
          enum:
          - Cash
          - CreditCard
          - DebitCard
          - Pix
          - Wallet
          - GiftCard
          - Points
          - Promissory
        amount:
          $ref: '#/components/schemas/PaymentAmount'
          description: Payment amount
      allOf:
      - $ref: '#/components/schemas/Payment'
    CarRental:
      title: CarRental
      type: object
      properties:
        car_category:
          type: string
        car_description:
          type: string
        company_name:
          type: string
        drivers:
          type: array
          items:
            $ref: '#/components/schemas/Person'
        drop_off:
          $ref: '#/components/schemas/DropOff'
        pick_up:
          $ref: '#/components/schemas/PickUp'
      allOf:
      - $ref: '#/components/schemas/Item'
      - type: object
        properties:
          type:
            type: string
            enum:
            - CarRental
    Address:
      title: address
      required:
      - city
      - country_code
      - state
      type: object
      properties:
        city:
          type: string
          description: Address city. It must be either three-letters ci

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/koin/refs/heads/main/openapi/koin-ecommerce-api-openapi.yml