XYZ-182: Introduces dedicated operation for invoice URL and adds it to create operations responses

spec/definitions/InvoiceAndToken.yaml

@@ -2,8 +2,11 @@ type: object
 required:
   - invoice
   - invoiceAccessToken
+  - invoiceUrl
 properties:
   invoice:
     $ref: "#/definitions/Invoice"
   invoiceAccessToken:
     $ref: "#/definitions/AccessToken"
+  invoiceUrl:
+    $ref: "#/definitions/InvoiceUrl"

spec/definitions/InvoiceParams.yaml

@@ -57,3 +57,5 @@ properties:
     type: object
   clientInfo:
     $ref: "#/definitions/InvoiceClientInfo"
+  urlParams:
+    $ref: "#/definitions/InvoiceUrlParams"

spec/definitions/InvoiceParamsWithTemplate.yaml

@@ -16,3 +16,5 @@ properties:
   metadata:
     description: "Invoice metadata"
     type: object
+  urlParams:
+    $ref: "#/definitions/InvoiceUrlParams"

spec/definitions/InvoiceUrl.yaml

@@ -0,0 +1,10 @@
+type: object
+required:
+  - url
+properties:
+  url:
+    description: >
+      Invoice's payment URL
+    type: string
+    example: "https://shop-specific-example.com/path/to/checkout?invoiceID=ABCDEF12345&\
+      invoiceAccessToken=0123456789abcdef0123456789abcdef&locale=en-US&theme=tomorrow-night"

spec/definitions/InvoiceUrlParams.yaml

@@ -0,0 +1,7 @@
+type: object
+required: []
+additionalProperties: true
+properties: {}
+example:
+  locale: "en-US"
+  theme: "tomorrow-night"

spec/paths/processing@invoice-templates@{invoiceTemplateID}@invoices.yaml

@@ -40,6 +40,7 @@ post:
               - invalidRequest
               - invalidDeadline
               - invoiceTermsViolated
+              - invalidUrlParams
           message:
             description: Human-readable description of the error
             type: string

spec/paths/processing@invoices.yaml

@@ -66,6 +66,7 @@ post:
               - invalidInvoiceCost
               - invoiceTermsViolated
               - ambiguousPartyID
+              - invalidUrlParams
           message:
             description: Human-readable description of the error
             type: string

spec/paths/processing@invoices@{invoiceID}@urls.yaml

@@ -0,0 +1,42 @@
+post:
+  operationId: createInvoiceUrl
+  description: Construct an URL for invoice payment with set of optional query parameters.
+  tags:
+    - Invoices
+  parameters:
+    - $ref: "#/parameters/requestID"
+    - $ref: "#/parameters/deadline"
+    - $ref: "#/parameters/invoiceID"
+    - name: params
+      in: body
+      description: Payment forms's prefill parameters
+      required: true
+      schema:
+        $ref: "#/definitions/InvoiceUrlParams"
+  responses:
+    "201":
+      description: Invoice's payment URL is constructed.
+      schema:
+        $ref: "#/definitions/InvoiceUrl"
+    "404":
+      $ref: "#/responses/NotFound"
+    "401":
+      $ref: "#/responses/Unauthorized"
+    "400":
+      description: Invalid data for url construction
+      schema:
+        type: object
+        required:
+          - code
+          - message
+        properties:
+          code:
+            description: >
+              [Error code](#tag/Error-Codes)
+            type: string
+            enum:
+              - invalidUrlParams
+          message:
+            description: Human-readable description of the error
+            type: string
+            example: Bad url params

spec/swagger.yaml

@@ -647,6 +647,8 @@ tags:
 
       | **refundCartConflict**           | It is impossible to define the refund content as the refund distribution and cart are sent at the same time.                               |
 
+      | **invalidUrlParams**             | Failed to construct payment URL and encode provided parameters due to incorrect encoding, incomplete sequences, or invalid characters.     |
+
       ## General errors
 
       The errors that occur during the transaction attempts with the objects