openapi: 3.2.0
info:
  title: Memo Bank NextGenPSD2 PIS API
  description: '**Memo Bank NextGenPSD2 API** allows Third Party Providers to access account information and initiate payments on behalf of customers.


    The API follows [BerlinGroup NextGenPSD2 Implementation Guidelines](https://www.berlin-group.org/nextgenpsd2-downloads) as of version 1.3.11. This document describe our implementation choices and where we have drifted away from the guidelines.


    All non-absolute paths described in this document are relatives to the base URL of the server (e.g. https://api.memo.bank/nextgenpsd2 for the production environment).

    '
  version: '1.0'
servers:
- url: https://api.memo.bank/nextgenpsd2
  description: Production environment
- url: https://api.beta.sandbox.memo.bank/nextgenpsd2
  description: Sandbox environment
tags:
- name: PIS
  description: "Payment Initiation Service.\n\n\nPayment initiation is done using the **integrated OAuth2** authentication flow described in NextGenPSD2\nspecifications.\nThis means you first have to initiate a payment using the dedicated endpoint, then redirect the PSU to our \nauthorisation page following the link present in the response (using `PIS:{paymentId}` as OAuth2 scope).\nAfter performing a strong customer authentication, the PSU will be redirected to your redirect URI with an\n**authorisation code** that you can then exchange for an **access token**.\n\n\nThis **access token** is only needed to cancel a payment on behalf a PSU (this does not require a strong\ncustomer authentication). It is not needed to retrieve the current status of a payment.\n"
paths:
  /v1/{payment-service}/{payment-product}/{paymentId}:
    get:
      tags:
      - PIS
      summary: Get payment information
      operationId: getPaymentInformation
      parameters:
      - name: payment-service
        in: path
        required: true
        schema:
          type: string
          enum:
          - payments
          - bulk-payments
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
      - name: paymentId
        in: path
        required: true
        schema:
          type: string
      - name: Signature
        in: header
        schema:
          type: string
          example: $SIGNATURE
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PaymentInitiationWithStatusResponse'
                - $ref: '#/components/schemas/BulkPaymentInitiationWithStatusResponse'
    delete:
      tags:
      - PIS
      summary: Cancel a payment.
      operationId: cancelPayment
      parameters:
      - name: payment-service
        in: path
        required: true
        schema:
          type: string
          enum:
          - payments
          - bulk-payments
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
      - name: paymentId
        in: path
        required: true
        schema:
          type: string
      - name: Signature
        in: header
        schema:
          type: string
          example: $SIGNATURE
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiationCancelResponseMinus202'
      security:
      - OAuth2:
        - PIS
  /v1/{payment-service}/{payment-product}/{paymentId}/status:
    get:
      tags:
      - PIS
      summary: Get payment initiation status
      operationId: getPaymentInitiationStatus
      parameters:
      - name: payment-service
        in: path
        required: true
        schema:
          type: string
          enum:
          - payments
          - bulk-payments
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
      - name: paymentId
        in: path
        required: true
        schema:
          type: string
      - name: Signature
        in: header
        schema:
          type: string
          example: $SIGNATURE
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiationStatusResponseMinus200Json'
  /v1/{payment-service}/{payment-product}:
    post:
      tags:
      - PIS
      summary: Initiate a payment
      operationId: initiatePayment
      parameters:
      - name: payment-service
        in: path
        required: true
        schema:
          type: string
          enum:
          - payments
          - bulk-payments
      - name: payment-product
        in: path
        required: true
        schema:
          type: string
          enum:
          - sepa-credit-transfers
          - instant-sepa-credit-transfers
      - name: Signature
        in: header
        schema:
          type: string
          example: $SIGNATURE
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/PaymentInitiationJson'
              - $ref: '#/components/schemas/BulkPaymentInitiationJson'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitationRequestResponseMinus201'
components:
  schemas:
    PaymentInitiationCancelResponseMinus202:
      required:
      - transactionStatus
      type: object
      properties:
        transactionStatus:
          type: string
          enum:
          - ACSC
          - RCVD
          - PDNG
          - RJCT
          - CANC
          - ACFC
          - PART
    LinksPaymentInitiation:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/HrefType'
        status:
          $ref: '#/components/schemas/HrefType'
    Amount:
      required:
      - amount
      - currency
      type: object
      properties:
        currency:
          pattern: ^[A-Z]{3}$
          type: string
        amount:
          pattern: ^-?[0-9]{1,14}(\.[0-9]{1,3})?$
          type: string
    AccountReference:
      type: object
      properties:
        iban:
          pattern: ^[A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}$
          type: string
        maskedPan:
          maxLength: 35
          minLength: 0
          type: string
        currency:
          pattern: ^[A-Z]{3}$
          type: string
        cashAccountType:
          type: string
    PaymentInitiationBulkElementJson:
      required:
      - creditorAccount
      - creditorName
      - instructedAmount
      type: object
      properties:
        instructedAmount:
          $ref: '#/components/schemas/Amount'
        creditorAccount:
          $ref: '#/components/schemas/AccountReference'
        creditorName:
          maxLength: 70
          minLength: 0
          type: string
        endToEndIdentification:
          maxLength: 35
          minLength: 0
          type: string
        creditorAddress:
          $ref: '#/components/schemas/Address'
        remittanceInformationUnstructured:
          maxLength: 140
          minLength: 0
          type: string
    BulkPaymentInitiationWithStatusResponse:
      required:
      - debtorAccount
      - payments
      - transactionStatus
      type: object
      properties:
        debtorAccount:
          $ref: '#/components/schemas/AccountReference'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentInitiationBulkElementJson'
        requestedExecutionDate:
          type: string
          format: date
        transactionStatus:
          type: string
          enum:
          - ACSC
          - RCVD
          - PDNG
          - RJCT
          - CANC
          - ACFC
          - PART
    BulkPaymentInitiationJson:
      required:
      - debtorAccount
      - payments
      type: object
      properties:
        debtorAccount:
          $ref: '#/components/schemas/AccountReference'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentInitiationBulkElementJson'
        requestedExecutionDate:
          type: string
          format: date
    PaymentInitiationJson:
      required:
      - creditorAccount
      - creditorName
      - debtorAccount
      - instructedAmount
      type: object
      properties:
        debtorAccount:
          $ref: '#/components/schemas/AccountReference'
        instructedAmount:
          $ref: '#/components/schemas/Amount'
        creditorAccount:
          $ref: '#/components/schemas/AccountReference'
        creditorName:
          maxLength: 70
          minLength: 0
          type: string
        endToEndIdentification:
          maxLength: 35
          minLength: 0
          type: string
        creditorAddress:
          $ref: '#/components/schemas/Address'
        remittanceInformationUnstructured:
          maxLength: 140
          minLength: 0
          type: string
        requestedExecutionDate:
          type: string
          format: date
    PaymentInitiationStatusResponseMinus200Json:
      required:
      - transactionStatus
      type: object
      properties:
        transactionStatus:
          type: string
          enum:
          - ACSC
          - RCVD
          - PDNG
          - RJCT
          - CANC
          - ACFC
          - PART
        psuMessage:
          maxLength: 500
          minLength: 0
          type: string
        tppMessage:
          type: array
          items:
            $ref: '#/components/schemas/TppMessage'
    PaymentInitiationWithStatusResponse:
      required:
      - creditorAccount
      - creditorName
      - debtorAccount
      - instructedAmount
      type: object
      properties:
        debtorAccount:
          $ref: '#/components/schemas/AccountReference'
        instructedAmount:
          $ref: '#/components/schemas/Amount'
        creditorAccount:
          $ref: '#/components/schemas/AccountReference'
        creditorName:
          maxLength: 70
          minLength: 0
          type: string
        endToEndIdentification:
          maxLength: 35
          minLength: 0
          type: string
        remittanceInformationUnstructured:
          maxLength: 140
          minLength: 0
          type: string
        requestedExecutionDate:
          type: string
          format: date
        transactionStatus:
          type: string
          enum:
          - ACSC
          - RCVD
          - PDNG
          - RJCT
          - CANC
          - ACFC
          - PART
    TppMessage:
      required:
      - category
      - code
      type: object
      properties:
        category:
          type: string
          enum:
          - ERROR
          - WARNING
        code:
          type: string
          enum:
          - ACCESS_EXCEEDED
          - BENEFICIARY_WHITELISTING_REQUIRED
          - CANCELLATION_INVALID
          - CERTIFICATE_BLOCKED
          - CERTIFICATE_EXPIRED
          - CERTIFICATE_INVALID
          - CERTIFICATE_MISSING
          - CERTIFICATE_REVOKE
          - CONSENT_EXPIRED
          - CONSENT_INVALID
          - CONSENT_UNKNOWN
          - CORPORATE_ID_INVALID
          - EXECUTION_DATE_INVALID
          - FORMAT_ERROR
          - FUNDS_NOT_AVAILABLE
          - KID_MISSING
          - PARAMETER_NOT_CONSISTENT
          - PARAMETER_NOT_SUPPORTED
          - PAYMENT_FAILED
          - PERIOD_INVALID
          - PRODUCT_INVALID
          - PRODUCT_UNKNOWN
          - PSU_CREDENTIALS_INVALID
          - REQUESTED_FORMATS_INVALID
          - RESOURCE_BLOCKED
          - RESOURCE_EXPIRED
          - RESOURCE_UNKNOWN
          - ROLE_INVALID
          - SCA_INVALID
          - SCA_METHOD_UNKNOWN
          - SERVICE_BLOCKED
          - SERVICE_INVALID
          - SESSIONS_NOT_SUPPORTED
          - SIGNATURE_INVALID
          - SIGNATURE_MISSING
          - STATUS_INVALID
          - TIMESTAMP_INVALID
          - TOKEN_EXPIRED
          - TOKEN_INVALID
          - TOKEN_UNKNOWN
          - WARNING
        path:
          type: string
        text:
          maxLength: 500
          minLength: 0
          type: string
    PaymentInitationRequestResponseMinus201:
      required:
      - _links
      - paymentId
      - transactionStatus
      type: object
      properties:
        transactionStatus:
          type: string
          enum:
          - ACSC
          - RCVD
          - PDNG
          - RJCT
          - CANC
          - ACFC
          - PART
        paymentId:
          type: string
        _links:
          $ref: '#/components/schemas/LinksPaymentInitiation'
        psuMessage:
          maxLength: 500
          minLength: 0
          type: string
        tppMessages:
          type: array
          items:
            $ref: '#/components/schemas/TppMessage'
    Address:
      required:
      - country
      type: object
      properties:
        country:
          pattern: ^[A-Z]{2}$
          type: string
        streetName:
          maxLength: 70
          minLength: 0
          type: string
        townName:
          type: string
        postCode:
          type: string
    HrefType:
      type: object
      properties:
        href:
          type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://client.memo.bank/authorize
          tokenUrl: /oauth2/token
          refreshUrl: /oauth2/token
          scopes:
            AIS: Account Information Service.
            PIS: Payment Initiation Service.
x-topics:
- title: Onboarding
  content: "For TPPs to be able to make a request on the API, they must follow the onboarding process.  For that, it is required from them to [send us an email](mailto:openbanking@memo.bank) with the following  elements:\n  - one or more **redirect URI** for OAuth2 authentication\n  - a valid **QSealC certificate**\n\n\nIn exchange of what they will receive:\n  - a `keyId` to be used with HTTP Signature authentication\n  - a `client_id` and a `client_secret` to be used with OAuth2 authentication\n"
- title: Authentication
  content: "## OAuth2\nWe follow the standard **Authorization Code** grant flow from OAuth2 to authenticate a TPP acting on behalf of a PSU.\n\nAs an example, in production our URLs are:\n  - Authorization URL: https://client.memo.bank/authorize\n  - Token URL: https://api.memo.bank/nextgenpsd2/oauth2/token\n  - Refresh URL: https://api.memo.bank/nextgenpsd2/oauth2/token\n\nWe strongly recommend that you send your requests to these endpoints using `application/json` or `application/x-www-form-urlencoded` as content type since query params are considered unsafe.\n\nThe `access_token` has a TTL of **2 hours** and the `refresh_token` has a TTL of **2 weeks**.\n\n## HTTP Signature\nRequests must be signed by TPPs using the private key associated to the certificate provided during  the onboarding process.\n\nWe follow the [draft-cavage-http-signatures-12](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12) to authenticate a TPP.\n\nHere is an exhaustive list of headers that must be signed:\n  - `(request-target)` (mandatory)\n  - `authorization` (mandatory)\n  - `date` (mandatory)\n  - `digest` (only if the request has a body)\n  - `host` (mandatory)\n  - `psu-corporate-id` (only if included in the request)\n  - `psu-id` (only if included in the request)\n  - `tpp-redirect-uri` (only if included in the request)\n  - `x-request-id` (only if included in the request)\n"
- title: Response formats
  content: '## Success cases

    Only the `application/json` content type is supported.


    ## Error cases

    In case of processing error, the API will use NextGenPSD2 specific solution to give additional error information in the response.


    Some errors may not follow this format if they are sent by a proxy between the client and the application.  This is the case with most authentication errors as of now.


    The `application/problem+json` content type from [RFC7807](https://datatracker.ietf.org/doc/html/rfc7807)  is not currently supported.

    '
- title: Authorisation
  content: 'Authorisations for a consent or a payment are always implicitly created and the `/authorisations`  sub-resources are not implemented.

    '
- title: Rate limiting
  content: "We enforce a rate limit on how many HTTP requests can be made in a  given period. When the limit is reached, our PSD2 API will return an error `429 Too Many Requests`.\n\nTo allow you to handle this rate limiting in a programmatic way, the following headers are sent along every response: \n- `RateLimit-Limit`: total number of available requests between two quota resets;\n- `RateLimit-Remaining`: number of available requests until the quota is reset;\n- `RateLimit-Reset`: time remaining (in seconds) until the quota is reset.\n"