--- swagger: "2.0" info: title: Mock Data Agreement API x-ibm-name: mock-data-agreement-api version: 1.0.0 contact: name: openbanking@dssbank.no license: name: Copyright © 2018-2019 LILLESANDS SPAREBANK. All rights reserved. url: https://openbanking.lillesands-sparebank.no/terms description: "API for manipulating mock data. \nAll endpoints here are only meant for testing. \nAll endpoints here are only available in sandbox and not in production.\nThe Agreement API is used to simulate corporate agreements, in private context this is created automatically.\n[**Read the developer documentation before using this API** ](https://openbanking.lillesands-sparebank.no/portal-sandbox/documentation/)\n" basePath: / schemes: - https paths: /v1/sandbox/agreements: post: description: | Only used to manage agreements for corporate customers. > Create agreement for customer. Engagements are the connection between accounts and customers. > When granting consent in test a corporate customer will first select an agreement before granting consent to accounts registered on that agreement. > Engagements must have both the role "REGISTER" and "VIEW" to be available for granting consent in the sandbox environment. > Note that the field "customer" in **engagement** points to the PSU which should see the accounts when granting consent in the PSD2 Sandbox. However the field "account" in the engagement should not be owned by the same PSU, this should be owned by the customer created as the corporation which the PSU is a member of. Also note that the field "owner" in **agreement** is also the corporation which the PSU is a member of. summary: /v1/sandbox/agreements tags: - /v1/sandbox/agreements operationId: AgreementsPost produces: - application/json;charset=utf-8 parameters: - $ref: '#/parameters/Content-Type' - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' - name: Body in: body required: true description: "" schema: $ref: '#/definitions/agreementsRequest' responses: 201: description: "" schema: $ref: '#/definitions/v1SandboxAgreements' examples: application/json;charset=utf-8: id: enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== name: Testavtale owner: 999999991 engagements: - id: enc!!s5D4NqQEMBHkWZB-bKMJPBtBfr5D6qhsKNsOQ1um5jHiJdEThVowZHquX20B7jNGop831hQj_9sXLqAVwls9OA== customer: 01085800481 account: bban: "90412263056" iban: NO2390412263056 roles: - view - register accessRights: false paymentRights: false transferRights: false registerLimit: 0 approvalLimit: 0 _links: self: href: /v1/sandbox/agreements/enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== verbs: - GET - DELETE engagements: href: /v1/sandbox/agreements/enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA==/engagements verbs: - POST - DELETE get: description: | Only for managing sandbox data, not part of the production API. Get list of all agreements created using POST /v1/sandbox/agreements. Both private and corporate agreements are shown. summary: /v1/sandbox/agreements tags: - /v1/sandbox/agreements operationId: AgreementsGet produces: - application/json;charset=utf-8 parameters: - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' responses: 200: description: "" schema: type: array items: $ref: '#/definitions/v1SandboxAgreements' examples: application/json;charset=utf-8: - id: enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg== name: Testavtavtale owner: 999999991 engagements: - id: enc!!1bRk1fK4sFyUtXGn39GeNXOVW5jeCV9D_QQ5GEpGZmGa1Juu6yA_ISHbyn7sXolF55Am8zAFoSUFSYGN7LbHag== customer: 01085800481 account: bban: "91351631959" iban: NO8591351631959 roles: - owner accessRights: true paymentRights: true transferRights: true registerLimit: 10000 approvalLimit: 10000 _links: self: href: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg== verbs: - GET - DELETE engagements: href: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg==/engagements verbs: - POST - DELETE - id: enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== name: Testavtale engagements: - id: enc!!s5D4NqQEMBHkWZB-bKMJPBtBfr5D6qhsKNsOQ1um5jHiJdEThVowZHquX20B7jNGop831hQj_9sXLqAVwls9OA== customer: 01085800481 account: bban: "90412263056" iban: NO2390412263056 roles: - view - register accessRights: false paymentRights: false transferRights: false registerLimit: 0 approvalLimit: 0 _links: self: href: /v1/sandbox/agreements/enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== verbs: - GET - DELETE engagements: href: /v1/sandbox/agreements/enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA==/engagements verbs: - POST - DELETE /v1/sandbox/agreements/{mockAgreementId}/engagements: post: description: | Add additional accounts with privileges to an agreement created using POST /v1/sandbox/agreements. > Engagements must have both the role "REGISTER" and "VIEW" to be available for granting consent in the sandbox environment. > Note that the field "customer" points to the PSU which should see the accounts when granting consent in the PSD2 Sandbox. However the field "account" should not be owned by the same PSU, this should be owned by the customer created as the corporation which the PSU is a member of. Also note that the field "owner" in **agreement** is also the corporation which the PSU is a member of. summary: /v1/sandbox/agreements/:id/engagements tags: - /v1/sandbox/agreements operationId: AgreementsEngagementsByMockAgreementIdPost produces: - application/json parameters: - name: mockAgreementId in: path required: true type: string - $ref: '#/parameters/Content-Type' - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' - name: Body in: body required: true description: "" schema: $ref: '#/definitions/engagementsRequest' responses: 201: description: CREATED schema: $ref: '#/definitions/Engagements1' delete: description: | Remove all accounts from agreement created using POST /v1/sandbox/agreements. summary: /v1/sandbox/agreements/:id/engagements tags: - /v1/sandbox/agreements operationId: AgreementsEngagementsByMockAgreementIdDelete produces: - application/json parameters: - name: mockAgreementId in: path required: true type: string description: "" - $ref: '#/parameters/Content-Type' - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' responses: 204: description: No Content /v1/sandbox/agreements/{mockAgreementId}/engagements/{mockEngagementId}: get: description: | Get single account with permissions for agreement created using POST /v1/sandbox/agreements/{mockAgreementId}/engagements. summary: /v1/sandbox/agreements/:id/engagements/:id tags: - /v1/sandbox/agreements operationId: AgreementsEngagementsByMockAgreementIdandEngagementIdGet produces: - application/json parameters: - name: mockAgreementId in: path required: true type: string - name: mockEngagementId in: path required: true type: string - $ref: '#/parameters/Content-Type' - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' responses: 200: description: OK schema: $ref: '#/definitions/Engagements1' delete: description: | Remove single account with permissions for agreement created using POST /v1/sandbox/agreements/{mockAgreementId}/engagements. summary: /v1/sandbox/agreements/:id/engagements:id tags: - /v1/sandbox/agreements operationId: AgreementsEngagementsByMockAgreementIdandEngagementIdDelete produces: - application/json parameters: - name: mockAgreementId in: path required: true type: string description: "" - name: mockEngagementId in: path required: true type: string - $ref: '#/parameters/Content-Type' - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/Digest' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' responses: 204: description: No Content /v1/sandbox/agreements/{mockAgreementId}: get: description: | Only for managing sandbox data, not part of the production API. Get single agreement created using POST /v1/sandbox/agreements. Both private and corporate agreements can be retrieved. summary: /v1/sandbox/agreements/:id tags: - /v1/sandbox/agreements operationId: AgreementsByMockAgreementIdGet produces: - application/json;charset=utf-8 parameters: - name: mockAgreementId in: path required: true type: string description: "" - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' responses: 201: description: "" schema: $ref: '#/definitions/v1SandboxAgreementswId' examples: application/json;charset=utf-8: id: enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== name: Testavtale owner: 999999991 engagements: - id: enc!!s5D4NqQEMBHkWZB-bKMJPBtBfr5D6qhsKNsOQ1um5jHiJdEThVowZHquX20B7jNGop831hQj_9sXLqAVwls9OA== customer: 01085800481 account: bban: "90412263056" iban: NO2390412263056 roles: - view - register accessRights: false paymentRights: false transferRights: false registerLimit: 0 approvalLimit: 0 _links: [] delete: description: Delete an agreement created using POST /v1/sandbox/agreements. summary: /v1/sandbox/agreements/:id tags: - /v1/sandbox/agreements operationId: AgreementsByMockAgreementIdDelete produces: - application/json parameters: - name: mockAgreementId in: path required: true type: string description: "" - $ref: '#/parameters/Accept' - $ref: '#/parameters/Accept-Charset' - $ref: '#/parameters/Accept-Encoding' - $ref: '#/parameters/Accept-Language' - $ref: '#/parameters/Host' - $ref: '#/parameters/X-Request-ID' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' responses: 204: description: No Content parameters: Accept: name: Accept in: header type: string required: false description: Advertises which content types, expressed as MIME types, the client is able to understand. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice with the Content-Type response header. x-example: application/json Accept-Charset: name: Accept-Charset in: header type: string required: false description: Advertises which character set the client is able to understand. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice within the Content-Type response header. x-example: utf-8 Accept-Encoding: name: Accept-Encoding in: header required: false type: string description: Advertises which content encoding, usually a compression algorithm, the client is able to understand. Using content negotiation, the server selects one of the proposals, uses it and informs the client of its choice with the Content-Encoding response header. x-example: deflate, gzip;q=1.0, *;q=0.5 Accept-Language: name: Accept-Language in: header description: Advertises which natural languages the client is able to understand, and which locale variant is preferred. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice with the Content-Language response header. required: false type: string x-example: en-US,en;q=0.7,nb;q=0.3 Host: name: Host in: header type: string required: false description: The domain name of the server (for virtual hosting), and (optionally) the TCP port number on which the server is listening. x-example: http://lbxp02vip.unix.cosng.net:20100/secesb/rest/era-psd2 Content-Type: name: Content-Type in: header required: false type: string description: Advertises what type of data is actually sent. X-Request-ID: name: X-Request-ID in: header type: string required: true description: Request identifier, unique to the call, as determined by the TPP. x-example: 4eba4445-1a4b-47b8-bdd5-4e56ef026b19 Digest: name: Digest in: header type: string required: true description: "Base64 encoded sha256 or sha512 hash of the message body, used with the signature.\n>\nThe Digest header is defined by RFC3230 and sha256/sha512 si defined by RFC5843. " x-example: MIFFTzCCAzegAkIBAgMJANnQVDLqktJUMA0GCS....8WLZOabcX3YxNoH4k== TPP-Signature-Certificate: name: TPP-Signature-Certificate in: header type: string required: true description: The certificate used for signing the request in base64 encoding. x-example: MIFFTzCCAzegAkIBAgMJANnQVDLqktJUMA0GCS....8WLZOX3YxNoH4k== Signature: name: Signature in: header type: string required: true description: | HTTP Message Signature as specified by https://tools.ietf.org/html/draft-cavage-http-signatures-10 with requirements imposed by Berlin Group's NextGenPSD2 Framework. - *keyId* must be formatted as `keyId="SN=XXX,CA=YYY"` where `XXX` is the serial number of the signing certificate in hexadecimal encoding and `YYY` is the ful Distinguished Name of the Certificate Authority having certificate - *algorithm* must identify the same algorithm for the signature as presented in the signing certificate and should be `rsa-sha256` - *headers* must contain `date`, `digest`, `x-request-id`, `psu-id`, `psu-corporate-id`, and `tpp-redirect-uri` when available - *signature* must be computed as `Base64(RSA-SHA256(signingString))` If any values in the signature header is ISO-8859-1 or UTF-8 encoded you need to URL encode the signature header according to RFC 2047 which means MIME encoding the signature. Also the signature must be wrapped using this format: =?charset?encoding?encoded signature?= Example of this encoding: `=?utf-8?B?a2V5QTQsQ0E9Mi41LjQuOTc9IzB........jMTM1MDUzNDQ0ZTRmMmQ0NjUz?=` Java example of how to implement encoding: ``` if (charset.equals(StandardCharsets.UTF_8)) { signature = String.format("=?utf-8?B?%s?=", Base64.getEncoder().encodeToString(signature.getBytes(StandardCharsets.UTF_8))); } ``` x-example: keyId="SN=6AEB4444FBAAD267,CA=O=PSDNO-FSA-ABCA,L=Trondheim,C=NO", algorithm="rsa-sha256", headers="date x-request-id tpp-redirect-uri psu-id", signature="***************" definitions: Self: title: Self example: href: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg== verbs: - GET - DELETE type: object properties: href: type: string verbs: type: array items: type: string required: - href - verbs Links1: title: Links1 example: self: href: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg== verbs: - GET - DELETE engagements: href: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg==/engagements verbs: - POST - DELETE type: object properties: self: $ref: '#/definitions/Self' engagements: $ref: '#/definitions/Engagements' required: - self - engagements Engagements: title: Engagements example: href: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg==/engagements verbs: - POST - DELETE type: object properties: href: example: /v1/sandbox/agreements/enc!!9LnOfAAQ-HgKXsU61DSZc0b1M9k-2FkJ4Hunsoe4mfTD3AOU_Evq91NkmNgd1lK9RRT6jE7MV7aAPxm7gMrQLg==/engagements type: string verbs: example: - POST - DELETE type: array items: type: string required: - href - verbs agreementsRequest: title: /v1/sandbox/agreementsRequest example: owner: "12345678" name: Testavtale engagements: - customer: 01085800481 account: iban: NO8626743379224 roles: - VIEW - REGISTER type: object properties: owner: type: string name: type: string engagements: type: array items: $ref: '#/definitions/Engagements1' required: - owner - name - engagements Engagements1: title: Engagements1 type: object properties: customer: example: 01085800481 type: string account: $ref: '#/definitions/Account' roles: example: - VIEW - REGISTER type: array items: type: string enum: - OWNER - DISPOSAL - VIEW - REGISTER - APPROVE - INTERNAL_TRANSFER - SALARY registerLimit: example: 0 type: integer format: int32 approvalLimit: example: 0 type: integer format: int32 required: - customer - account - roles - registerLimit - approvalLimit Account: title: Account example: iban: NO8626743379224 type: object properties: iban: example: NO8626743379224 type: string required: - iban v1SandboxAgreements: title: /v1/sandbox/agreements example: id: enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== name: Testavtale engagements: - id: enc!!s5D4NqQEMBHkWZB-bKMJPBtBfr5D6qhsKNsOQ1um5jHiJdEThVowZHquX20B7jNGop831hQj_9sXLqAVwls9OA== customer: 01085800481 owner: 999999991 account: bban: "90412263056" iban: NO2390412263056 roles: - view - register accessRights: false paymentRights: false transferRights: false registerLimit: 0 approvalLimit: 0 _links: self: href: /v1/sandbox/agreements/enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== verbs: - GET - DELETE engagements: href: /v1/sandbox/agreements/enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA==/engagements verbs: - POST - DELETE type: object properties: id: type: string name: type: string owner: type: string engagements: type: array items: $ref: '#/definitions/Engagements2' _links: $ref: '#/definitions/Links1' required: - id - name - engagements - _links Engagements2: title: Engagements2 type: object properties: id: example: enc!!s5D4NqQEMBHkWZB-bKMJPBtBfr5D6qhsKNsOQ1um5jHiJdEThVowZHquX20B7jNGop831hQj_9sXLqAVwls9OA== type: string customer: example: 01085800481 type: string name: example: ABC type: string account: $ref: '#/definitions/Account1' roles: example: - view - register type: array items: type: string enum: - OWNER - DISPOSAL - VIEW - REGISTER - APPROVE - INTERNAL_TRANSFER - SALARY accessRights: example: false type: boolean paymentRights: example: false type: boolean transferRights: example: false type: boolean registerLimit: example: 0 type: integer format: int32 approvalLimit: example: 0 type: integer format: int32 required: - id - customer - account - roles - accessRights - paymentRights - transferRights - registerLimit - approvalLimit Account1: title: Account1 example: bban: "90412263056" iban: NO2390412263056 type: object properties: bban: example: "90412263056" type: string iban: example: NO2390412263056 type: string required: - bban - iban engagementsRequest: title: /v1/sandbox/agreements/:id/engagementsRequest example: customer: 01085800481 account: iban: NO8626743379224 roles: - REGISTER - VIEW type: object properties: customer: type: string account: $ref: '#/definitions/Account' roles: type: array items: type: string enum: - OWNER - DISPOSAL - VIEW - REGISTER - APPROVE - INTERNAL_TRANSFER - SALARY registerLimit: example: 0 type: integer format: int32 approvalLimit: example: 0 type: integer format: int32 required: - customer - account - roles - registerLimit - approvalLimit v1SandboxAgreementswId: title: /v1/sandbox/agreements/:id example: id: enc!!oHc4g0K00_s2115LNqycmoQWN8tluC1Apmivegog7Ix3EpASoZ-Doe3mR7tuLEyvRbS7CdzKM1FnHYKx4KTKyA== name: Testavtale owner: 999999991 engagements: - id: enc!!s5D4NqQEMBHkWZB-bKMJPBtBfr5D6qhsKNsOQ1um5jHiJdEThVowZHquX20B7jNGop831hQj_9sXLqAVwls9OA== customer: 01085800481 name: ABC account: bban: "90412263056" iban: NO2390412263056 roles: - view - register accessRights: false paymentRights: false transferRights: false registerLimit: 0 approvalLimit: 0 _links: [] type: object properties: id: type: string name: type: string owner: type: string engagements: type: array items: $ref: '#/definitions/Engagements2' _links: type: object required: - id - name - engagements - _links tags: - name: /v1/sandbox/agreements x-ibm-configuration: enforced: true testable: true phase: realized x-ibm-endpoints: - endpointUrl: https://openbanking.lillesands-sparebank.no/api-sandbox type: - production - development ...