Koin Onboarding Services API

openapi: 3.0.3
info:
  title: Antifraud Access Onboarding 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: Onboarding Services
  description: Onboarding Service
paths:
  /v1/onboarding:
    post:
      tags:
      - Onboarding Services
      summary: Send Data
      description: Receives a new onboarding data.
      operationId: evaluationUsingPOST
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingRequest'
            examples:
              Store:
                value:
                  store:
                    name: Test 93
                    countryCode: AR
                    documentType: CPF
                    document: '12345678'
                  contacts:
                  - contact: test@example.com
                    type: EMAIL
                    roles:
                    - REPORT
                    - SUPPORT
                  payments:
                  - paymentMethod:
                    - CARD
                    - PIX
                    personData:
                      firstName: Jhon
                      lastName: Doe
                      email: test@example.com
                      cpf: '12345678'
                      birthDate: '1984-10-28'
                      countryCode: '55'
                      phone: (11)99123456
                      mcc: '8999'
                      address:
                        address: Street 12, Oregon
                        number: '12'
                        cep: '29115827'
                      revenue: '80000'
                    companyData:
                      name: KOIN
                      cnpj: '123456'
                      address:
                        address: Street 12, Oregon
                        number: '12'
                        cep: '29115827'
                      email: koin@koin.com.br
                      countryCode: '55'
                      phone: (11)99123456
                      mcc: '8999'
                      revenue: '50054'
                    transferData:
                      period: D2
                      accountType: CCAC
                      account: '12345567'
                      bank: John Doe
                      code: '001'
                      branch: '0015'
                      documentType: CNPJ
                      documentNumber: '123456'
                  transaction:
                    referenceId: '123456'
                    callbackUrl: http://cnd-backend/test
      responses:
        '200':
          description: Onboarding response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardApiResponse'
              examples:
                example-0:
                  value: "{\n    \"onboardingId\": \"d46ef4fc-32fd-4fbe-880b-eaa6d6dbd377\",\n    \"referenceId\": \"123456\",\n    \"status\": \"PENDING\"\n}"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                example-0:
                  value: "{\n    \"errorMessage\": \"Request without commerce\",\n    \"error\": \"null\"\n}"
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                example-0:
                  value: "{\n    \"errorMessage\": \"Request without commerce\",\n    \"error\": \"null\"\n}"
      x-readme:
        samples-enabled: false
  /v1/onboarding/{id}:
    get:
      tags:
      - Onboarding Services
      summary: Get Status
      description: API to get the status of the onboarding
      operationId: onboardingStatusUsingGET
      parameters:
      - name: id
        in: path
        description: Either evaluation ID returned by api on evaluation or reference id sent by client on evaluation
        required: true
        style: simple
        schema:
          type: string
      - name: field
        in: query
        description: Name that indicates which id we are going to use to look up the case (onboarding_id or reference_id). Optional and by default its value is onboarding_id. When uses a reference_id the query param "field" must be added with the value REFERENCE_ID.
        required: false
        schema:
          type: string
          enum:
          - ONBOARDING_ID
          - REFERENCE_ID
          default: REFERENCE_ID
      responses:
        '200':
          description: Antifraud analysis status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardApiResponse'
              examples:
                example-0:
                  value: "{\n    \"onboardingId\": \"d46ef4fc-32fd-4fbe-880b-eaa6d6dbd377\",\n    \"referenceId\": \"123456\",\n    \"status\": \"PENDING\"\n}"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                example-0:
                  value: "{\n    \"errorMessage\": \"Request without commerce\",\n    \"error\": \"null\"\n}"
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                example-0:
                  value: "{\n    \"errorMessage\": \"Onboarding 12345678 not found\",\n    \"error\": \"null\"\n}"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadResponse'
              examples:
                example-0:
                  value: "{\n    \"errorMessage\": \"Request without commerce\",\n    \"error\": \"null\"\n}"
      x-readme:
        samples-enabled: false
