Open Payments Bankgiro Lookup API

openapi: 3.2.0
info:
  title: Open Payments Bankgiro Lookup 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: Bankgiro Lookup
  description: Bankgiro Lookup APIs provide enhanced data and pre-payment validation on top of our core APIs. These services enable you to build more reliable, user-friendly payment experiences by accessing and verifying additional information related to payment accounts.
paths:
  /premium/v1/creditor-name:
    servers:
    - url: https://api.sandbox.openbankingplatform.com
      description: Premium products sandbox server
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    get:
      summary: Get Creditor Name
      description: Returns the name of the recipient based on their account information.
      tags:
      - Bankgiro Lookup
      operationId: GetCreditorName
      security:
      - oAuth2Sandbox:
        - paymentinitiation corporate
      - oAuth2Production:
        - paymentinitiation corporate
      parameters:
      - name: giroNumber
        in: query
        required: true
        schema:
          type: string
      - name: giroType
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/giroType'
      - name: ocrRef
        in: query
        description: '**Must** be provided if `invoiceRef` is not.

          '
        schema:
          $ref: '#/components/schemas/giroOcrReference'
      - name: invoiceRef
        in: query
        description: '**Must** be provided if `ocrRef` is not.

          '
        schema:
          $ref: '#/components/schemas/giroInvoiceReference'
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      - $ref: '#/components/parameters/PSU-ID'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCreditorNameResponse'
              examples:
                Example:
                  $ref: '#/components/examples/GetCreditorNameResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
      x-operation-id-source: normalized
      x-operation-id-original: Get Creditor Name
  /premium/v1/giro-numbers:
    servers:
    - url: https://api.sandbox.openbankingplatform.com
      description: Premium products sandbox server
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    get:
      summary: Get Giro Numbers
      description: Returns Bankgiro numbers associated with a company.
      tags:
      - Bankgiro Lookup
      operationId: GetGiroNumbers
      security:
      - oAuth2Sandbox:
        - paymentinitiation corporate
      - oAuth2Production:
        - paymentinitiation corporate
      parameters:
      - name: psuCorporateId
        in: query
        required: true
        schema:
          type: string
      - name: giroType
        in: query
        schema:
          $ref: '#/components/schemas/giroType'
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      - $ref: '#/components/parameters/PSU-ID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGiroNumbersResponse'
              examples:
                Example:
                  $ref: '#/components/examples/GetGiroNumbersResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
      x-operation-id-source: normalized
      x-operation-id-original: Get Giro Numbers
components:
  schemas:
    GetCreditorNameResponse:
      type: object
      properties:
        creditorName:
          type:
          - string
          - 'null'
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX_GetCreditorName'
      additionalProperties: false
    giroType:
      type: string
      description: Swedish giro type
      enum:
      - BANKGIRO
      - PLUSGIRO
    tppMessage2XX_GetCreditorName:
      type: object
      required:
      - category
      - code
      properties:
        category:
          $ref: '#/components/schemas/tppMessageCategory'
        code:
          $ref: '#/components/schemas/MessageCode_GetCreditorName2XX'
        path:
          type: string
        text:
          $ref: '#/components/schemas/tppMessageText'
    giroReference:
      description: 'Reference to a Swedish Bankgiro or Plusgiro account

        '
      type: object
      required:
      - giroNumber
      - giroType
      properties:
        giroNumber:
          $ref: '#/components/schemas/giroNumber'
        giroType:
          $ref: '#/components/schemas/giroType'
    ErrorResponseDetails:
      type: object
      properties:
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
      additionalProperties: false
    giroOcrReference:
      type: string
      description: Swedish OCR reference.
      minLength: 2
      maxLength: 25
      pattern: ^[0-9]+$
      example: '45678901234567'
    tppMessage2XX:
      type: object
      required:
      - category
      - code
      properties:
        category:
          $ref: '#/components/schemas/tppMessageCategory'
        code:
          $ref: '#/components/schemas/MessageCode2XX'
        path:
          type: string
        text:
          $ref: '#/components/schemas/tppMessageText'
    tppMessageText:
      description: Additional explaining text to the TPP.
      type: string
      maxLength: 512
    giroWithName:
      type: object
      allOf:
      - $ref: '#/components/schemas/giroReference'
      - type: object
        required:
        - name
        properties:
          name:
            $ref: '#/components/schemas/displayName'
    giroInvoiceReference:
      type: string
      description: Custom invoice reference
      minLength: 1
      maxLength: 25
      example: INV-20250073
    MessageCode2XX:
      description: Message codes for HTTP Error codes 2XX.
      type: string
    tppMessageCategory:
      description: Category of the TPP message category
      type: string
      enum:
      - INFORMATION
      - UNMAPPED
      - ERROR
      - WARNING
    displayName:
      description: 'Name of the account as defined by the PSU within online channels.

        '
      type: string
      maxLength: 70
    MessageCode_GetCreditorName2XX:
      description: Message codes for HTTP Error codes 2XX.
      type: string
      enum:
      - OCR_REF_INVALID
      - CREDITOR_ACCOUNT_INVALID
    giroNumber:
      type: string
      description: Swedish Bankgiro or Plusgiro number
      pattern: '[0-9-]{5,35}'
      example: 1234-5678
    GetGiroNumbersResponse:
      type: object
      properties:
        giros:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/giroWithName'
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
      additionalProperties: false
  parameters:
    PSU-ID:
      name: PSU-ID
      in: header
      description: 'Client ID of the PSU in the ASPSP client interface. This is typically a local social security number or another unique login ID.

        '
      schema:
        type: string
      required: true
      example: 199002092386
    PSU-Corporate-ID:
      name: PSU-Corporate-ID
      in: header
      description: 'Corporate Client ID for the ASPSP. This is typically the unique Corporate ID in the local format. E.g. Org. nummer for SE, KVK for NL. **Mandatory in the corporate scope**.

        '
      schema:
        type: string
      required: false
      example: 5560160680
    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
  examples:
    GetGiroNumbersResponseExample:
      value:
        giros:
        - giroNumber: 1234-5678
          giroType: BANKGIRO
          name: Acme AB
    GetCreditorNameResponseExample:
      value:
        creditorName: Acme AB
  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