From 8fce926a05e4b2730eb214e3765ffad531f29386 Mon Sep 17 00:00:00 2001 From: Aleksey Kashapov Date: Tue, 9 Jun 2026 14:15:33 +0300 Subject: [PATCH 1/5] XYZ-182: Adds `createInvoiceCheckoutUrl` operation on invoice --- ...ng@invoices@{invoiceID}@checkout-urls.yaml | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml diff --git a/spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml b/spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml new file mode 100644 index 0000000000..f9127b28fa --- /dev/null +++ b/spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml @@ -0,0 +1,43 @@ +# FIXME naming sucks +post: + operationId: createInvoiceCheckoutUrl + description: Create a new checkout url for invoice payment with set of optional query parameters. + tags: + - Invoices + parameters: + - $ref: "#/parameters/requestID" + - $ref: "#/parameters/deadline" + - $ref: "#/parameters/invoiceID" + # TODO Move into parameters subset in main spec document + - name: checkoutParameters + in: body + description: Checkout forms's prefill parameters + required: true + schema: + type: object + required: [] + additionalProperties: true + properties: {} + # TODO Type provide example + example: {} + responses: + "201": + description: Invoice's checkout URL is created. + schema: + # TODO Move to dedicated schema reference yaml document + type: object + required: + - checkoutUrl + properties: + checkoutUrl: + description: > + Invoice's checkout URL + type: string + # TODO Provide example + example: "string" + "404": + $ref: "#/responses/NotFound" + "401": + $ref: "#/responses/Unauthorized" + "400": + $ref: "#/responses/DefaultLogicError" From 2b2002e18742071e59eb516648ba0b107a78e94e Mon Sep 17 00:00:00 2001 From: Aleksey Kashapov Date: Wed, 10 Jun 2026 11:54:07 +0300 Subject: [PATCH 2/5] Renames operation, path and schemas; adds examples --- ...ng@invoices@{invoiceID}@checkout-urls.yaml | 43 ------------------- .../processing@invoices@{invoiceID}@urls.yaml | 40 +++++++++++++++++ 2 files changed, 40 insertions(+), 43 deletions(-) delete mode 100644 spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml create mode 100644 spec/paths/processing@invoices@{invoiceID}@urls.yaml diff --git a/spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml b/spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml deleted file mode 100644 index f9127b28fa..0000000000 --- a/spec/paths/processing@invoices@{invoiceID}@checkout-urls.yaml +++ /dev/null @@ -1,43 +0,0 @@ -# FIXME naming sucks -post: - operationId: createInvoiceCheckoutUrl - description: Create a new checkout url for invoice payment with set of optional query parameters. - tags: - - Invoices - parameters: - - $ref: "#/parameters/requestID" - - $ref: "#/parameters/deadline" - - $ref: "#/parameters/invoiceID" - # TODO Move into parameters subset in main spec document - - name: checkoutParameters - in: body - description: Checkout forms's prefill parameters - required: true - schema: - type: object - required: [] - additionalProperties: true - properties: {} - # TODO Type provide example - example: {} - responses: - "201": - description: Invoice's checkout URL is created. - schema: - # TODO Move to dedicated schema reference yaml document - type: object - required: - - checkoutUrl - properties: - checkoutUrl: - description: > - Invoice's checkout URL - type: string - # TODO Provide example - example: "string" - "404": - $ref: "#/responses/NotFound" - "401": - $ref: "#/responses/Unauthorized" - "400": - $ref: "#/responses/DefaultLogicError" diff --git a/spec/paths/processing@invoices@{invoiceID}@urls.yaml b/spec/paths/processing@invoices@{invoiceID}@urls.yaml new file mode 100644 index 0000000000..5804719a51 --- /dev/null +++ b/spec/paths/processing@invoices@{invoiceID}@urls.yaml @@ -0,0 +1,40 @@ +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: + type: object + required: [] + additionalProperties: true + properties: {} + example: + locale: "en-US" + theme: "tomorrow-night" + responses: + "201": + description: Invoice's payment URL is constructed. + schema: + type: object + required: + - url + properties: + url: + description: > + Invoice's payment URL + type: string + example: "https://shop-specific-example.com/path/to/checkout?locale=en-US&theme=tomorrow-night" + "404": + $ref: "#/responses/NotFound" + "401": + $ref: "#/responses/Unauthorized" + "400": + $ref: "#/responses/DefaultLogicError" From 931b24aec9f6936e66ce4875a1eb8d161753cd0c Mon Sep 17 00:00:00 2001 From: Aleksey Kashapov Date: Wed, 10 Jun 2026 12:47:49 +0300 Subject: [PATCH 3/5] Adds invoice url to create operations --- spec/definitions/InvoiceAndToken.yaml | 3 +++ spec/definitions/InvoiceParams.yaml | 2 ++ .../definitions/InvoiceParamsWithTemplate.yaml | 2 ++ spec/definitions/InvoiceUrl.yaml | 9 +++++++++ spec/definitions/InvoiceUrlParams.yaml | 7 +++++++ .../processing@invoices@{invoiceID}@urls.yaml | 18 ++---------------- 6 files changed, 25 insertions(+), 16 deletions(-) create mode 100644 spec/definitions/InvoiceUrl.yaml create mode 100644 spec/definitions/InvoiceUrlParams.yaml diff --git a/spec/definitions/InvoiceAndToken.yaml b/spec/definitions/InvoiceAndToken.yaml index 19125003f8..7ea21d17e7 100644 --- a/spec/definitions/InvoiceAndToken.yaml +++ b/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" diff --git a/spec/definitions/InvoiceParams.yaml b/spec/definitions/InvoiceParams.yaml index 3e0703104f..b76dbe0407 100644 --- a/spec/definitions/InvoiceParams.yaml +++ b/spec/definitions/InvoiceParams.yaml @@ -57,3 +57,5 @@ properties: type: object clientInfo: $ref: "#/definitions/InvoiceClientInfo" + urlParams: + $ref: "#/definitions/InvoiceUrlParams" diff --git a/spec/definitions/InvoiceParamsWithTemplate.yaml b/spec/definitions/InvoiceParamsWithTemplate.yaml index 0f69bc92e7..5e6e4b406e 100644 --- a/spec/definitions/InvoiceParamsWithTemplate.yaml +++ b/spec/definitions/InvoiceParamsWithTemplate.yaml @@ -16,3 +16,5 @@ properties: metadata: description: "Invoice metadata" type: object + urlParams: + $ref: "#/definitions/InvoiceUrlParams" diff --git a/spec/definitions/InvoiceUrl.yaml b/spec/definitions/InvoiceUrl.yaml new file mode 100644 index 0000000000..550988be67 --- /dev/null +++ b/spec/definitions/InvoiceUrl.yaml @@ -0,0 +1,9 @@ +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" diff --git a/spec/definitions/InvoiceUrlParams.yaml b/spec/definitions/InvoiceUrlParams.yaml new file mode 100644 index 0000000000..474a8a6118 --- /dev/null +++ b/spec/definitions/InvoiceUrlParams.yaml @@ -0,0 +1,7 @@ +type: object +required: [] +additionalProperties: true +properties: {} +example: + locale: "en-US" + theme: "tomorrow-night" diff --git a/spec/paths/processing@invoices@{invoiceID}@urls.yaml b/spec/paths/processing@invoices@{invoiceID}@urls.yaml index 5804719a51..95c26b0e6b 100644 --- a/spec/paths/processing@invoices@{invoiceID}@urls.yaml +++ b/spec/paths/processing@invoices@{invoiceID}@urls.yaml @@ -12,26 +12,12 @@ post: description: Payment forms's prefill parameters required: true schema: - type: object - required: [] - additionalProperties: true - properties: {} - example: - locale: "en-US" - theme: "tomorrow-night" + $ref: "#/definitions/InvoiceUrlParams" responses: "201": description: Invoice's payment URL is constructed. schema: - type: object - required: - - url - properties: - url: - description: > - Invoice's payment URL - type: string - example: "https://shop-specific-example.com/path/to/checkout?locale=en-US&theme=tomorrow-night" + $ref: "#/definitions/InvoiceUrl" "404": $ref: "#/responses/NotFound" "401": From 75526341f8dfe43a8624ebe35e6bbbf5fcdab4ae Mon Sep 17 00:00:00 2001 From: Aleksey Kashapov Date: Wed, 10 Jun 2026 12:53:47 +0300 Subject: [PATCH 4/5] Fixes yaml string' length --- spec/definitions/InvoiceUrl.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/definitions/InvoiceUrl.yaml b/spec/definitions/InvoiceUrl.yaml index 550988be67..a08fbeb35c 100644 --- a/spec/definitions/InvoiceUrl.yaml +++ b/spec/definitions/InvoiceUrl.yaml @@ -6,4 +6,5 @@ properties: 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" + example: "https://shop-specific-example.com/path/to/checkout?invoiceID=ABCDEF12345&\ + invoiceAccessToken=0123456789abcdef0123456789abcdef&locale=en-US&theme=tomorrow-night" From 469149e300aebbc5a5f3fc827de1e6ca73b20776 Mon Sep 17 00:00:00 2001 From: Aleksey Kashapov Date: Wed, 10 Jun 2026 16:37:01 +0300 Subject: [PATCH 5/5] Introduces `invalidUrlParams` error code to invoice url related ops --- ...templates@{invoiceTemplateID}@invoices.yaml | 1 + spec/paths/processing@invoices.yaml | 1 + .../processing@invoices@{invoiceID}@urls.yaml | 18 +++++++++++++++++- spec/swagger.yaml | 2 ++ 4 files changed, 21 insertions(+), 1 deletion(-) diff --git a/spec/paths/processing@invoice-templates@{invoiceTemplateID}@invoices.yaml b/spec/paths/processing@invoice-templates@{invoiceTemplateID}@invoices.yaml index ee04ab1cf1..056d04b15c 100644 --- a/spec/paths/processing@invoice-templates@{invoiceTemplateID}@invoices.yaml +++ b/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 diff --git a/spec/paths/processing@invoices.yaml b/spec/paths/processing@invoices.yaml index f0912fed31..d2acacc940 100644 --- a/spec/paths/processing@invoices.yaml +++ b/spec/paths/processing@invoices.yaml @@ -66,6 +66,7 @@ post: - invalidInvoiceCost - invoiceTermsViolated - ambiguousPartyID + - invalidUrlParams message: description: Human-readable description of the error type: string diff --git a/spec/paths/processing@invoices@{invoiceID}@urls.yaml b/spec/paths/processing@invoices@{invoiceID}@urls.yaml index 95c26b0e6b..352133cbb4 100644 --- a/spec/paths/processing@invoices@{invoiceID}@urls.yaml +++ b/spec/paths/processing@invoices@{invoiceID}@urls.yaml @@ -23,4 +23,20 @@ post: "401": $ref: "#/responses/Unauthorized" "400": - $ref: "#/responses/DefaultLogicError" + 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 diff --git a/spec/swagger.yaml b/spec/swagger.yaml index f7dd1bed04..d011aab33a 100644 --- a/spec/swagger.yaml +++ b/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