components:
  schemas:
    CompanyData:
      title: Company Data
      type: object
      required:
      - name
      - cnpj
      - address
      - email
      - mcc
      - countryCode
      - phone
      - revenue
      properties:
        name:
          type: string
          description: Company name
          example: Store 12
        cnpj:
          type: string
          description: CNPJ
          example: '56651716001150'
        address:
          $ref: '#/components/schemas/Address'
        email:
          type: string
          description: Company email
          example: test@example.com
        countryCode:
          type: string
          description: Phone country code
          example: '55'
        phone:
          type: string
          description: Phone number
          example: (11)23456-3456
        mcc:
          type: string
          description: Merchant Category Codes. Four-digit number
          example: '8999'
        revenue:
          type: string
          description: Person revenue
          example: '500055'
    Address:
      title: Address
      type: object
      required:
      - address
      - number
      - cep
      properties:
        address:
          type: string
          description: Company address
          example: SCN Quadra 02, Bloco G
        number:
          type: string
          description: Company street number
          example: '12'
        cep:
          type: string
          description: Company cep
          example: 05376-140
    Contact:
      title: Contact
      type: object
      required:
      - contact
      - type
      - roles
      properties:
        contact:
          type: string
          description: Email address or Phone number
          example: test@example.com
        type:
          type: string
          description: Contact type
          enum:
          - EMAIL
          - PHONE
        roles:
          title: roles
          type: array
          description: Contact type
          items:
            title: role
            type: string
            enum:
            - SUPPORT
            - REPORT
            - BACKOFFICE
            - BILLING
            - CHARGEBACKS
            - CREDENTIALS
    OnboardingRequest:
      title: OnboardingRequest
      type: object
      required:
      - store
      - contacts
      - payments
      - transaction
      properties:
        store:
          $ref: '#/components/schemas/Store'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        payments:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/Payment'
        transaction:
          $ref: '#/components/schemas/Transaction'
    BadResponse:
      title: BadResponse
      type: object
      properties:
        error:
          type: string
          description: Request error
          example: 'com.fasterxml.jackson.databind.exc.InvalidFormatException:'
        errorMessage:
          type: string
          description: Error description
          example: 'JSON parse error: Cannot deserialize value of type'
    PaymentAccount:
      title: Credentials
      type: object
      required:
      - storeCode
      properties:
        paymentMethod:
          type: string
          description: Payment method for the extract
          enum:
          - CARD
        account:
          type: string
          description: Payment account number
          example: AP12345PI
        evaluatesFraud:
          type: boolean
          description: Indicates if the account has antifraud
          example: true
    Transaction:
      title: Transaction
      type: object
      required:
      - referenceId
      properties:
        referenceId:
          type: string
          description: Client transaction identifier
          example: FGCCCEA53JYSHXX
        callbackUrl:
          type: string
          description: Url to send notifications to client
          example: http://domain/service
    Credentials:
      title: Credentials
      type: object
      required:
      - storeCode
      properties:
        storeCode:
          type: string
          description: Store code
          example: STORE12
        privateKey:
          type: string
          description: Authentication key
          example: dqwg43yefnjnk5fe
        orgId:
          type: string
          description: Fingerprint key
          example: s4fes6ytr4
    TransferData:
      title: Transfer Data
      type: object
      required:
      - period
      - account
      - accountType
      - code
      - bank
      - branch
      - documentType
      - documentNumber
      properties:
        period:
          type: string
          description: Advance payment period
          enum:
          - D2
          - D5
          - D15
          - D30
          - FLOW
        accountType:
          type: string
          description: Account type
          enum:
          - CACC
          - SLARY
          - SVGS
          - TRAN
        account:
          type: string
          description: Account number
          example: '05376140'
        bank:
          type: string
          description: Name of the person associated with the bank account
          example: John Doe
        code:
          type: string
          description: Bank code
          example: '001'
        branch:
          type: string
          description: Bank branch
          example: '0015'
        documentNumber:
          type: string
          description: Account document number
          example: '1234567889'
        documentType:
          type: string
          description: Document type
          enum:
          - CNPJ
          - CPF
    PersonData:
      title: Person Data
      type: object
      required:
      - firstName
      - lastName
      - email
      - cpf
      - birthDate
      - countryCode
      - phone
      - mcc
      - address
      - revenue
      properties:
        firstName:
          type: string
          description: Person first name
          example: John
        lastName:
          type: string
          description: Person last name
          example: Doe
        email:
          type: string
          description: Person email
          example: test@example.com
        cpf:
          type: string
          description: Person cpf
          example: '57616508278'
        birthDate:
          type: string
          description: Birthdate
          example: '1990-05-06'
        countryCode:
          type: string
          description: Phone country code
          example: '55'
        phone:
          type: string
          description: Phone number
          example: (11)23456-3456
        mcc:
          type: string
          description: Merchant Category Codes. Four-digit number
          example: '8999'
        address:
          $ref: '#/components/schemas/Address'
        revenue:
          type: string
          description: Person revenue
          example: '500055'
    StandardApiResponse:
      title: StandardApiResponse
      type: object
      required:
      - onboardingId
      - referenceId
      - status
      properties:
        onboardingId:
          type: string
          description: Onboarding identification
          example: 31ff2cc8-199e-4c3c-ba2d-4d85b88bd9f2
        referenceId:
          type: string
          description: Client transaction identifier
          example: FGCCCEA53JYSHXX
        status:
          type: string
          description: Onboarding status
          enum:
          - PENDING
          - INPROGRESS
          - ACTIONREQUIRED
          - COMPLETED
          - REJECT
          - CANCELLED
        message:
          type: string
          description: Information message
          example: Test message
        credentials:
          $ref: '#/components/schemas/Credentials'
        paymentAccounts:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/PaymentAccount'
    PricingDetail:
      title: Pricing Detail Table
      type: object
      required:
      - installment
      - brand
      - value
      properties:
        installment:
          type: integer
          description: Installment
          example: 1
        brand:
          type: string
          description: Card brand
          example: VISA
        value:
          type: number
          format: double
          description: Pricing fee
          example: '0.28'
    Payment:
      title: Payment Data
      type: object
      required:
      - paymentMethod
      - personData
      - transferData
      properties:
        paymentMethod:
          title: paymentMethod
          type: array
          description: Payment methods
          items:
            title: paymentMethod
            type: string
            enum:
            - CARD
            - PIX
        personData:
          $ref: '#/components/schemas/PersonData'
        companyData:
          $ref: '#/components/schemas/CompanyData'
        transferData:
          $ref: '#/components/schemas/TransferData'
        pricing:
          title: PricingData
          type: array
          description: Pricing
          items:
            $ref: '#/components/schemas/PricingData'
    Store:
      title: Store
      type: object
      required:
      - name
      - countryCode
      - documentType
      - document
      properties:
        name:
          type: string
          description: Store name, must not contain special characters and is limited to 20 characters, including spaces
          example: Store23
        countryCode:
          type: string
          description: Two-letter code as described in the ISO 3166 international standard
          example: BR
        documentType:
          type: string
          description: Type of the document
          enum:
          - CPF
          - CNPJ
        document:
          type: string
          description: Document number
          example: '1234567'
        integration:
          type: string
          description: Integration source
          enum:
          - api-standard
          - bis2bis
          - magento-1
          - magento-2
          - poolpay
          - traycorp
          - shopify
          - vale-pay
          - vtex
          - woocommerce
          - wbuy
    PricingData:
      title: Pricing
      type: object
      required:
      - paymentMethod
      properties:
        paymentMethod:
          type: string
          description: Payment method for the pricing configuration
          enum:
          - CARD
          - PIX
        summarized:
          type: number
          format: double
          description: Pricing fee
          example: '0.5'
        detailed:
          title: Pricing Details
          type: array
          description: Pricing detail table
          items:
            $ref: '#/components/schemas/PricingDetail'