Koin Availability Services API

openapi: 3.2.0
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:
    RouteBus:
      title: Route bus
      type: object
      required:
      - position
      - company_name
      - departure
      - arrival
      properties:
        position:
          type: integer
        company_name:
          type: string
          description: Company name
        departure:
          description: Departure segment data
          allOf:
          - $ref: '#/components/schemas/DepartureBus'
        arrival:
          description: Arrival segment data
          allOf:
          - $ref: '#/components/schemas/ArrivalBus'
    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
    PickUp:
      title: pick_up
      type: object
      allOf:
      - $ref: '#/components/schemas/CarDelivery'
    Course:
      title: course
      type: object
      properties:
        category:
          type: string
        end_date:
          type: string
          description: Course end date (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        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 (In ISO 8601 format with UTC in GMT 0)
          example: '2021-01-01T00:00:00.000Z'
        subcategory:
          type: string
    Document:
      title: document
      required:
      - number
      - type
      type: object
      description: Document is required for Payment Antifraud Data if payment method is Redirection and email is blank.
      properties:
        nationality:
          type: string
          description: Person nationality. Two-letter country code as described in the ISO 3166 international standard
          example: UY
        number:
          type: string
          description: Person document number
          example: '35645888'
        type:
          type: string
          description: Person document type
          example: DNI
    Financing:
      title: Financing
      type: object
      required:
      - price
      - quantity
      - service_date
      - type
      properties:
        recipient:
          title: Financing recipient
          type: object
          properties:
            full_name:
              type: string
              maxLength: 100
              description: Recipient full name.
              example: Jhon Doe Jones
            email:
              type: string
              description: Recipient email
              example: jhon_doe@domain.com
            emv:
              type: string
              description: PIX QR code information, translated to a string
              example: 00020126360014BR.GOV.BCB.PIX0114+55123456789105204000053039865406100.005802BR5908John Doe6009San Pablo6210050698765463049667
            document:
              description: Recipient ID
              required:
              - type
              - number
              type: object
              properties:
                type:
                  type: string
                  description: Recipient document type
                  example: cpf
                number:
                  type: string
                  description: Recipient document number
                  example: '54672396002'
                nationality:
                  type: string
                  description: Recipient nationality (two-letter ISO 3166 country code)
                  example: BR
            phone:
              required:
              - area
              - number
              type: object
              properties:
                country_code:
                  type: string
                  description: Country code
                  example: '+55'
                area:
                  type: string
                  description: Area code
                  example: '11'
                number:
                  type: string
                  description: Phone number
                  example: '984565666'
                type:
                  type: string
                  description: Phone type.
                  example: Mobile
            account:
              type: object
              properties:
                ispb:
                  type: string
                  description: Brazilian Payment System Identifier (eight-number length).
                  example: 12345678
                agency:
                  type: string
                  description: Agency of the account.
                  example: 1500
                code:
                  type: string
                  description: Payer account number.
                  example: 123456789
                type:
                  type: string
                  description: Payer account type.
                  example: CC
            bank:
              type: object
              properties:
                name:
                  type: string
                  example: Bank name
                  description: Bank.
        price:
          allOf:
          - $ref: '#/components/schemas/Price'
          description: Item price
        quantity:
          type: integer
          description: Item quantity
          format: int32
          example: 5
        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:
          - Financing
    Category:
      title: category
      required:
      - id
      - name
      type: object
      properties:
        id:
          type: string
          description: Item category id
          example: '111'
        name:
          type: string
          description: Item category name
          example: Some category name
    Phone:
      title: phone
      required:
      - number
      type: object
      properties:
        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
    ArrivalBus:
      title: arrival
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseBusData'
    Owner:
      title: owner
      type: object
      allOf:
      - $ref: '#/components/schemas/Person'
    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'
    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
    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'
    PassengerBus:
      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/PhoneBus'
    ErrorResponse:
      title: Error Response
      type: object
      properties:
        code:
          type: string
          description: Standardized error code.
        message:
          type: string
          description: Error message.
        causes:
          type: array
          description: List of error causes.
          items:
            type: string
    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
    Insurance:
      title: Insurance
      type: object
      properties:
        expiration_date:
          type: string
          format: date-time
        installment:
          type: number
          format: bigdecimal
        subscription_date:
          type: string
          format: date-time
        type:
          type: string
    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:
          - $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 (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'
    Bus:
      title: Bus
      type: object
      required:
      - id
      - price
      - quantity
      - itinerary_type
      - passengers
      - routes
      - type
      properties:
        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/PassengerBus'
        price:
          allOf:
          - $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/RouteBus'
        type:
          type: string
          description: Item type
          enum:
          - Bus
    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
    DropOff:
      title: drop_off
      type: object
      allOf:
      - $ref: '#/components/schemas/CarDelivery'
    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'
    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
    Generic:
      title: Generic
      type: object
      allOf:
      - $ref: '#/components/schemas/Item'
    TransferDS:
      title: Transfer
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/TravelInsuranceProvider'
        modality:
          type: string
          description: Transfer modality
        description:
          type: string
          description: Description of the product
        passengers_resume:
          $ref: '#/components/schemas/PassengersResume'
      allOf:
      - $ref: '#/components/schemas/DestinationService'
    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'
    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
    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
    DepartureAirport:
      title: departure
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseAirportData'
    Price:
      title: price
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    PenaltyAmount:
      title: penalty_amount
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    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'
    LicesingAmount:
      title: licesing_amount
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    Client:
      title: client
      type: object
      allOf:
      - $ref: '#/components/schemas/Person'
    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'
    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'
    Route:
      title: route
      type: object
      properties:
        position:
          type: integer
        provider:
          type: string
          description: Route provider
        segments:
          uniqueItems: true
          type: array
          description: Route segments list
          items:
            $ref: '#/components/schemas/Segment'
    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:
            

# --- 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