Koin Availability Services API

openapi: 3.0.3
info:
  title: Antifraud Access Availability 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: Availability Services
paths:
  /v1/payment/orders/availability:
    post:
      tags:
      - Availability Services
      summary: Availability
      description: You can use this service to check if the customer is eligible for the "buy now pay later" payment method. The service will return the installment options in case of success. It is available for transparent checkout only.
      operationId: availabilityPOST
      parameters:
      - name: Content-Type
        in: header
        example: application/json
        description: The Media type of the body of the request. Default value for payment provider protocol is application/json
        schema:
          type: string
        required: true
      - name: Accept
        in: header
        example: application/json
        description: Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityRequest'
      responses:
        '200':
          description: Availability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'
              examples:
                Applicable:
                  $ref: '#/components/examples/AvailabilityApplicable'
                Rejected:
                  $ref: '#/components/examples/AvailabilityRejected'
                Undefined:
                  $ref: '#/components/examples/AvailabilityUndefined'
                Error:
                  $ref: '#/components/examples/UnknownError'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation failed:
                  value:
                    code: 400
                    message: Validation failed
                    causes:
                    - transaction.reference_id must not be blank
components:
  schemas:
    AvailabilityResponse:
      title: Availability response
      type: object
      required:
      - status
      - transaction
      - payment_method
      - country_code
      - payer
      properties:
        status:
          type: object
          required:
          - type
          properties:
            type:
              type: string
              enum:
              - Applicable
              - Failed
              description: Availability status.
            reason:
              type: string
              enum:
              - Rejected
              - Undefined
              description: Availability reason.
        store:
          type: object
          properties:
            code:
              type: string
              description: Store identifier.
              example: SBXSTORE
        transaction:
          required:
          - reference_id
          - account
          - amount
          type: object
          properties:
            reference_id:
              type: string
              pattern: ^[a-zA-Z0-9_#.-]{0,50}$
              description: Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
              example: REF0000001
            business_id:
              type: string
              pattern: ^[a-zA-Z0-9_#.-]{0,50}$
              description: Business ID. The ID of the transaction related with this payment.
              example: BIZ0000001
            account:
              type: string
              description: Client account number provided by Koin.
              example: SBX000
            amount:
              required:
              - currency_code
              - value
              type: object
              properties:
                currency_code:
                  type: string
                  pattern: '[A-Z]{3}'
                  description: Currency code (ISO 4217)
                  example: BRL
                value:
                  type: number
                  pattern: d{1,10}.d{2}
                  description: Total amount
                  example: 1500.56
        payment_method:
          required:
          - code
          type: object
          properties:
            code:
              type: string
              description: Payment method code
              example: BNPL
        country_code:
          type: string
          description: Transaction country code.
          example: BR
        payer:
          required:
          - document
          - email
          properties:
            document:
              description: Payer ID
              required:
              - type
              - number
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - cpf
                  description: Payer document type
                number:
                  type: string
                  pattern: ^[0-9]{11}$
                  description: Payer document number
                  example: '54672396002'
            email:
              type: string
              description: Payer email
              example: jhon_doe@domain.com
        installment_options:
          description: Available installment options (when applicable)
          type: array
          items:
            type: object
            required:
            - installments
            - installment_rate
            - installment_amount
            - total_amount
            - first_due_date
            - iof
            - cet
            - cet_am
            - option_id
            properties:
              installments:
                type: integer
                description: Amount of installments
                example: 2
              installment_rate:
                type: number
                pattern: d{1,10}.d{2}
                description: Installment rate
                example: 2.99
              installment_amount:
                type: number
                pattern: d{1,10}.d{2}
                description: Installment amount
                example: 51.5
              total_amount:
                type: number
                pattern: d{1,10}.d{2}
                description: Payment total amount
                example: 103
              first_due_date:
                type: string
                format: date-time
                description: Installment first due date (ISO 8601 date format)
                example: '2022-01-28T00:00:00.000Z'
              iof:
                type: number
                pattern: d{1,10}.d{2}
                description: IOF rate
                example: 26.18
              cet:
                type: number
                pattern: d{1,10}.d{2}
                description: CET rate
                example: 58.17
              cet_am:
                type: number
                pattern: d{1,10}.d{2}
                description: Monthly CET rate
                example: 3.84
              option_id:
                type: string
                description: Installment option identifier
                example: 28567e07-7296-41e7-99f1-e18df9756392
              incoming_percent_value:
                type: number
                pattern: d{1,10}.d{2}
                description: _Entrada_ installment percentage
                example: 1.2
              incoming_value:
                type: number
                pattern: d{1,10}.d{2}
                description: _Entrada_ installment amount
                example: 10.44
              discount:
                type: object
                properties:
                  original_installment_value:
                    type: number
                    description: Original amount before applying the discount
                  value:
                    type: number
                    description: Discount amount
                  percent:
                    type: number
                    description: Discount percentage
              ui:
                type: object
                properties:
                  layout:
                    type: object
                    properties:
                      tags:
                        type: array
                        items:
                          type: string
                        enum:
                        - RECOMMENDED
                        - INTEREST_FREE
                        - ENTRY_REQUIRED
                        - DISCOUNT
                        - FORCED_FIRST_INSTALLMENT
                      highlighted:
                        type: boolean
                      sorted:
                        type: number
                        format: int
                  hints:
                    type: object
                    properties:
                      birthdate:
                        type: object
                        properties:
                          required:
                            type: boolean
        code:
          type: string
          description: Standardized error code (applies only for error cases)
        message:
          type: string
          description: Message associated with the error code (applies only for error cases)
    DestinationService:
      title: DestinationService
      type: object
      required:
      - service
      properties:
        passengers:
          uniqueItems: true
          type: array
          description: List of passengers, required for Travel Insurance
          items:
            $ref: '#/components/schemas/Person'
        service:
          $ref: '#/components/schemas/Service'
      allOf:
      - $ref: '#/components/schemas/Item'
    CarDelivery:
      title: CarDelivery
      type: object
      required:
      - date
      - address
      properties:
        address:
          description: Delivery address
          allOf:
          - $ref: '#/components/schemas/Address'
        date:
          type: string
          description: Delivery date (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
    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
    Passenger:
      title: passenger
      required:
      - first_name
      - last_name
      - document
      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
        phone:
          description: phone
          allOf:
          - $ref: '#/components/schemas/Phone'
    CellphoneInsurance:
      type: object
      title: CellphoneInsurance
      properties:
        client:
          $ref: '#/components/schemas/Client'
        device:
          $ref: '#/components/schemas/Device'
        insurance:
          $ref: '#/components/schemas/Insurance'
      allOf:
      - $ref: '#/components/schemas/Item'
    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'
    PhoneBus:
      title: phone
      required:
      - number
      type: object
      properties:
        country_code:
          type: string
          description: Transaction country code (two-letter ISO 3166 country code)
          example: BR
        area_code:
          type: string
          description: Phone area code
          example: '11'
        number:
          type: string
          description: Phone number
          example: '45669874'
        type:
          type: string
          description: Phone type
          example: Mobile
    Client:
      title: client
      type: object
      allOf:
      - $ref: '#/components/schemas/Person'
    ArrivalBus:
      title: arrival
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseBusData'
    Person:
      title: Person
      type: object
      properties:
        id:
          type: string
          description: Client custom person identifier
          example: c1245228
        first_name:
          type: string
          description: First name. Required if full_name is blank.
          example: Alvaro
        last_name:
          type: string
          description: Last name.  Required if full_name is blank.
          example: Garrincha
        full_name:
          type: string
          description: Full name. Is required if first_name and last_name are blank
          example: Alvaro 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. Required for Ecommerce Antifraud Data
          example: email@domain
        phone:
          description: phone
          allOf:
          - $ref: '#/components/schemas/Phone'
    Fine:
      title: fine
      type: object
      properties:
        car_owning_tax_type:
          type: string
          enum:
          - IPVA
          - SUCIVE
        car_owning_tax_amount:
          allOf:
          - $ref: '#/components/schemas/CarOwningTaxAmount'
          description: Carowning Tax amount
        fine_issued_year:
          type: integer
          description: Fine issued year
          example: '2020'
        insurance_amount:
          allOf:
          - $ref: '#/components/schemas/InsuranceAmount'
          description: Insurance amount
        licesing_amount:
          allOf:
          - $ref: '#/components/schemas/LicesingAmount'
          description: Licesing amount
        penalty_amount:
          allOf:
          - $ref: '#/components/schemas/PenaltyAmount'
          description: Penalty amount
    Student:
      title: student
      required:
      - birth_date
      - email
      - first_name
      - gender
      - last_name
      - relationship_with_payer
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        birth_date:
          type: string
          description: Person birthdate
          example: '1990-05-06'
        document:
          $ref: '#/components/schemas/Document'
        email:
          type: string
          description: Person email contact
          example: email@domain
        first_name:
          type: string
          description: Person first name
          example: Alvaro
        gender:
          type: string
          description: Person gender
          enum:
          - FEMALE
          - MALE
          - OTHER
        id:
          type: string
          description: Person id
          example: c1245228
        last_name:
          type: string
          description: Person last name
          example: Garrincha
        phone:
          description: phone
          allOf:
          - $ref: '#/components/schemas/Phone'
        relationship_with_payer:
          type: string
          description: Student relationship with payer
          example: FATHER
    Service:
      title: Service
      type: object
      required:
      - start_date
      - end_date
      - number_of_passengers
      properties:
        destination:
          type: string
          description: Service destination
          example: Villa Serrana
        end_date:
          type: string
          description: Service end date (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        id:
          type: string
          description: Service id
          example: idddd-eeee
        name:
          type: string
          description: Service name
          example: Cabalgata Villa Serrana
        number_of_passengers:
          type: integer
          example: '10'
          description: Number of passengers
        origin:
          type: string
          description: Service origin
          example: Villa Serrana
        start_date:
          type: string
          description: Service start date (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        sub_type:
          type: string
          description: Service subType
          example: Activity
    Price:
      title: price
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    ArrivalAirport:
      title: arrival
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseAirportData'
    PassengersResume:
      title: PassengersResume
      type: object
      required:
      - adults
      - children
      - infants
      properties:
        adults:
          type: integer
          description: Adults count
          format: int32
          example: 2
        children:
          type: integer
          description: Children count
          format: int32
          example: 2
        infants:
          type: integer
          description: Infants count
          format: int32
          example: 2
    LicesingAmount:
      title: licesing_amount
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    Owner:
      title: owner
      type: object
      allOf:
      - $ref: '#/components/schemas/Person'
    TravelInsuranceProvider:
      title: provider
      type: object
      required:
      - code
      - name
      properties:
        code:
          type: string
          description: Travel insurance provider code
        name:
          type: string
          description: Travel insurance provider name
    AvailabilityRequest:
      title: Availability request
      required:
      - transaction
      - country_code
      - payment_method
      - payer
      - ip_address
      - device_fingerprint
      type: object
      properties:
        store:
          type: object
          properties:
            code:
              type: string
              description: Store identifier
              example: SBXSTORE
        transaction:
          required:
          - reference_id
          - account
          - amount
          type: object
          properties:
            reference_id:
              type: string
              pattern: ^[a-zA-Z0-9_#.-]{0,50}$
              description: Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
              example: REF0000001
            business_id:
              type: string
              pattern: ^[a-zA-Z0-9_#.-]{0,50}$
              description: Business ID. The ID of the transaction related with this payment
              example: BIZ0000001
            account:
              type: string
              description: Client account number provided by Koin
              example: SBX000
            amount:
              required:
              - currency_code
              - value
              type: object
              properties:
                currency_code:
                  type: string
                  pattern: '[A-Z]{3}'
                  description: Currency code (ISO 4217)
                  example: BRL
                value:
                  type: number
                  pattern: d{1,10}.d{2}
                  description: Payment total amount
                  example: 1500.56
        country_code:
          type: string
          description: Transaction country code (two-letter ISO 3166 country code)
          example: BR
        payment_method:
          required:
          - code
          type: object
          properties:
            code:
              type: string
              description: Payment method code
              example: BNPL
        payer:
          required:
          - document
          - email
          properties:
            document:
              description: Payer ID
              required:
              - type
              - number
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - cpf
                  description: Payer document type
                number:
                  type: string
                  pattern: ^[0-9]{11}$
                  description: Payer document number
                  example: '54672396002'
            email:
              type: string
              description: Payer email
              example: jhon_doe@domain.com
        ip_address:
          type: string
          description: Buyer ip address
          example: 192.0.2.146
        device_fingerprint:
          type: string
          description: Represents the device used to initiate the payment
          example: 3f139f92d30d54f1aaf519b3a39a20814
        items:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Generic'
            - $ref: '#/components/schemas/GenericLegacy'
            - $ref: '#/components/schemas/Financing'
            - $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/TransferDS'
            - $ref: '#/components/schemas/Bus'
    PickUp:
      title: pick_up
      type: object
      allOf:
      - $ref: '#/components/schemas/CarDelivery'
    Education:
      title: Education
      type: object
      properties:
        course:
          description: Course details
          allOf:
          - $ref: '#/components/schemas/Course'
        students:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/Student'
      allOf:
      - $ref: '#/components/schemas/Item'
    DropOff:
      title: drop_off
      type: object
      allOf:
      - $ref: '#/components/schemas/CarDelivery'
    BaseBusData:
      title: BaseBusData
      type: object
      required:
      - city
      - state
      - date
      - timezone
      properties:
        city:
          type: string
          description: Address city. It must be either three-letters city code or city name
          example: Rio de Janeiro
        state:
          type: string
          description: Address state. It must be either state code or state name
          example: RJ
        date:
          type: string
          example: '2021-10-23T10:00:00.000Z'
        timezone:
          type: number
          format: int
    Segment:
      title: Segment
      type: object
      properties:
        airline_code:
          type: string
          description: Airline code
          example: AA
        departure:
          description: Departure airport data
          allOf:
          - $ref: '#/components/schemas/DepartureAirport'
        arrival:
          description: Arrival airport data
          allOf:
          - $ref: '#/components/schemas/ArrivalAirport'
        flight_class:
          description: Flight class
          type: string
        flight_number:
          description: Flight number
          type: integer
          example: '123'
        position:
          description: Segment order
          type: integer
          example: '1'
    GenericLegacy:
      title: GenericLegacy
      type: object
      deprecated: true
      required:
      - reference
      - name
      - price
      - quantity
      - discount
      - category
      properties:
        reference:
          type: string
          description: Item identifier
          example: ITM00001
        name:
          type: string
          description: Item name
          example: Pencil
        price:
          required:
          - currency_code
          - value
          type: object
          description: Item price
          properties:
            currency_code:
              type: string
              pattern: '[A-Z]{3}'
              description: Currency code (ISO 4217)
              example: BRL
            value:
              type: number
              pattern: d{1,10}.d{2}
              description: Amount
              example: 1500.56
        quantity:
          type: integer
          description: Item quantity
          example: 10
        discount:
          type: number
          pattern: d{1,10}.d{2}
          description: Item discount
          example: 0.5
        category:
          type: string
          description: Category name
          example: School supplies
    Tour:
      title: Tour
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/TravelInsuranceProvider'
        modality:
          type: string
          description: Tour modality
        description:
          type: string
          description: Description of the product
        passengers_resume:
          $ref: '#/components/schemas/PassengersResume'
      allOf:
      - $ref: '#/components/schemas/DestinationService'
    DepartureBus:
      title: departure
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseBusData'
    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
    Item:
      title: Item
      required:
      - category
      - id
      - name
      - price
      - quantity
      - type
      type: object
      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'
          Transfer: '#/components/schemas/TransferDS'
          Financing: '#/components/schemas/Financing'
          GenericLegacy: '#/components/schemas/GenericLegacy'
          Bus: '#/components/schemas/Bus'
          Subscription: '#/components/schemas/Subscription'
      properties:
        category:
          $ref: '#/components/schemas/Category'
        discount_amount:
          $ref: '#/components/schemas/DiscountAmount'
          description: Item price discount
        id:
          type: string
          description: Item id
          example: '13238487'
        name:
          type: string
          description: item name
          example: Some name
        price:
          $ref: '#/components/schemas/Price'
          description: Item price
        quantity:
          type: integer
          description: Item quantity
          format: int32
          example: 5
        seller_id:
          type: string
          description: Item seller
          example: Some Seller
        service_date:
          type: string
          description: Date which the service will take place (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        type:
          type: string
          description: Item type
          enum:
          - Generic
          - CarRental
          - Lodging
          - Flight
          - Education
          - DestinationService
          - CellphoneInsurance
          - CarPenaltyFee
          - Financing
          - Subscription
          - Bus
    InsuranceAmount:
      title: insurance_amount
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    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 (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        checkout_date:
          type: string
          description: Checkout date (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        guests:
          uniqueItems: true
          description: guests
          type: array
          items:
            $ref: '#/components/schemas/Person'
        lodger:
          description: lodger details
          allOf:
          - $ref: '#/components/schemas/Lodger'
        nights:
          type: integer
          description: Number of nights
          example: '8'
        refundable:
          description: is refundable
          example: 'true'
      allOf:
      - $ref: '#/components/schemas/Item'
    Flight:
      title: Flight
      type: object
      required:
      - id
      - price
      - quantity
      - itinerary_type
      - passengers
      properties:
        discount_amount:
          allOf:
          - $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:
          allOf:
         

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