REST resource modelling for payments: resources, state and transitions

REST models a payment API as resources, and the quality of the resource model determines how easy the API is to use and how hard it is to misuse. A resource is a thing the client can create, read, update or delete through a URL. For payments, the core resources are the payment itself, the payment status, the account, the balance, and the transaction history. Each resource has a URL, such as /v1/payments for the collection and /v1/payments/PAY-20261105-8841 for one payment, and each supports the HTTP methods that make sense for it. A payment can be created with POST, read with GET, and cancelled with POST to a sub-resource such as /v1/payments/PAY-20261105-8841/cancel. A payment cannot be updated with PUT, because a payment instruction that has been accepted cannot be changed; it can only be cancelled and recreated. Source: REST API design guidance; Berlin Group NextGenPSD2 API framework. For a business analyst, the requirement is to define this behaviour in the API specification, because the client builds against the specification and nothing else. The payment resource carries its state, and the state determines what the client can do with it. A payment in state ACCP, accepted for processing, can be cancelled. A payment in state ACSC, settlement completed, cannot be cancelled, because the money has already left the debtor account; it can only be recalled, which is a different operation with a different outcome. The API must enforce these rules: a cancel request for a settled payment returns a 409 Conflict with a code such as ALREADY_SETTLED, not a 200 that pretends the cancellation worked. The API must also return the current state in every response, so the client always knows where the payment stands. A client that does not know the state cannot decide what to do next, and a client that guesses will make mistakes. Sub-resources model the parts of a payment that have their own lifecycle. The status history is a sub-resource: GET /v1/payments/PAY-20261105-8841/status returns the list of status changes with timestamps, so the client can see when the payment was accepted, when settlement started, and when the beneficiary was credited. The cancellation is a sub-resource: POST /v1/payments/PAY-20261105-8841/cancel creates a cancellation request, which itself has a status. The events are a sub-resource: GET /v1/payments/PAY-20261105-8841/events returns the webhooks that were sent for this payment. Each sub-resource has its own URL and its own representation, and the main payment resource links to them, so a client that reads a payment can discover what else it can do with it. This is the principle of hypermedia: the API tells the client what is possible, rather than the client having to guess. Field naming and data types must be consistent across all resources. An amount is always an object with a currency and a value, such as {'currency': 'EUR', 'amount': '25000.00'}, never a bare number, because a bare number without a currency is ambiguous and a floating point number cannot represent money exactly. A date is always an ISO 8601 string, such as 2026-11-05, never a Unix timestamp, because a timestamp without a timezone is ambiguous. An identifier is always a string, never a number, because a leading zero in an identifier is significant. A status is always a code from the defined code set, such as ACCP or RJCT, never a free text word, because a client cannot program against free text. For a business analyst, the requirement is to define the resource model, the state machine for each resource, the allowed transitions, and the field types, and to write them into the API specification as a contract that both the bank and the client can test against. Nested resources model the relationships between payments and the things they contain. A payment has a debtor, a creditor, charges, and a remittance information block, and each of these is a nested object inside the payment resource, not a separate top level resource. The debtor is an object with a name, an account, and an agent; the charges are an array of charge objects, each with a type and an amount; the remittance information is an object with a structured or unstructured reference. Nesting keeps the payment resource self contained: a client that reads a payment gets everything it needs in one response, without having to make additional calls to fetch the debtor, the charges or the remittance. A resource that is split across many endpoints forces the client to make many calls, and each call is a chance for a timeout or an inconsistency. The API documentation must state this rule plainly, because a client that has to guess will guess wrong. Links between resources let a client discover what it can do next. A payment resource includes links to its status history, its cancellation, and its events, each with a URL and a relation such as status, cancel or events. A client that follows the links does not need to construct URLs itself, which means the bank can change its URL structure without breaking clients, as long as the links are updated. This is the hypermedia principle, and it is what makes a REST API evolvable. A client that hard codes URLs, such as /v1/payments/PAY-20261105-8841/status, will break if the bank changes the URL; a client that follows the link from the payment resource will not. For a business analyst, the requirement is to define the links each resource carries, the relations, and the behaviour when a link is followed for a resource in a state that does not allow that action. Further reading: REST API design guidance; Berlin Group NextGenPSD2 API framework. Last reviewed 7 November 2026.