---
swagger: "2.0"
info:
  title: PISP Domestic Standing Orders REST API BOS
  description: Swagger for Standing Orders REST API Specification
  version: v3.1.10
  termsOfService: https://www.openbanking.org.uk/terms
  contact:
    name: Service Desk
    email: ServiceDesk@openbanking.org.uk
  license:
    name: open-licence
    url: https://www.openbanking.org.uk/open-licence
  x-ibm-name: pisp-domestic-standing-orders-api-bos
schemes:
- https
basePath: /bos/open-banking/v3.1/pisp
tags:
- name: Standing Orders REST APIs
consumes:
- application/json; charset=UTF-8
produces:
- application/json; charset=UTF-8
securityDefinitions:
  PSUOAuth2Security:
    type: oauth2
    flow: accessCode
    tokenUrl: https://secure-api.bankofscotland.co.uk/prod01/lbg/bos/oidc-api/v1.1/token
    authorizationUrl: https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/personal/oidc-api/v1.1/authorize
    scopes:
      payments: Generic payment scope
      openid: Enable OpenID
    description: OAuth flow, it is required when the PSU needs to perform SCA with
      the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU. The
      below example Authorization URL shows the personal channel. For business and
      commercial specific authorization URLs please refer to the **well known endpoint**
      or the **Technical Implementation Guide**.
  TPPOAuth2Security:
    type: oauth2
    flow: application
    tokenUrl: https://secure-api.bankofscotland.co.uk/prod01/lbg/bos/oidc-api/v1.1/token
    scopes:
      payments: Generic payment scopes
      tpp_client_credential: TPP Client Credential Scope for accounts and payments
        api
    description: TPP client credential authorisation flow with the ASPSP
paths:
  /domestic-standing-order-consents:
    post:
      tags:
      - Domestic Standing Order Consents
      summary: Create a domestic standing order consent
      description: Create a domestic standing order consent
      operationId: createDomesticStandingOrderConsent
      consumes:
      - application/json;charset=UTF-8
      produces:
      - application/json;charset=UTF-8
      parameters:
      - $ref: '#/parameters/xFapiFinancialId'
      - $ref: '#/parameters/xFapiCustomerLastLoggedTime'
      - $ref: '#/parameters/xFapiCustomerIpAddress'
      - $ref: '#/parameters/xFapiInteractionId'
      - $ref: '#/parameters/xIdempotencyKey'
      - $ref: '#/parameters/xJwsSignature'
      - $ref: '#/parameters/DomesticStandingOrderConsentRequest'
      - $ref: '#/parameters/Authorization'
      responses:
        201:
          description: Created
          headers:
            x-fapi-interaction-id:
              type: string
            x-jws-signature:
              type: string
          schema:
            $ref: '#/definitions/DomesticStandingOrderConsentResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not found
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - TPPOAuth2Security:
        - payments
  /domestic-standing-order-consents/{ConsentId}:
    get:
      tags:
      - Domestic Standing Order Consents
      summary: Get a domestic standing order consent
      description: Get a domestic standing order consent
      operationId: getDomesticStandingOrderConsent
      consumes:
      - application/json;charset=UTF-8
      produces:
      - application/json;charset=UTF-8
      parameters:
      - $ref: '#/parameters/ConsentId'
      - $ref: '#/parameters/xFapiFinancialId'
      - $ref: '#/parameters/xFapiCustomerLastLoggedTime'
      - $ref: '#/parameters/xFapiCustomerIpAddress'
      - $ref: '#/parameters/xFapiInteractionId'
      - $ref: '#/parameters/Authorization'
      responses:
        200:
          description: OK
          headers:
            x-fapi-interaction-id:
              type: string
            x-jws-signature:
              type: string
          schema:
            $ref: '#/definitions/DomesticStandingOrderConsentResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not found
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - TPPOAuth2Security:
        - payments
  /domestic-standing-orders:
    post:
      tags:
      - Domestic Standing Orders
      summary: Create a domestic standing order
      description: Create a domestic standing order
      operationId: createDomesticStandingOrder
      consumes:
      - application/json;charset=UTF-8
      produces:
      - application/json;charset=UTF-8
      parameters:
      - $ref: '#/parameters/xFapiFinancialId'
      - $ref: '#/parameters/xFapiCustomerLastLoggedTime'
      - $ref: '#/parameters/xFapiCustomerIpAddress'
      - $ref: '#/parameters/xFapiInteractionId'
      - $ref: '#/parameters/xIdempotencyKey'
      - $ref: '#/parameters/xJwsSignature'
      - $ref: '#/parameters/DomesticStandingOrderRequest'
      - $ref: '#/parameters/Authorization'
      responses:
        201:
          description: Created
          headers:
            x-fapi-interaction-id:
              type: string
            x-jws-signature:
              type: string
          schema:
            $ref: '#/definitions/DomesticStandingOrderResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not found
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - PSUOAuth2Security:
        - payments
  /domestic-standing-orders/{DomesticStandingOrderId}:
    get:
      tags:
      - Domestic Standing Orders
      summary: Get a domestic standing order
      description: Get a domestic standing order
      operationId: getDomesticStandingOrder
      consumes:
      - application/json;charset=UTF-8
      produces:
      - application/json;charset=UTF-8
      parameters:
      - $ref: '#/parameters/DomesticStandingOrderId'
      - $ref: '#/parameters/xFapiFinancialId'
      - $ref: '#/parameters/xFapiCustomerLastLoggedTime'
      - $ref: '#/parameters/xFapiCustomerIpAddress'
      - $ref: '#/parameters/xFapiInteractionId'
      - $ref: '#/parameters/Authorization'
      responses:
        200:
          description: OK
          headers:
            x-fapi-interaction-id:
              type: string
            x-jws-signature:
              type: string
          schema:
            $ref: '#/definitions/DomesticStandingOrderResponse'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResponse'
        401:
          description: Unauthorized
        403:
          description: Forbidden
        404:
          description: Not found
        500:
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
      - TPPOAuth2Security:
        - payments
