openapi: 3.0.1
info:
  title: Bank Account Management Service OpenAPI specification
  description: >-
    The Bank Account Management Service enables merchants to store bank account
    data of their customers easily and highly secured at                      
    Ratepay. The stored bank account data can be used on the merchant's website
    or within backoffice orders to simplify future purchases.  The Bank Account
    Management Service offers a REST API to store, retrieve and delete customer
    bank account data. The API uses JSON as                       data exchange
    format..
  version: version 1
servers:
  - url: https://api-integration.ratepay.com/shop/consumer/v1
    description: Integration environment
  - url: https://api.ratepay.com/shop/consumer/v1
    description: Production environment
security:
  - Bearer Authentication: []
paths:
  /partners/{partner_profile_id}/consumer/{shop_buyer_id}/bank-accounts:
    get:
      summary: Get stored bank account by shop buyer id
      description: >-
        Retrieve a list of bank accounts stored for a specific buyer. Currently,
        the service stores one bank account per buyer.
        Thus,                             the returned list contains max. one
        bank account.
      operationId: getBankAccounts
      parameters:
        - name: partner_profile_id
          in: path
          description: partner profile id provided by Ratepay.
          example: MYSHOP_PR_DE
          required: true
          schema:
            type: string
        - name: shop_buyer_id
          in: path
          description: unique id assigned to the buyer by the merchant
          required: true
          schema:
            type: string
            example: customer_1
        - name: Authorization
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          in: header
          required: true
          schema:
            type: string
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Successfully returned requested data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '401':
          description: partner profile id doesn't belong to the asking shop
          content:
            application/json:
              schema: {}
        '404':
          description: Unknown merchant consumer id
          content:
            application/json:
              schema: {}
        '405':
          description: Method not allowed
          content:
            application/json:
              schema: {}
        '406':
          description: Data format not supported (JSON only)
          content:
            application/json:
              schema: {}
        '413':
          description: Request entity too large
          content:
            application/json:
              schema: {}
        '500':
          description: Internal server error. Try again later.
          content:
            application/json:
              schema: {}
    post:
      summary: Store bank account
      description: >-
        Store bank account data for a specific buyer. Currently, only one bank
        account can be stored              per buyer. Subsequent calls to that
        endpoint for the same buyer will overwrite existing bank account data.
      operationId: storeBankAccount
      parameters:
        - name: partner_profile_id
          in: path
          description: partner profile id provided by Ratepay
          example: MYSHOP_PR_DE
          required: true
          schema:
            type: string
        - name: shop_buyer_id
          in: path
          description: unique id assigned to the consumer by the merchant
          required: true
          schema:
            type: string
            example: customer_1
        - name: Authorization
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          in: header
          required: true
          schema:
            type: string
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            example: application/json
      requestBody:
        description: bank account data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccount'
        required: true
      responses:
        '201':
          description: bank account stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '400':
          description: data must contain IBAN and owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '401':
          description: partner profile id doesn't belong to the asking shop
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '406':
          description: Data format not supported (JSON only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '413':
          description: Request entity too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '415':
          description: Unsupported content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '422':
          description: Invalid IBAN or BIC
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
        '500':
          description: Internal server error. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountReference'
  /partners/{partner_profile_id}/consumer/{shop_buyer_id}/bank-accounts/{bank_account_reference}:
    delete:
      summary: Delete bank account
      description: Delete a stored bank account of a given buyer.
      operationId: deleteBankAccount
      parameters:
        - name: partner_profile_id
          in: path
          description: partner profile id provided by Ratepay
          example: MYSHOP_PR_DE
          required: true
          schema:
            type: string
        - name: shop_buyer_id
          in: path
          description: unique id assigned to the buyer by the merchant
          example: customer_1
          required: true
          schema:
            type: string
        - name: bank_account_reference
          in: path
          description: >-
            unique identifier for the bank account. This element can be
            retrieved by the GET request
          example: 226e7a20-5e1e-4f23-a56c-c8a851b190e7
          required: true
          schema:
            type: string
        - name: Authorization
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          in: header
          required: true
          schema:
            type: string
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            example: application/json
      responses:
        '204':
          description: bank account deleted
        '401':
          description: partner profile id doesn't belong to the asking shop
        '404':
          description: Unknown merchant consumer id
        '500':
          description: Internal server error. Try again later.
  /partners/{partner_profile_id}/shop-buyers/{shop_buyer_id}/bank-accounts/{bank_account_reference}:
    get:
      summary: Get stored bank account by bank account reference
      description: >-
        Retrieve a list of bank accounts stored for a specific bank account
        reference. Currently, the service stores one bank account per buyer.
        Thus, the returned list contains max. one bank account.
      operationId: getBankAccountInternal
      parameters:
        - name: partner_profile_id
          in: path
          description: partner profile id provided by Ratepay.
          example: MYSHOP_PR_DE
          required: true
          schema:
            type: integer
            format: int32
        - name: shop_buyer_id
          in: path
          description: unique id assigned to the buyer by the merchant
          example: customer_1
          required: true
          schema:
            type: string
        - name: bank_account_reference
          in: path
          description: the identifier of the bank account
          example: 226e7a20-5e1e-4f23-a56c-c8a851b190e7
          required: true
          schema:
            type: string
        - name: Authorization
          description: >-
            For each request, a valid access token must be provided in the
            Authorization header. See [Authentication
            API](/docs/developer/authentication/authentication/) for obtaining a
            valid token.
          in: header
          required: true
          schema:
            type: string
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            example: application/json
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: Successfully returned requested data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '401':
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          description: Unknown merchant consumer id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '406':
          description: Data format not supported (JSON only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '413':
          description: Request entity too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '500':
          description: Internal server error. Try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
components:
  securitySchemes:
    Bearer Authentication:
      type: http
      description: >-
        For each request, a valid access token must be provided in the
        Authorization header. See [Authentication
        API](/docs/developer/authentication/authentication/) for obtaining a
        valid token.
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ErrorInfo:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
    BankAccount:
      required:
        - iban
        - owner
      type: object
      properties:
        bank_account_reference:
          type: string
          description: identifier of the bank account
          format: uuid
          readOnly: true
          example: 8e3412b0-a334-4d0a-b132-7ab996d769ef
        owner:
          maxLength: 1000
          minLength: 0
          type: string
          description: name of bank account owner (including first name and last name)
          example: Jane Doe
        iban:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            the international bank account number. Spaces are allowed, but not
            necessary.
          example: DE07 1234 1234 1234 1234 12
        bic:
          maxLength: 50
          minLength: 0
          type: string
          description: the bank identifier code
          example: MARKDEFFXXX
      description: bank account data
    BankAccountReference:
      type: object
      properties:
        bank_account_reference:
          type: string
          description: >-
            The `bank_account_reference` can be used in a payment request to
            identify the IBAN and BIC for the purchase.
          format: uuid
      description: reference to bank account data
