Gherkin for payment and refund workflows

Payments are the clearest possible target for spec-driven development. Money movement has invariants, the invariants are checkable, and the cost of missing one is not a bug report but a customer complaint.

This guide covers the four things a refund specification must get right, and the one it usually gets wrong.

What actually goes wrong

In our experience with refund workflows, the defects that reach production cluster into four groups:

  • Double refunds. The customer clicks twice, the client retries, or a network timeout causes the caller to retry. Without idempotency, the refund happens twice.
  • Boundary errors. The window is 30 days. The order was settled 30 days ago. Is that inside or outside? An implementation that uses > instead of >= — or compares dates rather than timestamps — answers differently from what the business intended.
  • Partial refunds that accumulate incorrectly. Two partial refunds of 60% each on a 100 EUR order. The remainder must be 40 EUR, not -20 EUR. State that or it will be wrong.
  • Partial failure. The provider times out halfway through. The order must not be left in a state where it looks refunded but the money did not move.

Each of these is a specification problem before it is a code problem. In every one of these cases the right behaviour was never written down, so it was implemented by guesswork.

State the invariants

Start with the invariants, because they are the clauses that must never be violated. In Gherkin terms, they are scenarios whose subject is a state rather than an action.

Feature: Refund a settled order

  Background:
    Given an authenticated customer
    And order "A-1042" for 100.00 EUR is settled
    And the customer has already been refunded 0.00 EUR

  Scenario: The refunded amount never exceeds the order total
    When a refund of 60.00 EUR is granted for order "A-1042"
    And a refund of 60.00 EUR is granted for order "A-1042"
    Then the total refunded for order "A-1042" is 120.00 EUR
    And the order status is "partially_refunded"

  Scenario: A further refund is refused once the order is fully refunded
    Given the total refunded for order "A-1042" is 100.00 EUR
    When a refund of 10.00 EUR is requested for order "A-1042"
    Then the request is rejected with code "REFUND_EXCEEDS_ORDER_TOTAL"
    And the total refunded for order "A-1042" is 100.00 EUR

The first scenario has a counter-intuitive expected value — 120 EUR refunded on a 100 EUR order — and that is the point. The invariant being expressed is "the platform does not prevent over-refunding; it records it". Whether that is the behaviour you want is a business decision, and the specification should make it visible rather than leave it to be discovered.

If over-refunding is not acceptable, the invariant becomes "the request is rejected with REFUND_EXCEEDS_ORDER_TOTAL and the total refunded remains 100.00 EUR". Either is fine. What is not fine is leaving it unspecified.

Idempotency is a clause, not an implementation detail

An idempotency key is a contract with the caller. It belongs in the specification and in the OpenAPI document.

paths:
  /orders/{orderId}/refunds:
    post:
      operationId: createRefund
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 8
            maxLength: 64
Scenario: The same idempotency key returns the original refund
    Given a refund with idempotency key "idem-9f3a-2b71" was granted for order "A-1042"
    When a refund with idempotency key "idem-9f3a-2b71" 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

The last clause is the one that matters. "The response is the original refund response" can be satisfied by a cache. "No second refund was sent to the payment provider" can only be satisfied by the real behaviour. Say both, and check the second.

Also specify the negative case, which is the one that actually gets hit in production:

Scenario: The same idempotency key with a different body is rejected
    Given a refund with idempotency key "idem-9f3a-2b71" was granted for order "A-1042"
    When a refund with idempotency key "idem-9f3a-2b71" is requested for order "A-1043"
    Then the request is rejected with code "IDEMPOTENCY_KEY_REUSED"

Reusing a key with a different payload is a client bug, and it is much better caught at the boundary than reconciled later.

Boundaries need both sides

A boundary is only specified when both sides are written down.

Scenario Outline: Refund window boundary

  Given the refund window is <window> days
  And order "A-<id>" settled <age> days ago
  When a refund is requested for order "A-<id>"
  Then the result is <outcome>

  Examples:
    | id   | window | age | outcome                                    |
    | 1042 | 30     | 29  | granted                                   |
    | 1043 | 30     | 30  | granted                                   |
    | 1044 | 30     | 31  | refused with REFUND_WINDOW_CLOSED          |
    | 1045 | 30     | 0   | granted                                   |

Note that row 1043 — exactly on the boundary — is present. A boundary specification with only the two sides and nothing between them is the classic gap: nobody writes the row where the answer is contested.

Note also that the window is stated in days and the age in days. That means the specification implicitly commits to comparing calendar days rather than elapsed hours. If the business rule is actually "30 × 24 hours from the settlement timestamp", say that instead — the units are part of the rule.

Failure paths need their own scenarios

The most common omission in payment specifications is the provider failing.

Scenario: A provider timeout leaves the order unsettled and retryable
    Given order "A-1042" is settled
    And the payment provider times out while processing the refund
    When a refund is requested for order "A-1042"
    Then the request fails with 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 request can be retried with the same idempotency key

This scenario states four things: the customer-visible error, the order’s state, the refunded total, and the retry contract. Each of those is a separate decision, and each is a place where an implementation can diverge from intent.

What to leave implicit

Payment specifications get long, and long specifications do not get reviewed. Leave out:

  • The provider’s own API semantics. The provider is somebody else’s contract; reference it, do not restate it.
  • Internal service structure. "The refund service calls the ledger service" is implementation. "The refunded total is recorded before the provider is called" is a behaviour with an observable consequence — keep that.
  • Anything the OpenAPI document already states structurally. Field types, required-ness, and response shapes belong in the schema, not in scenarios.

The review question for this domain

For each clause, ask:

If this clause were false, would money be wrong?

If yes, it needs to be right, and it needs to be verified by a scenario that could actually fail. A clause about money that is covered by an assertion of status == 200 is worse than no clause, because it produces a green tick on an unverified rule.

Next