feat(sandbox): add the card correction simulate endpoint

openapi/components/schemas/cards/SandboxCardCorrectionRequest.yaml

@@ -0,0 +1,34 @@
+type: object
+required:
+  - cardTransactionId
+  - amount
+  - direction
+description: >-
+  Sandbox-only request body for `POST /sandbox/cards/{id}/simulate/correction`.
+  Posts a network correction against an existing settled `CardTransaction` — an
+  adjustment the card network makes to money it has already moved.
+properties:
+  cardTransactionId:
+    type: string
+    description: >-
+      The id of the settled `CardTransaction` to correct. Must have at least one
+      settled clearing.
+    example: Transaction:019542f5-b3e7-1d02-0000-000000000100
+  amount:
+    type: integer
+    format: int64
+    description: >-
+      Correction amount in the smallest unit of the transaction's currency
+      (cents for USD). Must not exceed the transaction's settled amount.
+    exclusiveMinimum: 0
+    example: 250
+  direction:
+    type: string
+    enum:
+      - DEBIT
+      - CREDIT
+    description: >-
+      Which way the correction moves money. `DEBIT` takes further funds from the
+      cardholder and is permanent — nothing releases it. `CREDIT` returns funds
+      to the cardholder, the way a return does.
+    example: DEBIT

openapi/paths/sandbox/cards/sandbox_cards_{id}_simulate_correction.yaml

@@ -0,0 +1,97 @@
+post:
+  summary: Simulate a card correction
+  description: >
+    Simulate a network correction against an existing settled card transaction
+    in the sandbox environment — an adjustment the card network makes to money
+    it has already moved.
+
+
+    A `DEBIT` correction takes further funds from the cardholder and is
+    permanent: nothing releases it and no capture settles against it. A `CREDIT`
+    correction returns funds, the way a return does. The resulting card
+    operation is delivered asynchronously via the issuer's events webhook.
+
+
+    Production returns `404` on this path.
+  operationId: sandboxSimulateCardCorrection
+  tags:
+    - Sandbox
+  security:
+    - BasicAuth: []
+  parameters:
+    - name: id
+      in: path
+      required: true
+      description: The id of the card the correction applies to.
+      schema:
+        type: string
+      example: Card:019542f5-b3e7-1d02-0000-000000000010
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: ../../../components/schemas/cards/SandboxCardCorrectionRequest.yaml
+        examples:
+          correctionDebit:
+            summary: The network takes a further $2.50 on a settled purchase
+            value:
+              cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100
+              amount: 250
+              direction: DEBIT
+          correctionCredit:
+            summary: The network returns $2.50 it took in error
+            value:
+              cardTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100
+              amount: 250
+              direction: CREDIT
+  responses:
+    '202':
+      description: >-
+        Simulation accepted. The resulting card operation is delivered
+        asynchronously via the issuer's events webhook. Returns the issuer
+        transaction token that correlates the simulated event.
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/cards/SandboxCardSimulationResponse.yaml
+    '400':
+      description: Bad request - Invalid parameters
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/errors/Error400.yaml
+    '401':
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/errors/Error401.yaml
+    '403':
+      description: Forbidden - request was made with a production platform token
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/errors/Error403.yaml
+    '404':
+      description: Card or card transaction not found
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/errors/Error404.yaml
+    '409':
+      description: >-
+        Conflict. The simulation targets a card in a program where the card
+        issuer makes authorization decisions. These sandbox simulators support
+        only card programs where Grid makes authorization decisions. This is a
+        property of the card's program, so retrying will not help.
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/errors/Error409.yaml
+    '500':
+      description: Internal service error
+      content:
+        application/json:
+          schema:
+            $ref: ../../../components/schemas/errors/Error500.yaml