HG-58: Allow to refund payments (#105)

spec/definitions/Invoice.yaml

@@ -1,6 +1,5 @@
 type: object
 allOf:
-  - $ref: '#/definitions/InvoiceStatus'
   - type: object
     required:
       - id
@@ -55,3 +54,4 @@ allOf:
       metadata:
         description: Связанные с инвойсом метаданные
         type: object
+  - $ref: '#/definitions/InvoiceStatus'

spec/definitions/InvoiceChange.yaml

@@ -11,3 +11,5 @@ properties:
       - PaymentStarted
       - PaymentStatusChanged
       - PaymentInteractionRequested
+      - RefundStarted
+      - RefundStatusChanged

spec/definitions/InvoiceStatus.yaml

@@ -9,7 +9,6 @@ properties:
       - unpaid
       - cancelled
       - paid
-      - refunded
       - fulfilled
   reason:
     description: Причина отмены или погашения инвойса

spec/definitions/InvoicesTopic.yaml

@@ -26,4 +26,5 @@ allOf:
             - PaymentProcessed
             - PaymentCaptured
             - PaymentCancelled
+            - PaymentRefunded
             - PaymentFailed

spec/definitions/Payment.yaml

@@ -1,6 +1,5 @@
 type: object
 allOf:
-  - $ref: '#/definitions/PaymentStatus'
   - type: object
     required:
       - id
@@ -65,3 +64,4 @@ allOf:
         description: Уникальный отпечаток user agent'а плательщика
         type: string
         maxLength: 1000
+  - $ref: '#/definitions/PaymentStatus'

spec/definitions/PaymentStatus.yaml

@@ -10,6 +10,7 @@ properties:
       - processed
       - captured
       - cancelled
+      - refunded
       - failed
   error:
     $ref: '#/definitions/LogicError'

spec/definitions/Refund.yaml

@@ -0,0 +1,18 @@
+type: object
+allOf:
+  - type: object
+    required:
+      - id
+      - createdAt
+    properties:
+      id:
+        description: Идентификатор возврата
+        type: string
+      createdAt:
+        description: Дата и время осуществления
+        type: string
+        format: date-time
+      reason:
+        description: Причина осуществления возврата
+        type: string
+  - $ref: '#/definitions/RefundStatus'

spec/definitions/RefundStarted.yaml

@@ -0,0 +1,12 @@
+type: object
+allOf:
+  - $ref: '#/definitions/InvoiceChange'
+  - type: object
+    required:
+      - paymentID
+      - refund
+    properties:
+      paymentID:
+        type: string
+      refund:
+        $ref: '#/definitions/Refund'

spec/definitions/RefundStatus.yaml

@@ -0,0 +1,26 @@
+type: object
+required:
+  - status
+properties:
+  status:
+    description: Статус возврата
+    type: string
+    enum:
+      - pending
+      - succeeded
+      - failed
+  error:
+    description: |
+      Данные ошибки, возникшей в процессе проведения возврата, в случае если
+      возврат был неуспешен
+    type: object
+    required:
+      - code
+      - message
+    properties:
+      code:
+        description: Код ошибки, пригодный для обработки автоматическими системами
+        type: string
+      message:
+        description: Описание ошибки, пригодное для восприятия человеком
+        type: string

spec/definitions/RefundStatusChanged.yaml

@@ -0,0 +1,13 @@
+type: object
+allOf:
+  - $ref: '#/definitions/InvoiceChange'
+  - type: object
+    required:
+      - paymentID
+      - refundID
+    properties:
+      paymentID:
+        type: string
+      refundID:
+        type: string
+  - $ref: '#/definitions/RefundStatus'

spec/paths/analytics@shops@{shopID}@invoices.yaml

@@ -19,7 +19,6 @@ get:
         - unpaid
         - cancelled
         - paid
-        - refunded
         - fulfilled
     - name: paymentStatus
       in: query
@@ -31,6 +30,7 @@ get:
         - processed
         - captured
         - cancelled
+        - refunded
         - failed
     - name: paymentFlow
       in: query

spec/paths/analytics@shops@{shopID}@payments.yaml

@@ -20,6 +20,7 @@ get:
         - processed
         - captured
         - cancelled
+        - refunded
         - failed
     - name: paymentFlow
       in: query

spec/paths/processing@invoices@{invoiceID}@payments@{paymentID}@refunds.yaml

@@ -0,0 +1,44 @@
+get:
+  description: Получить все возвраты указанного платежа.
+  tags:
+    - Payments
+  operationId: getRefunds
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceID'
+    - $ref: '#/parameters/paymentID'
+  responses:
+    '200':
+      description: Данные возвратов по платежу
+      schema:
+        type: array
+        items:
+          $ref: '#/definitions/Refund'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'
+post:
+  description: Создать возврат указанного платежа
+  tags:
+    - Payments
+  operationId: createRefund
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceID'
+    - $ref: '#/parameters/paymentID'
+    - name: reason
+      in: body
+      description: Причина совершения возврата
+      required: false
+      schema:
+        $ref: '#/definitions/Reason'
+  responses:
+    '201':
+      description: Возврат создан
+      schema:
+        $ref: '#/definitions/Refund'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'

spec/paths/processing@invoices@{invoiceID}@payments@{paymentID}@refunds@{refundID}.yaml

@@ -0,0 +1,19 @@
+get:
+  description: Получить данные определённого возврата указанного платежа.
+  tags:
+    - Payments
+  operationId: getRefundByID
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceID'
+    - $ref: '#/parameters/paymentID'
+    - $ref: '#/parameters/refundID'
+  responses:
+    '200':
+      description: Данные возврата
+      schema:
+        $ref: '#/definitions/Refund'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'

spec/swagger.yaml

@@ -145,6 +145,13 @@ parameters:
     required: true
     type: string
     maxLength: 40
+  refundID:
+    name: refundID
+    in: path
+    description: Идентификатор возврата в рамках платежа
+    required: true
+    type: string
+    maxLength: 40
   contractID:
     name: contractID
     in: path