Koin Recipient Services Account API

openapi: 3.0.3
info:
  title: Antifraud Access Recipient Services Account 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: Recipient Services Account
paths:
  /v1/payment/payment-key/info:
    post:
      tags:
      - Recipient Services Account
      summary: Recipient Account
      description: Service to obtain recipient account information.
      operationId: RecipientAccountPOST
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientAccount'
      responses:
        '200':
          description: Recipient response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RecipientAccount:
      title: Recipient
      required:
      - payment_key
      - transaction
      type: object
      properties:
        payment_key:
          type: string
          pattern: ^[0-9]{11}$ ,^[0-9]{14}$, ^\+[1-9][0-9]\d{1,14}$ ,[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
          description: Pix payment key. Options are CNPJ, CPF, telephone, email, or random payment key (max 100 characters)
          example:
          - '12345678000112'
          - '54672396002'
          - '+5561912346578'
          - jhon_doe@domain.com
          - 123e4567-e12b-12d1-a456-426655440000
        transaction:
          required:
          - reference_id
          - amount
          - account
          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
            descriptor:
              type: string
              description: Description sent to recipient of payment (Max. 140 characters)}
    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
    RecipientResponse:
      title: Payout Response
      type: object
      properties:
        id:
          type: string
          pattern: ^[a-zA-Z0-9_#.-]{0,50}$
          description: Identifier search recipient.
        name:
          type: string
          example: Box Jhon
          description: Full name.
        document:
          required:
          - type
          - number
          type: object
          properties:
            type:
              type: string
              enum:
              - cpf
              - cnpj
              description: Payer document type (cpf, cnpj)
            number:
              type: string
              pattern: (^[0-9]{11}$)|(^[0-9]{14}$)
              description: Payer document number
        account:
          type: object
          properties:
            agency:
              type: string
              description: Receiver account Agency.
              example: 1500
            code:
              type: string
              description: Receiver account number.
              example: 123456789
            type:
              type: string
              description: Receiver account type.
              example: CC
        bank:
          type: object
          properties:
            name:
              type: string
              example: Bank name
              description: Bank.
            ispb:
              type: string
              description: Brazilian Payment System Identifier (eight-number length).
              example: 12345678
        descriptor:
          type: string
          example: From Mike to Maria's birthday present
          description: Text send to client. Maximum of 140 characters.
        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)