Payment and refund template

Copy the block below into a .feature file and replace the <placeholders>.

@payments @refunds
Feature: Refund a settled order

  Background:
    Given an authenticated customer "C-88"
    And order "A-1042" for 100.00 EUR is settled
    And the refund window for the order's plan is 30 days
    And the order was settled 3 days ago
    And the total refunded for order "A-1042" is 0.00 EUR

  @happy-path
  Scenario: A full refund is granted inside the window
    When the customer requests a refund for order "A-1042"
    Then the response status is 200
    And the refund amount is 100.00 EUR
    And the currency is EUR
    And the order status is "refunded"
    And the total refunded for order "A-1042" is 100.00 EUR
    And a refund receipt is emailed to the customer

  @idempotency
  Scenario: The same idempotency key returns the original refund
    Given a refund with idempotency key "idem-9f3a" was granted for order "A-1042"
    When a refund with idempotency key "idem-9f3a" is requested for order "A-1042"
    Then the response is the original refund response
    And the total refunded for order "A-1042" is 100.00 EUR
    And no second refund was sent to the payment provider

  @idempotency
  Scenario: The same idempotency key with a different order is refused
    Given a refund with idempotency key "idem-9f3a" was granted for order "A-1042"
    And order "A-1043" for 50.00 EUR is settled
    When a refund with idempotency key "idem-9f3a" is requested for order "A-1043"
    Then the response status is 409
    And the response body contains error code "IDEMPOTENCY_KEY_REUSED"

  @boundary
  Scenario Outline: The refund window boundary is inclusive

    Given the order was settled <age> days ago
    When the customer requests a refund for order "A-1042"
    Then the result is <outcome>

    Examples:
      | age | outcome                                          |
      | 0   | granted                                          |
      | 29  | granted                                          |
      | 30  | granted                                          |
      | 31  | refused with REFUND_WINDOW_CLOSED                |

  @partial-refund
  Scenario: A partial refund leaves the remainder refundable
    When a partial refund of 60.00 EUR is granted for order "A-1042"
    Then the order status is "partially_refunded"
    And the total refunded for order "A-1042" is 60.00 EUR
    And the remaining refundable amount is 40.00 EUR

  @partial-refund
  Scenario: A refund beyond the remaining amount is refused
    Given the total refunded for order "A-1042" is 60.00 EUR
    When a refund of 50.00 EUR is requested for order "A-1042"
    Then the response status is 422
    And the response body contains error code "REFUND_EXCEEDS_REMAINING"
    And the total refunded for order "A-1042" is 60.00 EUR

  @failure
  Scenario: A provider timeout leaves the order unchanged and retryable
    Given the payment provider times out while processing the refund
    When the customer requests a refund for order "A-1042"
    Then the response status is 503
    And the response body contains error code "REFUND_PROVIDER_UNAVAILABLE"
    And the order status is still "settled"
    And the total refunded for order "A-1042" is 0.00 EUR
    And the same idempotency key can be retried

  @failure
  Scenario: An order that was never settled cannot be refunded
    Given order "A-1042" has status "new"
    When the customer requests a refund for order "A-1042"
    Then the response status is 422
    And the response body contains error code "ORDER_NOT_SETTLED"
    And the total refunded for order "A-1042" is 0.00 EUR

Notes on each part

The idempotency scenarios are the highest-value part of this template. Double refunds are the most expensive defect in a payment system and the easiest to cause — a user double-clicks, a client retries after a timeout, a proxy retries. The three clauses in the first idempotency scenario are deliberately separate: "the response is the original refund response" could be satisfied by a cache, but "no second refund was sent to the payment provider" cannot.

The boundary row for exactly 30 days is present. This is the row that gets left out. Whether the window is inclusive is a business decision, and the specification has to make it — the implementation cannot infer it.

The boundary uses Scenario Outline with one row per side, plus the boundary itself. Three rows, not two.

The partial-refund pair is a state machine, and both halves are needed. "A partial refund leaves the remainder refundable" and "a refund beyond the remaining amount is refused" together define the invariant. Either one alone leaves the behaviour ambiguous.

The failure scenario asserts four separate facts. The error code, the order status, the refunded total, and the retry contract. Each is an independent decision, and each is a place where the implementation can diverge from intent. The retry clause is the one most often omitted, and it is the one that determines whether a user can retry at all.

The "never settled" case is a negative case at the bottom of the file. It is the most common real-world refund request, and it is the one most likely to be absent from a feature file.

Pair it with an OpenAPI document

The interface belongs in the contract: the Idempotency-Key header, the error responses with their codes, the refund request and result schemas.

parameters:
  - name: Idempotency-Key
    in: header
    required: true
    schema: { type: string, minLength: 8, maxLength: 64 }

Every error code asserted above — IDEMPOTENCY_KEY_REUSED, REFUND_WINDOW_CLOSED, REFUND_EXCEEDS_REMAINING, REFUND_PROVIDER_UNAVAILABLE, ORDER_NOT_SETTLED — must be declared as a response on the operation, or the cross-format consistency check will fail the build. That is the intended behaviour: it forces the contract and the behaviour to describe the same system.