parameters:
  xFapiFinancialId:
    name: x-fapi-financial-id
    in: header
    description: The unique id of the ASPSP to which the request is issued. The unique
      id will be issued by OB.
    type: string
    required: true
  Authorization:
    in: header
    name: Authorization
    type: string
    required: true
    description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
  xFapiCustomerLastLoggedTime:
    name: x-fapi-customer-last-logged-time
    in: header
    description: 'The time when the PSU last logged in with the TPP. All dates in
      the HTTP headers are represented as RFC 7231 Full Dates. An example is below:
      Sun, 10 Sep 2017 19:43:31 UTC'
    pattern: ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
      \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$
    type: string
    required: false
  xFapiCustomerIpAddress:
    name: x-fapi-customer-ip-address
    in: header
    description: The IP address of the customer
    type: string
    required: false
  xFapiInteractionId:
    name: x-fapi-interaction-id
    in: header
    description: An RFC4122 UID used as a correlation ID.
    type: string
    required: false
    pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  xIdempotencyKey:
    name: x-idempotency-key
    in: header
    description: Every request will be processed only once per x-idempotency-key.
    type: string
    required: true
  xJwsSignature:
    name: x-jws-signature
    in: header
    description: A detached JWS signature of the body of the payload.
    type: string
    required: true
  DomesticStandingOrderConsentRequest:
    name: body
    in: body
    description: Domestic standing order consent request body
    required: true
    schema:
      $ref: '#/definitions/DomesticStandingOrderConsentRequest'
  ConsentId:
    name: ConsentId
    in: path
    description: A unique identifier used to identify the consent
    required: true
    type: string
  DomesticStandingOrderRequest:
    name: body
    in: body
    description: Domestic standing order request body
    required: true
    schema:
      $ref: '#/definitions/DomesticStandingOrderRequest'
  DomesticStandingOrderId:
    name: DomesticStandingOrderId
    in: path
    description: A unique identifier used to identify the domestic standing order
    required: true
    type: string
