Open Payments KYC Service API

openapi: 3.2.0
info:
  title: Open Payments KYC Service API
  version: 1.3.3
  description: '# Summary

    The Open Banking part of our API is based on The BerlinGroup NextGenPSD2 Framework with some additional services.'
  license:
    name: Creative Commons Attribution 4.0 International Public License
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Open Payments Europe AB
    url: https://www.openpayments.io/
    email: info@openpayments.io
servers:
- url: https://api.openbankingplatform.com
- url: https://api.sandbox.openbankingplatform.com
security:
- {}
tags:
- name: KYC Service
  description: 'KYC Service offers the following services:

    * Initiation of a KYC process to access our KYC webform

    * KYC status of a corporation'
paths:
  /kyc/integration/v1/new/{PSU-Corporate-ID}:
    servers:
    - url: https://api.sandbox.openbankingplatform.com
      description: KYC sandbox server
    - url: https://api.openbankingplatform.com
      description: KYC production server
    post:
      tags:
      - KYC Service
      security:
      - oAuth2Sandbox:
        - paymentinitiation corporate
      - oAuth2Production:
        - paymentinitiation corporate
      summary: Create KYC
      description: Enter the `PSU-Corporate-ID` of the company for which to initiate the KYC process. This generates a KYC webform URL valid for 24 hours. If more time is needed, generate a new URL. This webform guides the user through the whole KYC process. To check if the KYC was successful poll the KYC Service's `/status` endpoint.
      operationId: new
      parameters:
      - name: PSU-Corporate-ID
        description: Corporate Client ID. This is typically the unique Corporate ID in the local format. E.g. Org. nummer for SE, KVK for NL.
        in: path
        required: true
        schema:
          type: string
          example: 123456-1234
      - name: countryCode
        in: query
        required: true
        description: ISO 3166 ALPHA2 country code
        schema:
          type: string
          example: SE
          pattern: '[A-Z]{2}'
      - $ref: '#/components/parameters/X-Request-ID'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartNewKycInstanceResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server Error
  /kyc/integration/v1/status/{PSU-Corporate-ID}:
    servers:
    - url: https://api.sandbox.openbankingplatform.com
      description: KYC sandbox server
    - url: https://api.openbankingplatform.com
      description: KYC production server
    get:
      tags:
      - KYC Service
      security:
      - oAuth2Sandbox:
        - paymentinitiation corporate
      - oAuth2Production:
        - paymentinitiation corporate
      summary: Get KYC Status
      description: Returns the KYC status of the company. If the `kycStatus` is `Valid`, the company is allowed to make payments. If the `kycStatus` is `Invalid`, a new KYC process can be initiated via the KYC Service's /new endpoint.
      operationId: status
      parameters:
      - name: PSU-Corporate-ID
        description: Corporate Client ID. This is typically the unique Corporate ID in the local format. E.g. Org. nummer for SE, KVK for NL.
        in: path
        required: true
        schema:
          example: 123456-1234
          type: string
      - $ref: '#/components/parameters/X-Request-ID'
      responses:
        '200':
          $ref: '#/components/responses/getKycStatusResponse-200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server Error
components:
  examples:
    getKycStatusResponseExample:
      value:
        psuCorporateId: 123456-1234
        kycStatus: Valid
        kycValidUntil: '2024-09-06'
  schemas:
    StartNewKycInstanceResponse:
      type: object
      required:
      - kycUrl
      properties:
        kycUrl:
          $ref: '#/components/schemas/kycUrl'
    kycUrl:
      type: string
      example: https://kyc.openbankingplatform.com/?instanceId=008b3d7e-ae80-4577-8ed9-36a2b2b0fa6d
    getKycStatusResponse:
      type: object
      properties:
        psuCorporateId:
          type: string
          example: 123456-1234
        kycStatus:
          $ref: '#/components/schemas/kycStatus'
        kycValidUntil:
          type:
          - string
          - 'null'
          example: '2024-09-06'
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    kycStatus:
      example: Invalid
      type: string
      enum:
      - Valid
      - Invalid
  responses:
    getKycStatusResponse-200:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getKycStatusResponse'
          examples:
            Example:
              $ref: '#/components/examples/getKycStatusResponseExample'
  parameters:
    X-Request-ID:
      name: X-Request-ID
      in: header
      description: ID of the request, unique to the call, as determined by the initiating party.
      required: true
      example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
      schema:
        type: string
        format: uuid
  securitySchemes:
    oAuth2Sandbox:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.openbankingplatform.com/connect/token
          scopes:
            aspspinformation: ASPSP Information
            accountinformation: Account Information
            paymentinitiation: Payment Initiation
            private: Private accounts context
            corporate: Corporate accounts context
    oAuth2Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.openbankingplatform.com/connect/token
          scopes:
            aspspinformation: ASPSP Information
            accountinformation: Account Information
            bankgiroinformation: Account Information Enrichment
            paymentinitiation: Payment Initiation
            private: Private accounts context
            corporate: Corporate accounts context
externalDocs:
  description: 'Full Documentation of NextGenPSD2 Access to Account Interoperability Framework

    (General Introduction Paper, Operational Rules, Implementation Guidelines)

    '
  url: https://www.berlin-group.org/nextgenpsd2-downloads
x-tagGroups:
- name: Core APIs
  tags:
  - ASPSP Information Service
  - Consent Service
  - Account Information Service (AIS)
  - Payment Initiation Service (PIS)
  - KYC Service
- name: Alternative APIs
  tags:
  - ISO Payments
  - FX Connect
- name: Premium APIs
  tags:
  - Bankgiro Lookup
  - Payout Service
  - Verification of Payee (VoP)
  - SEPA Direct Debit