Koin Payment Services API

openapi: 3.0.3
info:
  title: Antifraud Access Payment 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: Payment Services
paths:
  /v1/payment/orders:
    post:
      tags:
      - Payment Services
      summary: Create Payment
      description: Create payment service. Before required fields will validated and after will validated business rules. Below is a table with the information regarding said api.
      operationId: createPayment
      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:
              oneOf:
              - $ref: '#/components/schemas/PaymentPixFull'
              - $ref: '#/components/schemas/PaymentBNPL'
              - $ref: '#/components/schemas/PaymentCardSchemas'
      responses:
        '200':
          description: Create payment response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PixPaymentResponse'
                - $ref: '#/components/schemas/BNPLPaymentResponse'
                - $ref: '#/components/schemas/CardPaymentResponse'
              examples:
                Successful Pix:
                  $ref: '#/components/examples/PixCreatePaymentResponse'
                Successful Pix checkout own:
                  $ref: '#/components/examples/PixOwnCreatePaymentResponse'
                Successful BNPL:
                  $ref: '#/components/examples/BNPLCreatePaymentResponse'
                Successful BNPL transparent checkout:
                  $ref: '#/components/examples/BNPLCreatePaymentFullApiResponse'
                Successful Card:
                  $ref: '#/components/examples/CardCreatePaymentResponse'
                Successful Card with Antifraud:
                  $ref: '#/components/examples/CardCreatePaymentWithAntiFraudResponse'
                Successful Card with Antifraud strategy:
                  $ref: '#/components/examples/CardCreatePaymentWithAntiFraudStrategyResponse'
                Successful Card with Checkout:
                  $ref: '#/components/examples/CardCreatePaymentWithCheckout'
                Error:
                  $ref: '#/components/examples/UnknownError'
                G01 Error:
                  $ref: '#/components/examples/G01Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Validation Failed:
                  value:
                    code: 400
                    message: Validation failed
                    causes:
                    - transaction.amount.currency_code must not be null
                    - transaction.amount.value must not be null
        '404':
          description: Not Found
        '409':
          description: Conflict
        '500':
          description: Internal Server Error
    get:
      tags:
      - Payment Services
      summary: Get Payment by Reference ID
      description: Payment details service.
      operationId: paymentByReferenceIdGET
      parameters:
      - in: query
        name: reference_id
        description: Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
        example: REF0000001
        schema:
          type: string
        required: true
      - 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
      responses:
        '200':
          description: Payment details response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PixPaymentDetailResponse'
                - $ref: '#/components/schemas/BNPLPaymentDetailResponse'
                - $ref: '#/components/schemas/CardPaymentDetailResponse'
              examples:
                Pix payment:
                  $ref: '#/components/examples/PixGetPaymentResponse'
                BNPL payment:
                  $ref: '#/components/examples/BNPLGetPaymentResponse'
                Card payment:
                  $ref: '#/components/examples/CardGetPaymentDetailResponse'
                Card payment with Antifraud:
                  $ref: '#/components/examples/CardWithAntifraudGetPaymentDetailResponse'
                Error:
                  $ref: '#/components/examples/UnknownError'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request:
                  value:
                    code: 400
                    message: Required String parameter 'reference_id' is not present
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    code: 404
                    message: Payment not found by reference_id {reference_id}
        '500':
          description: Internal Server Error
  /v1/payment/orders/lookup:
    get:
      tags:
      - Payment Services
      summary: Get Payments by Transaction ID
      description: Payment orders.
      operationId: paymentByTransactionIdGET
      parameters:
      - in: query
        name: transaction_id
        description: Payment identifier, Multiple orders associated with a payment.
        example: TRX0000001
        schema:
          type: string
        required: true
      - 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
      responses:
        '200':
          description: Payment order response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CardPaymentTransactionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request:
                  value:
                    code: 400
                    message: Required String parameter 'transaction_id' is not present
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    code: 404
                    message: Payment not found by transaction_id {transaction_id}
        '500':
          description: Internal Server Error
  /v1/payment/orders/{order_id}/capture:
    post:
      tags:
      - Payment Services
      summary: Capture Payment
      description: Service responsible for capturing a card payment
      operationId: capturePayment
      parameters:
      - in: path
        name: order_id
        description: Order ID returned by create payment service
        schema:
          type: string
        example: 9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f
        required: true
      - 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
      responses:
        '200':
          description: Capture response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureResponse'
              examples:
                Successful Capture:
                  $ref: '#/components/examples/CardCapturePaymentResponse'
                Error:
                  $ref: '#/components/examples/UnknownError'
                G02 Error:
                  value:
                    code: G02
                    message: Error order_id not found
                G05 Error:
                  value:
                    code: G05
                    message: Only orders Authorized can be Captured
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /v1/payment/orders/{order_id}:
    get:
      tags:
      - Payment Services
      summary: Get Payment
      description: Payment details service.
      operationId: paymentByOrderIdGET
      parameters:
      - name: order_id
        in: path
        description: Order ID returned by create payment service
        example: 9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f
        schema:
          type: string
        required: true
      - 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
      responses:
        '200':
          description: Payment details response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PixPaymentDetailResponse'
                - $ref: '#/components/schemas/BNPLPaymentDetailResponse'
                - $ref: '#/components/schemas/CardPaymentDetailResponse'
              examples:
                Pix payment:
                  $ref: '#/components/examples/PixGetPaymentResponse'
                BNPL payment:
                  $ref: '#/components/examples/BNPLGetPaymentResponse'
                Card payment:
                  $ref: '#/components/examples/CardGetPaymentDetailResponse'
                Card payment with Antifraud:
                  $ref: '#/components/examples/CardWithAntifraudGetPaymentDetailResponse'
                Error:
                  $ref: '#/components/examples/UnknownError'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request:
                  value:
                    code: 400
                    message: Required String parameter 'reference_id' is not present
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    code: 404
                    message: Payment not found by order_id {order_id}
        '500':
          description: Internal Server Error
  /v1/payment/orders/{order_id}/cancel:
    put:
      tags:
      - Payment Services
      summary: Cancel Payment
      description: Cancellation payment. Card, Pix and BNPL payment method can be cancelled, for Pix payment method, you can only cancel dynamic QR payments; for the card payment method, you can cancel **Opened** or **Authorized** payments, which will remain with the status **Canceled** or **Voided** respectively.
      operationId: cancelPaymentPUT
      parameters:
      - name: order_id
        in: path
        description: Order ID returned by create payment service
        example: 9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f
        schema:
          type: string
        required: true
      - 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
      responses:
        '200':
          description: Cancel payment response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelPaymentResponse'
              examples:
                Successful cancellation:
                  value:
                    status:
                      type: Cancelled
                      date: '2022-02-08T21:25:04.000Z'
                    transaction:
                      reference_id: REF0000001
                      account: SBX000
                      provider_reference:
                        tx_id: '20000000000000026628140042292'
                    order_id: 9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f
                Error:
                  $ref: '#/components/examples/UnknownError'
                G02 Error:
                  value:
                    code: G02
                    message: Error order_id not found
                G04 Error:
                  value:
                    code: G04
                    message: Only orders not Closed can be Cancelled
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
components:
  schemas:
    PaymentBNPL:
      title: BNPL
      required:
      - transaction
      - country_code
      - payment_method
      - payer
      - device_fingerprint
      - notification_url
      - shipping
      - items
      - ip_address
      - verified_id
      type: object
      properties:
        store:
          type: object
          properties:
            code:
              type: string
              description: Store identifier
              example: SBXSTORE
            category:
              type: string
              description: Four-digit ISO 18245 merchant category code
              example: 4816
        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
              - breakdown
              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
                breakdown:
                  required:
                  - items
                  - shipping
                  - taxes
                  type: object
                  properties:
                    items:
                      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: Items total amount
                          example: 1500
                    shipping:
                      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: Shipping total amount
                          example: 500.56
                    taxes:
                      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: Taxes total amount
                          example: 0
        country_code:
          type: string
          description: Transaction country code (two-letter ISO 3166 country code)
          example: BR
        payment_method:
          required:
          - code
          - expiration_date
          type: object
          properties:
            code:
              type: string
              enum:
              - PIX
              - CARD
              - BNPL
              description: Payment method code
            expiration_date:
              type: string
              format: date-time
              description: Payment expiration date (In ISO 8601 format with UTC in GMT 0)
              example: '2021-01-01T00:00:00.000Z'
            option_id:
              type: string
              description: Availability installment option identifier (required for transparent checkout).
              example: e9652f2e-6aa1-4580-b6e3-45e9c5de66a6
        payer:
          required:
          - document
          - email
          - phone
          - address
          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'
                nationality:
                  type: string
                  description: Payer nationality (two-letter ISO 3166 country code)
                  example: BR
            first_name:
              type: string
              maxLength: 100
              description: Payer first name. If the length of the field exceeds 100 characters it will be truncated
              example: Jhon
            last_name:
              type: string
              maxLength: 100
              description: Payer last name. If the length of the field exceeds 100 characters it will be truncated
              example: Doe
            name_father:
              type: string
              maxLength: 100
              description: Payer's father last name. If the length of the field exceeds 100 characters it will be truncated (Only for BNPL payment method)
              example: Doe
            name_mother:
              type: string
              maxLength: 100
              description: Payer's mother last name. If the length of the field exceeds 100 characters it will be truncated (Only for BNPL payment method)
              example: Jones
            full_name:
              type: string
              maxLength: 100
              description: Payer full name. If the length of the field exceeds 100 characters it will be truncated
              example: Jhon Doe Jones
            gender:
              type: string
              description: Payer gender
              enum:
              - FEMALE
              - MALE
              - OTHER
            email:
              type: string
              description: Payer email
              example: jhon_doe@domain.com
            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
            birthdate:
              type: string
              pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
              description: Payer birthdate
              example: '1980-10-20'
            address:
              type: object
              required:
              - country_code
              - street
              - number
              - city_name
              - zip_code
              - state
              properties:
                country_code:
                  type: string
                  description: Country code (two-letter ISO 3166 country code)
                  example: BR
                state:
                  type: string
                  description: State code
                  example: SP
                city_name:
                  type: string
                  description: City name
                  example: SAO PAULO
                street:
                  type: string
                  description: Street name
                  example: RUA ABRAO WAITMAN
                number:
                  type: string
                  description: Building number
                  example: '500'
                zip_code:
                  type: string
                  description: ZIP code
                  example: 04788240
                district:
                  type: string
                  description: District
                  example: INTERLAGOS
                complement:
                  type: string
                  description: Additional address information
        shipping:
          required:
          - delivery_date
          - address
          type: object
          properties:
            delivery_date:
              type: string
              description: Shipping delivery date
              example: '2021-11-01'
            address:
              required:
              - country_code
              - street
              - number
              - city_name
              - zip_code
              - state
              type: object
              properties:
                country_code:
                  type: string
                  description: Country code (two-letter ISO 3166 country code)
                  example: BR
                state:
                  type: string
                  description: State code
                  example: SP
                city_name:
                  type: string
                  description: City name
                  example: SAO PAULO
                street:
                  type: string
                  description: Street name
                  example: RUA ABRAO WAITMAN
                number:
                  type: string
                  description: Building number
                  example: '500'
                zip_code:
                  type: string
                  description: ZIP code
                  example: 04788240
                district:
                  type: string
                  description: District
                  example: INTERLAGOS
                complement:
                  type: string
                  description: Additional address information
        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'
        ip_address:
          type: string
          description: Buyer ip address
          example: 192.0.2.146
        verified_id:
          type: boolean
          description: Indicates if the buyer's ID was verified
        descriptor:
          type: string
          description: Description sent to recipient of payment (Max. 140 characters)
        device_fingerprint:
          type: string
          description: Represents the device used to initiate the payment
          example: 3f139f92d30d54f1aaf519b3a39a20814
        notification_url:
          type: array
          description: List of urls to which notifications will be sent
          items:
            type: string
            example: https://www.providerApi.com/notificationPayments
        payment_url:
          type: string
          description: Url checkout for payment
          example: https://www.providerApi.com/payments/checkout
        terms:
          type: object
          properties:
            accepted:
              type: boolean
              description: Indicates whether the customer accepted the terms and conditions (required for transparent checkout)
              example: true
    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'
    LicesingAmount:
      title: licesing_amount
      type: object
      allOf:
      - $ref: '#/components/schemas/Amount'
    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'
    PaymentCardSchemas:
      title: CARD
      oneOf:
      - $ref: '#/components/schemas/PaymentCard'
      - $ref: '#/components/schemas/PaymentCardWithAntiFraud'
      - $ref: '#/components/schemas/PaymentCardWithCheckOut'
    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'
    PixPaymentResponse:
      title: Pix payment response
      type: object
      required:
      - transaction
      - order_id
      - status
      - country_code
      properties:
        store:
          type: object
          properties:
            code:
              type: string
              description: Store identifier.
              example: SBXSTORE
            category:
              type: string
              description: Four-digit ISO 18245 merchant category code.
              example: 4816
        transaction:
          required:
          - reference_id
          - 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.
              

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