--- swagger: "2.0" info: title: Signing Basket API x-ibm-name: signing-basket-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: | [**Read the developer documentation before using this API** ](https://openbanking.lillesands-sparebank.no/portal-sandbox/documentation/) basePath: / tags: - name: /v1/signing-baskets schemes: - https paths: /v1/signing-baskets: post: tags: - /v1/signing-baskets summary: Creates a new signing basket given a set of paymentIds. description: | The payments must have been created using POST /v1/{payment-product} and the TPP must store the payment-ids until the signing basket is created. A signing basket operation is not atomic. Even if a signing basket only has a single status it only represents the worst case of all payments inside it. To get the status of individual payments, each payment status must be queried independently using GET /v1/{payment-product}/{payment-id}/status. operationId: createSigningBasket consumes: - application/json;charset=UTF-8 produces: - application/json;charset=UTF-8 parameters: - in: body name: body description: payload required: true schema: $ref: '#/definitions/SigningBasketRequest' - $ref: '#/parameters/x-accept-fix' - $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-Session-ID' - $ref: '#/parameters/TPP-Redirect-URI' - $ref: '#/parameters/TPP-Redirect-Preferred' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-IP-Address' - $ref: '#/parameters/PSU-IP-Port' - $ref: '#/parameters/PSU-User-Agent' - $ref: '#/parameters/PSU-Accept' - $ref: '#/parameters/PSU-Accept-Charset' - $ref: '#/parameters/PSU-Accept-Encoding' - $ref: '#/parameters/PSU-Accept-Language' - $ref: '#/parameters/PSU-HTTP-Method' - $ref: '#/parameters/PSU-Device-ID' - $ref: '#/parameters/PSU-Geo-Location' responses: 201: description: CREATED schema: $ref: '#/definitions/SigningBasket' 400: description: REFERENCE_MIX_INVALID schema: $ref: '#/definitions/Error' 401: description: Unauthorized schema: $ref: '#/definitions/Challenge' 404: description: RESOURCE_UNKNOWN schema: $ref: '#/definitions/Error' 500: description: Internal Server Error schema: $ref: '#/definitions/Error' examples: SYSTEM_ERROR: id: "5615873378" system: ERA-PSD2 status: 500 code: SYSTEM_ERROR /v1/signing-baskets/{basketId}/authorisations: post: tags: - /v1/signing-baskets summary: Starts the authorisation process of a signing basket. description: |2 This works like the authorisation flow for a single payment works. A signing basket operation is not atomic. Even if a signing basket only has a single status it only represents the worst case of all payments inside it. To get the status of individual payments, each payment status must be queried independently using GET /v1/{payment-product}/{payment-id}/status. operationId: createAuthorization consumes: - application/json;charset=UTF-8 produces: - application/json;charset=UTF-8 parameters: - name: basketId in: path description: Id of the signing basket. required: true type: string x-example: enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjRx5n== - $ref: '#/parameters/x-accept-fix' - $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-Session-ID' - $ref: '#/parameters/TPP-Redirect-URI' - $ref: '#/parameters/TPP-Redirect-Preferred' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-IP-Address' - $ref: '#/parameters/PSU-IP-Port' - $ref: '#/parameters/PSU-User-Agent' - $ref: '#/parameters/PSU-Accept' - $ref: '#/parameters/PSU-Accept-Charset' - $ref: '#/parameters/PSU-Accept-Encoding' - $ref: '#/parameters/PSU-Accept-Language' - $ref: '#/parameters/PSU-HTTP-Method' - $ref: '#/parameters/PSU-Device-ID' - $ref: '#/parameters/PSU-Geo-Location' responses: 201: description: CREATED schema: $ref: '#/definitions/PaymentAuthorization' 400: description: RESOURCE_BLOCKED schema: $ref: '#/definitions/Error' 401: description: Unauthorized schema: $ref: '#/definitions/Challenge' 404: description: RESOURCE_UNKNOWN schema: $ref: '#/definitions/Error' 500: description: Internal Server Error schema: $ref: '#/definitions/Error' examples: SYSTEM_ERROR: id: "5615873378" system: ERA-PSD2 status: 500 code: SYSTEM_ERROR /v1/signing-baskets/{basketId}: get: tags: - /v1/signing-baskets summary: Gets the singular status of a signing basket and a list of all the paymentIds it contains. description: | A signing basket operation is not atomic. Even if a signing basket only has a single status it only represents the worst case of all payments inside it. To get the status of individual payments, each payment status must be queried independently using GET /v1/{payment-product}/{payment-id}/status. operationId: getSigningBasket produces: - application/json;charset=UTF-8 parameters: - name: basketId in: path description: Id of the signing basket. required: true type: string x-example: enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjRx5n== - $ref: '#/parameters/x-accept-fix' - $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-Session-ID' - $ref: '#/parameters/TPP-Redirect-URI' - $ref: '#/parameters/TPP-Redirect-Preferred' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-IP-Address' - $ref: '#/parameters/PSU-IP-Port' - $ref: '#/parameters/PSU-User-Agent' - $ref: '#/parameters/PSU-Accept' - $ref: '#/parameters/PSU-Accept-Charset' - $ref: '#/parameters/PSU-Accept-Encoding' - $ref: '#/parameters/PSU-Accept-Language' - $ref: '#/parameters/PSU-HTTP-Method' - $ref: '#/parameters/PSU-Device-ID' - $ref: '#/parameters/PSU-Geo-Location' responses: 200: description: OK schema: $ref: '#/definitions/SigningBasketItems' 401: description: Unauthorized schema: $ref: '#/definitions/Challenge' 404: description: RESOURCE_UNKNOWN schema: $ref: '#/definitions/Error' 500: description: Internal Server Error schema: $ref: '#/definitions/Error' examples: SYSTEM_ERROR: id: "5615873378" system: ERA-PSD2 status: 500 code: SYSTEM_ERROR delete: tags: - /v1/signing-baskets summary: Deletes a signing basket before it has been authorised description: | Delete a signing basket. This operation may be performed only if no authorisation attemts has been made on the signing basket. operationId: deleteSigningBasket produces: - application/json;charset=UTF-8 parameters: - name: basketId in: path description: Id of the signing basket. required: true type: string x-example: enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjRx5n== - $ref: '#/parameters/x-accept-fix' - $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-Session-ID' - $ref: '#/parameters/TPP-Redirect-URI' - $ref: '#/parameters/TPP-Redirect-Preferred' - $ref: '#/parameters/TPP-Signature-Certificate' - $ref: '#/parameters/Signature' - $ref: '#/parameters/PSU-ID' - $ref: '#/parameters/PSU-Corporate-ID' - $ref: '#/parameters/PSU-IP-Address' - $ref: '#/parameters/PSU-IP-Port' - $ref: '#/parameters/PSU-User-Agent' - $ref: '#/parameters/PSU-Accept' - $ref: '#/parameters/PSU-Accept-Charset' - $ref: '#/parameters/PSU-Accept-Encoding' - $ref: '#/parameters/PSU-Accept-Language' - $ref: '#/parameters/PSU-HTTP-Method' - $ref: '#/parameters/PSU-Device-ID' - $ref: '#/parameters/PSU-Geo-Location' responses: 204: description: No Content 401: description: Unauthorized schema: $ref: '#/definitions/Challenge' 404: description: RESOURCE_UNKNOWN schema: $ref: '#/definitions/Error' 500: description: Internal Server Error schema: $ref: '#/definitions/Error' examples: SYSTEM_ERROR: id: "5615873378" system: ERA-PSD2 status: 500 code: SYSTEM_ERROR parameters: x-accept-fix: name: x-accept-fix in: header required: true type: string description: Set this to "amount-as-string", will make amounts be serialized as strings with the correct number of decimal points. Temporarily required , default serialization will be switched to string when all clients sends this header. x-example: amount-as-string 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 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 TPP-Session-ID: name: TPP-Session-ID in: header type: string required: true description: TPP session identifier. x-example: b29f79d9-12ea-462b-ad8a-8ad38b8c57b7 TPP-Redirect-URI: name: TPP-Redirect-URI in: header type: string required: true description: URI of the TPP, where the transaction flow shalle be redirected to after a Redirect. x-example: http://httpbin.org/get TPP-Redirect-Preferred: name: TPP-Redirect-Preferred in: header type: string required: false description: Set to *false* to automatically trigger biometric authentication for mobile apps whenever available. Default is *true*. x-example: "false" 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="***************" PSU-ID: name: PSU-ID in: header type: string format: UUID required: true description: The PSU identifier. x-example: 49ae0cfe-6b72-4310-81f5-ad4eef897fe3 PSU-Corporate-ID: name: PSU-Corporate-ID in: header required: false type: string description: The PSU Corporate agreement identifier. x-example: aog5kNSbDNo2srEPAqsCGaR8LNCAfLVlKPzbwKZQJzI= PSU-Corporate-ID-Required: name: PSU-Corporate-ID in: header required: true type: string description: The PSU Corporate agreement identifier. x-example: aog5kNSbDNo2srEPAqsCGaR8LNCAfLVlKPzbwKZQJzI= PSU-IP-Address: name: PSU-IP-Address in: header description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. required: true type: string x-example: 153.110.241.229 PSU-IP-Port: name: PSU-IP-Port in: header description: The forwarded IP Port header field consists of the corresponding HTTP request IP Port field between PSU and TPP, if available. required: false type: string x-example: 443 PSU-User-Agent: name: PSU-User-Agent in: header description: The forwarded value for the User-Agent header field between the PSU and TPP, if available. required: false type: string x-example: Mozilla/5.0 (Windows NT 10.0; …) Gecko/20100101 Firefox/63.0 PSU-Accept: name: PSU-Accept in: header description: The forwarded value for the Accept header field between the PSU and TPP, if available. required: false type: string x-example: application/json PSU-Accept-Charset: name: PSU-Accept-Charset in: header description: The forwarded value for the Accept-Charset header field between the PSU and TPP, if available. required: false type: string x-example: utf-8 PSU-Accept-Encoding: name: PSU-Accept-Encoding in: header description: The forwarded value for the Accept-Encoding header field between the PSU and TPP, if available. required: false type: string x-example: gzip, deflate, br PSU-Accept-Language: name: PSU-Accept-Language in: header description: The forwarded value for the Accept-Language header field between the PSU and TPP, if available. required: false type: string x-example: en-US,en;q=0.7,nb;q=0.3 PSU-HTTP-Method: name: PSU-HTTP-Method in: header type: string enum: - GET - POST - PUT - PATCH - DELETE required: false description: The forwarded value for the HTTP method used between the PSU and TPP, if available. x-example: GET PSU-Device-ID: name: PSU-Device-ID in: header type: string format: UUID required: false description: The forwarded value of the device ID used by the PSU, if available. x-example: 35-67660-48540-8 PSU-Geo-Location: name: PSU-Geo-Location in: header description: The forwarded value of the Geo Location of the corresponding HTTP request between the PSU and TPP, if available. required: false type: string x-example: GEO:52.506931,13.144558 definitions: Link: type: object required: - href - verbs properties: href: type: string example: https://openbanking.lillesands-sparebank.no/ verbs: type: array items: type: string enum: - GET - PUT - POST - DELETE example: GET Error: type: object properties: id: type: string example: "5884127160" system: type: string example: ERA-PSD2 status: type: number example: 400 code: type: string example: ERROR_CODE message: type: string example: error message appears here Challenge: type: object properties: _links: type: object readOnly: true additionalProperties: $ref: '#/definitions/Link' example: _links: scaRedirect: href: https://openbanking.lillesands-sparebank.no/tap?route_secesb_id=1&flow=psd2&state=ca477daf-d824-4f0b-b405-6c8fc385dc0b&locale=no-NB, no; q=1.0 verbs: - GET PaymentAuthorization: type: object properties: scaStatus: type: string example: STARTED enum: - RECEIVED - PSU_IDENTIFIED - PSU_AUTHENTICATED - SCA_METHOD_SELECTED - STARTED - FINALISED - FAILED - EXEMPTED _links: type: object additionalProperties: $ref: '#/definitions/Link' example: self: href: https://openbanking.lillesands-sparebank.no/ verbs: - GET SigningBasket: type: object required: - transactionStatus properties: basketId: type: string description: Basket id example: enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjRx5n== transactionStatus: type: string description: Transaction status example: RCVD enum: - RCVD - ACTC - PATC - RJCT _links: type: object description: Links readOnly: true additionalProperties: $ref: '#/definitions/Link' example: self: href: https://openbanking.lillesands-sparebank.no/ verbs: - GET SigningBasketRequest: type: object required: - paymentIds properties: paymentIds: type: array description: List of paymentIds to be included in the signing basket. Can hold up to 10 payments per signing basket. items: type: string example: - enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjRxabc5n== - enc!!H6fD9HSabc7Y7peXJh1HqC34RFgGfF992bjRx5n== - enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjabcRx5n== SigningBasketItems: type: object required: - transactionStatus properties: payments: type: array description: Array of paymentId. items: type: string example: - enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjRxabc5n== - enc!!H6fD9HSabc7Y7peXJh1HqC34RFgGfF992bjRx5n== - enc!!H6fD9HS7Y7peXJh1HqC34RFgGfF992bjabcRx5n== transactionStatus: type: string description: Transaction status. example: ACTC enum: - RCVD - ACTC - PATC - RJCT _links: type: object description: Links readOnly: true additionalProperties: $ref: '#/definitions/Link' example: self: href: https://openbanking.lillesands-sparebank.no/ verbs: - GET x-ibm-configuration: enforced: true testable: true phase: realized x-ibm-endpoints: - endpointUrl: https://openbanking.lillesands-sparebank.no/api-sandbox type: - production - development ...