Koin Payment Service Provider API

openapi: 3.2.0
info:
  title: Antifraud Access Payment Service Provider 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: Payment Service Provider
paths:
  /v1/antifraud/evaluations:
    post:
      tags:
      - Payment Service Provider
      summary: Create Evaluation
      description: Receives a new transaction for antifraud analysis.
      operationId: createEvaluationUsingPOST
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAntiFraud'
            examples:
              Payment:
                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
                    terminal_id: e2b9198407134463a2ccd8439c0acf02
                  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
                    seller:
                      document:
                        nationality: BR
                        number: '98765432100'
                        type: CPF
                      email: seller@domain.com
                      full_name: Seller Name
                      id: seller-1234
                      phone:
                        area_code: '11'
                        number: '987654321'
                        type: MOBILE
                  transaction:
                    agency_id: AGEN-12345
                    business_id: '1234567'
                    country_code: BR
                    reference_id: '123456'
                    sequence: 1
                    listener_mode: false
                    origin: API
                    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: Payment
      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]'
    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'
    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
        origin:
          type: string
          description: Represents the transaction origin
          enum:
          - API
          - LINK
          - TAP_TO_PAY
          example: API
    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 ID 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'
      - title: GiftCard
        required:
        - method
        - amount
        type: object
        properties:
          id:
            type: string
            description: Payment ID 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
    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 city code or city name
          example: Buenos Aires
        complement:
          type: string
          description: Address complement
          example: Complemento
        country_code:
          type: string
          description: Address country. Two-letter code as described in the ISO 3166 international standard
          example: AR
        neighborhood:
          type: string
          description: Address neighborhood
          example: Chacarita
        number:
          type: string
          description: Address number
          example: '2459'
        state:
          type: string
          description: Address state. It must be either state code or state name
          example: Buenos Aires
        street:
          type: string
          description: Address street
          example: Corrientes
        zip_code:
          type: string
          description: Address zip code
          example: '1425'
        full_address:
          type: string
          description: Full address
          example: Corrientes 747, San Nicolas
    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
    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
    CarIdentifier:
      title: car_identifier
      type: object
      properties:
        key:
          type: string
          description: Car identifier key
          example: RENAVAM
        value:
          type: string
          description: Car identifier value
          example: AA2123
    Course:
      title: course
      type: object
      properties:
        category:
          type: string
        end_date:
          type: string
          description: 'Course end date. Format "yyyy-MM-dd''T''HH:mm:ss.SSS''Z''" as described in the ISO 8601 '
          example: '2021-02-23T14:10:44.307062Z'
        link:
          type: string
          description: Course link
          example: https://link
        monthly_fee:
          type: number
          description: Course monthly fee
          example: '245.12'
        name:
          type: string
        presential:
          type: boolean
        scholarship_percentage:
          type: integer
          description: Course scholarship percentage
          example: 20
        start_date:
          type: string
          description: 'Course start date. Format "yyyy-MM-dd''T''HH:mm:ss.SSS''Z''" as described in the ISO 8601 '
          example: 2021-012-23T14:10:44.307062Z
        subcategory:
          type: string
    StrategiesData:
      title: Strategies Data
      type: object
      description: Optional data for fraud prevention strategies
      properties:
        collect_auth_supported:
          type: boolean
          description: Indicates if collect authentication is supported
          example: true
        acquirer_bin:
          type: string
          description: Acquirer Bank Identification Number
          example: '408956'
        acquirer:
          type: string
          description: Acquirer identifier
          example: WDP
        merchant_id:
          type: string
          description: Merchant identifier
          example: BRLIARLEGAPR
        mcc:
          type: string
          description: Merchant Category Code
          example: '1234'
        merchant_descriptor:
          type: string
          description: Merchant descriptor
          example: DAGS_TEST_3DS
    Category:
      title: category
      required:
      - name
      type: object
      properties:
        id:
          type: string
          description: Item category id
          example: '111'
        name:
          type: string
          description: Item category name
          example: Some category name
    Passenger:
      title: passenger
      required:
      - first_name
      - last_name
      type: object
      properties:
        id:
          type: string
          description: Person id
          example: c1245228
        first_name:
          type: string
          description: First name
          example: Alvaro
        last_name:
          type: string
          description: Last name
          example: Garrincha
        document:
          $ref: '#/components/schemas/Document'
        gender:
          type: string
          description: Gender
          enum:
          - FEMALE
          - MALE
          - OTHER
        address:
          $ref: '#/components/schemas/Address'
        birth_date:
          type: string
          description: Birthdate
          example: '1990-05-06'
        email:
          type: string
          description: Email contact
          example: email@domain.com
        phone:
          description: phone
          $ref: '#/components/schemas/Phone'
    Wallet:
      title: Wallet
      required:
      - method
      - amount
      - provider
      type: object
      properties:
        method:
          type: string
          description: Payment method used for the buyer
          enum:
          - Wallet
        payer:
          $ref: '#/components/schemas/Payer'
          description: Payer Required for Ecommerce Antifraud Data. Required for Payment Antifraud Data if buyer is blank.
        amount:
          $ref: '#/components/schemas/PaymentAmount'
          description: Payment amount
        provider:
          type: string
          description: Wallet provider
          enum:
          - APPLE_PAY
          - GOOGLE_PAY
          - NUPAY
          - IFOOD_PAY
          example: APPLE_PAY
    Education:
      title: Education
      type: object
      properties:
        course:
          description: Course details
          $ref: '#/components/schemas/Course'
        students:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/Student'
      allOf:
      - $ref: '#/components/schemas/Item'
      - type: object
        properties:
          type:
            type: string
            enum:
            - Education
    Buyer:
      title: buyer
      type: object
      allOf:
      - $ref: '#/components/schemas/PersonBuyer'
    Car:
      title: car
      type: object
      properties:
        brand:
          type: string
          description: Car brand
          example: Tesla
        identifier:
          $ref: '#/components/schemas/CarIdentifier'
        license_plate:
          type: string
          description: license plate
          example: AAM 2312
        model:
          type: string
          description: Car model
          example: '3'
        owner:
          $ref: '#/components/schemas/Owner'
        year:
          type: string
          description: Car year
          example: '2018'
    TravelInsurance:
      title: TravelInsurance
      type: object
      required:
      - provider
      - region
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        modality:
          type: string
          description: Travel insurance modality
        region:
          type: string
          description: Travel insurance region
          example: NATIONAL
          enum:
          - NATIONAL
          - EUROPE
          - UNITED_STATES
          - LATIN_AMERICA
          - MULTI_DESTINATION
          - OTHER
      allOf:
      - $ref: '#/components/schemas/DestinationService'
      - type: object
        properties:
          type:
            type: string
            enum:
            - TravelInsurance
    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'
    DestinationService:
      title: DestinationService
      type: object
      required:
      - service
      - passengers
      properties:
        passengers:
          uniqueItems: true
          type: array
          description: List of passengers
          items:
            $ref: '#/components/schemas/Person'
        service:
          $ref: '#/components/schemas/Service'
      allOf:
      - $ref: '#/components/schemas/Item'
    Transfer:
      title: Transfer
      type: object
      required:
      - accountNumber
      - bankName
      properties:
        accountNumber:
          type: string
          description: Transfer account number
          example: '235687943672'
        bankName:
          type: string
          description: Transfer bank name
          example: ITAU
        payer:
          $ref: '#/components/schemas/Payer'
          description: Payer Required for Ecommerce Antifraud Data. Required for Payment Antifraud Data if buyer is blank.
      allOf:
      - $ref: '#/components/schemas/Payment'
    Profile:
      title: Profile
      type: object
      properties:
        category:
          type: string
          description: Customer level for example Free, Basic, Pro, Gold, etc
          example: Platinum
    Asynchronous:
      title: Asynchronous
      type: object
      properties:
        payment_data:
          $ref: '#/components/schemas/AsyncPaymentDetail'
        amount:
          $ref: '#/components/schemas/PaymentAmount'
          description: Payment amount. Do not include when payment_data method is CreditCard or DebitCard.
      allOf:
      - $ref: '#/components/schemas/Payment'
    Device:
      title: Device
      type: object
      properties:
        brand:
         

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