definitions:
  DomesticStandingOrderConsentRequest:
    type: object
    required:
    - Data
    - Risk
    properties:
      Data:
        $ref: '#/definitions/DomesticStandingOrderConsentRequestData'
      Risk:
        $ref: '#/definitions/Risk'
  DomesticStandingOrderConsentRequestData:
    type: object
    required:
    - Permission
    - Initiation
    properties:
      Permission:
        $ref: '#/definitions/Permission'
      ReadRefundAccount:
        description: Specifies to share the refund account details with PISP
        type: string
        enum:
        - "No"
        - "Yes"
      Initiation:
        $ref: '#/definitions/Initiation'
      Authorisation:
        $ref: '#/definitions/Authorisation'
      SCASupportData:
        type: object
        additionalProperties: false
        description: Supporting Data provided by TPP, when requesting SCA Exemption.
        properties:
          RequestedSCAExemptionType:
            description: This field allows a PISP to request specific SCA Exemption
              for a Payment Initiation
            type: string
            enum:
            - BillPayment
            - ContactlessTravel
            - EcommerceGoods
            - EcommerceServices
            - Kiosk
            - Parking
            - PartyToParty
          AppliedAuthenticationApproach:
            description: |-
              Specifies a character string with a maximum length of 40 characters.
              Usage: This field indicates whether the PSU was subject to SCA performed by the TPP
            type: string
            maxLength: 40
            enum:
            - CA
            - SCA
          ReferencePaymentOrderId:
            description: |-
              Specifies a character string with a maximum length of 140 characters.
              Usage: If the payment is recurring then the transaction identifier of the previous payment occurrence so that the ASPSP can verify that the PISP, amount and the payee are the same as the previous occurrence.
            type: string
            minLength: 1
            maxLength: 40
  DomesticStandingOrderRequest:
    type: object
    required:
    - Data
    - Risk
    properties:
      Data:
        $ref: '#/definitions/DomesticStandingOrderRequestData'
      Risk:
        $ref: '#/definitions/Risk'
  DomesticStandingOrderRequestData:
    type: object
    required:
    - ConsentId
    - Initiation
    properties:
      ConsentId:
        type: string
        minLength: 1
        maxLength: 128
      Initiation:
        $ref: '#/definitions/Initiation'
  Permission:
    type: string
    enum:
    - Create
  Initiation:
    type: object
    required:
    - Frequency
    - FirstPaymentDateTime
    - FirstPaymentAmount
    - CreditorAccount
    properties:
      Frequency:
        $ref: '#/definitions/Frequency'
      Reference:
        $ref: '#/definitions/Reference'
      FirstPaymentDateTime:
        $ref: '#/definitions/DateTime'
      RecurringPaymentDateTime:
        $ref: '#/definitions/DateTime'
      FinalPaymentDateTime:
        $ref: '#/definitions/DateTime'
      FirstPaymentAmount:
        $ref: '#/definitions/Amount'
      RecurringPaymentAmount:
        $ref: '#/definitions/Amount'
      FinalPaymentAmount:
        $ref: '#/definitions/Amount'
      DebtorAccount:
        $ref: '#/definitions/DebtorAccount'
      CreditorAccount:
        $ref: '#/definitions/CreditorAccount'
  Frequency:
    type: string
    minLength: 1
    maxLength: 35
    pattern: ^(IntrvlWkDay:(01|04):0[1-5])$|^(IntrvlMnthDay:(01|03|06|12|02):(-0[1-5]|0[1-9]|[12][0-9]|3[01]))$
  Reference:
    type: string
    minLength: 1
    maxLength: 35
  DateTime:
    type: string
    format: date-time
  Amount:
    type: object
    required:
    - Amount
    - Currency
    properties:
      Amount:
        type: string
        pattern: ^\d{1,13}$|^\d{1,13}\.\d{1,2}$
      Currency:
        type: string
        enum:
        - GBP
  DebtorAccount:
    type: object
    required:
    - SchemeName
    - Identification
    properties:
      SchemeName:
        type: string
        enum:
        - IBAN
        - SortCodeAccountNumber
        - BBAN
      Identification:
        type: string
        minLength: 1
        maxLength: 256
      Name:
        type: string
        minLength: 1
        maxLength: 350
      SecondaryIdentification:
        type: string
        minLength: 1
        maxLength: 34
  CreditorAccount:
    type: object
    required:
    - SchemeName
    - Identification
    - Name
    properties:
      SchemeName:
        type: string
        enum:
        - IBAN
        - SortCodeAccountNumber
      Identification:
        type: string
        minLength: 1
        maxLength: 256
      Name:
        type: string
        minLength: 1
        maxLength: 350
      SecondaryIdentification:
        type: string
        minLength: 1
        maxLength: 34
  Authorisation:
    type: object
    required:
    - AuthorisationType
    properties:
      AuthorisationType:
        type: string
        enum:
        - Any
        - Single
      CompletionDateTime:
        type: string
        format: date-time
  Risk:
    type: object
    required:
    - PaymentContextCode
    properties:
      PaymentContextCode:
        type: string
        enum:
        - BillPayment
        - EcommerceGoods
        - EcommerceServices
        - Other
        - PartyToParty
        - BillingGoodsAndServicesInAdvance
        - BillingGoodsAndServicesInArrears
        - PispPayee
        - EcommerceMerchantInitiatedPayment
        - FaceToFacePointOfSale
        - TransferToSelf
        - TransferToThirdParty
      MerchantCategoryCode:
        type: string
        minLength: 3
        maxLength: 4
      MerchantCustomerIdentification:
        type: string
        minLength: 1
        maxLength: 70
      ContractPresentInidicator:
        type: boolean
        description: Indicates if Payee has a contractual relationship with the PISP.
      BeneficiaryPrepopulatedIndicator:
        type: boolean
        description: Indicates if PISP has immutably prepopulated payment details
          in for the PSU.
      PaymentPurposeCode:
        type: string
        minLength: 3
        maxLength: 4
        description: Category code, related to the type of services or goods that
          corresponds to the underlying purpose of the payment that conforms to Recommended
          UK Purpose Code in ISO 20022 Payment Messaging List
      BeneficiaryAccountType:
        $ref: '#/definitions/OBExternalExtendedAccountType1Code'
      DeliveryAddress:
        $ref: '#/definitions/DeliveryAddress'
  OBExternalExtendedAccountType1Code:
    description: Specifies the extended type of account.
    type: string
    enum:
    - Business
    - BusinessSavingsAccount
    - Charity
    - Collection
    - Corporate
    - Ewallet
    - Government
    - Investment
    - ISA
    - JointPersonal
    - Pension
    - Personal
    - PersonalSavingsAccount
    - Premier
    - Wealth
  DeliveryAddress:
    type: object
    required:
    - TownName
    - Country
    properties:
      AddressLine:
        type: array
        items:
          type: string
          minLength: 1
          maxLength: 70
        minItems: 0
        maxItems: 2
      StreetName:
        type: string
        minLength: 1
        maxLength: 70
      BuildingNumber:
        type: string
        minLength: 1
        maxLength: 16
      PostCode:
        type: string
        minLength: 1
        maxLength: 16
      TownName:
        type: string
        minLength: 1
        maxLength: 35
      CountrySubDivision:
        type: string
        minLength: 1
        maxLength: 35
      Country:
        type: string
        pattern: '[A-Z]{2}'
  DomesticStandingOrderConsentsResponse:
    type: array
    items:
      $ref: '#/definitions/DomesticStandingOrderConsentResponse'
  DomesticStandingOrderConsentResponse:
    type: object
    required:
    - Data
    - Risk
    properties:
      Data:
        $ref: '#/definitions/DomesticStandingOrderConsentResponseData'
      Risk:
        $ref: '#/definitions/Risk'
  DomesticStandingOrderConsentResponseData:
    type: object
    required:
    - ConsentId
    - CreationDateTime
    - Status
    - StatusUpdateDateTime
    - Permission
    - Initiation
    properties:
      ConsentId:
        type: string
        minLength: 1
        maxLength: 128
      CreationDateTime:
        type: string
        format: date-time
      Status:
        $ref: '#/definitions/Status'
      StatusUpdateDateTime:
        type: string
        format: date-time
      Permission:
        $ref: '#/definitions/Permission'
      CutOffDateTime:
        type: string
        format: date-time
      Charges:
        items:
          $ref: '#/definitions/Charge'
        type: array
      ReadRefundAccount:
        description: Specifies to share the refund account details with PISP
        type: string
        enum:
        - "No"
        - "Yes"
      Initiation:
        $ref: '#/definitions/Initiation'
      Authorisation:
        $ref: '#/definitions/Authorisation'
      SCASupportData:
        type: object
        additionalProperties: false
        description: Supporting Data provided by TPP, when requesting SCA Exemption.
        properties:
          RequestedSCAExemptionType:
            description: This field allows a PISP to request specific SCA Exemption
              for a Payment Initiation
            type: string
            enum:
            - BillPayment
            - ContactlessTravel
            - EcommerceGoods
            - EcommerceServices
            - Kiosk
            - Parking
            - PartyToParty
          AppliedAuthenticationApproach:
            description: |-
              Specifies a character string with a maximum length of 40 characters.
              Usage: This field indicates whether the PSU was subject to SCA performed by the TPP
            type: string
            enum:
            - CA
            - SCA
          ReferencePaymentOrderId:
            description: |-
              Specifies a character string with a maximum length of 140 characters.
              Usage: If the payment is recurring then the transaction identifier of the previous payment occurrence so that the ASPSP can verify that the PISP, amount and the payee are the same as the previous occurrence.
            type: string
            minLength: 1
            maxLength: 40
      Debtor:
        $ref: '#/definitions/OBDebtorIdentification1'
  OBDebtorIdentification1:
    type: object
    additionalProperties: false
    description: Set of elements used to identify a person or an organisation.
    properties:
      Name:
        type: string
        description: The account name is the name or names of the account owner(s)
          represented at an account level, as displayed by the ASPSP's online channels.
          Note, the account name is not the product name or the nickname of the account.
      SchemeName:
        type: string
        enum:
        - IBAN
        - SortCodeAccountNumber
        - BBAN
      Identification:
        type: string
      SecondaryIdentification:
        type: string
  DomesticStandingOrderResponse:
    type: object
    required:
    - Data
    properties:
      Data:
        $ref: '#/definitions/DomesticStandingOrderResponseData'
  DomesticStandingOrderResponseData:
    type: object
    required:
    - DomesticStandingOrderId
    - ConsentId
    - CreationDateTime
    - Status
    - StatusUpdateDateTime
    - Initiation
    properties:
      DomesticStandingOrderId:
        type: string
        minLength: 1
        maxLength: 40
      ConsentId:
        type: string
        minLength: 1
        maxLength: 128
      CreationDateTime:
        type: string
        format: date-time
      Status:
        $ref: '#/definitions/Status'
      StatusUpdateDateTime:
        type: string
        format: date-time
      Charges:
        items:
          $ref: '#/definitions/Charge'
        type: array
      Refund:
        type: object
        additionalProperties: false
        required:
        - Account
        description: Unambiguous identification of the refund account to which a refund
          will be made as a result of the transaction.
        properties:
          Account:
            type: object
            additionalProperties: false
            required:
            - SchemeName
            - Identification
            - Name
            description: Provides the details to identify an account.
            properties:
              SchemeName:
                type: string
                enum:
                - IBAN
                - SortCodeAccountNumber
              Identification:
                type: string
                minLength: 1
                maxLength: 256
              Name:
                description: |-
                  Name of the account, as assigned by the account servicing institution.
                  Usage: The account name is the name or names of the account owner(s) represented at an account level. The account name is not the product name or the nickname of the account.
                  OB: ASPSPs may carry out name validation for Confirmation of Payee, but it is not mandatory.
                type: string
                minLength: 1
                maxLength: 350
              SecondaryIdentification:
                type: string
                minLength: 1
                maxLength: 34
      Initiation:
        $ref: '#/definitions/Initiation'
      MultiAuthorisation:
        $ref: '#/definitions/MultiAuthorisation'
      Debtor:
        type: object
        additionalProperties: false
        description: Set of elements used to identify a person or an organisation.
        properties:
          Name:
            type: string
            description: The account name is the name or names of the account owner(s)
              represented at an account level, as displayed by the ASPSP's online
              channels. Note, the account name is not the product name or the nickname
              of the account.
            minLength: 0
            maxLength: 350
  Status:
    type: string
    enum:
    - Authorised
    - AwaitingAuthorisation
    - Consumed
    - Rejected
  Charge:
    required:
    - ChargeBearer
    - Type
    - Amount
    properties:
      ChargeBearer:
        type: string
        enum:
        - BorneByCreditor
        - BorneByDebtor
        - FollowingServiceLevel
        - Shared
      Type:
        type: string
        minLength: 1
        maxLength: 40
      Amount:
        $ref: '#/definitions/Amount'
  MultiAuthorisation:
    type: object
    required:
    - Status
    properties:
      Status:
        type: string
        enum:
        - Authorised
        - AwaitingFurtherAuthorisation
        - Rejected
      NumberRequired:
        type: integer
        format: int32
      NumberReceived:
        type: integer
        format: int32
      LastUpdateDateTime:
        type: string
        format: date-time
      ExpirationDateTime:
        type: string
        format: date-time
  ErrorResponse:
    type: object
    required:
    - Code
    - Message
    - Errors
    properties:
      Code:
        type: string
        minLength: 1
        maxLength: 40
      Id:
        type: string
        minLength: 1
        maxLength: 40
      Message:
        type: string
        minLength: 1
        maxLength: 500
      Errors:
        items:
          $ref: '#/definitions/Error'
        type: array
        minItems: 1
  Error:
    type: object
    required:
    - ErrorCode
    - Message
    properties:
      ErrorCode:
        type: string
        minLength: 1
        maxLength: 128
      Message:
        type: string
        minLength: 1
        maxLength: 500
      Path:
        type: string
        minLength: 1
        maxLength: 500
      Url:
        type: string
x-ibm-configuration:
  enforced: true
  testable: true
  phase: realized
x-ibm-endpoints:
- endpointUrl: https://secure-api.lloydsbank.com/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.halifax.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.bankofscotland.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api.mbna.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api.halifax.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api.bankofscotland.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.mbna.co.uk/prod01/lbg
  type:
  - production
- endpointUrl: https://secure-api-eidas.lloydsbank.com/prod01/lbg
  type:
  - production
...