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.
Related
- Gherkin for payment and refund workflows — the reasoning behind each part of this template
- Gherkin feature files — the conventions
- Assertion strength — whether these assertions can actually fail