REST APIs for Payments

Most modern payment APIs use REST, which is an architectural style built on standard HTTP methods and on resources that have clear identifiers. A payment is a resource, an account is a resource, and a payment status is a resource, each with its own URL. To create a payment, a client sends a POST request to the payments resource with the payment details in the body. To check the status, the client sends a GET request to that payment's URL. To cancel a payment that has not yet been released, the client might send a DELETE or a PATCH request. This consistency is the main strength of REST, because a developer who has used one REST API can understand another one quickly, and standard tools can test and monitor them. Idempotency is the most important payment specific concern in REST API design. Networks fail, and when a client does not receive a response, it does not know whether the payment was created or not, so it will retry. Without idempotency, the retry creates a second payment, and the customer is charged twice. The solution is an idempotency key, a unique value the client sends with the creation request, which the bank stores alongside the payment. If the same key arrives again, the bank returns the original result instead of creating a new payment. A BA writing API requirements must insist on idempotency for every operation that moves money, and must define how long keys are retained and what happens when a key is reused with different payment details. Versioning, pagination and error handling are the other essentials. APIs change over time, and versioning, usually in the URL or in a header, lets the bank improve the API without breaking existing clients. Pagination controls how large lists, such as transaction histories, are returned, so that a client asking for a year's transactions does not receive a single enormous response. Error responses must be consistent and useful, with a machine readable code, a human readable message, and enough detail for the developer to fix the problem, without leaking sensitive information. A BA should review the error catalogue for an API as carefully as the success cases, because developers spend most of their integration time handling errors, not the happy path. A worked example shows a REST call end to end. A corporate treasury system creates a payment of EUR 25,000 to a supplier. It sends POST /v1/payments with a JSON body containing the debtor account, the creditor account, the amount, and an Idempotency-Key header with a UUID. The bank returns 202 Accepted with a payment identifier PAY-20261105-8841 and a status ACCP. The treasury system then calls GET /v1/payments/PAY-20261105-8841/status every 30 seconds until the status changes to ACCC, which confirms the beneficiary was credited. The whole flow takes 8 seconds for a SEPA Instant payment, or up to one business day for a standard SEPA credit transfer. The treasury system stores the payment identifier and the idempotency key, so that if the network times out on the POST, it can safely retry with the same key and receive the same payment identifier back, instead of creating a duplicate payment. A failure scenario tests the error handling. The treasury system sends a payment with a creditor account number that is missing a digit. The bank returns 422 Unprocessable Content with a business error code AC01 and a field path creditorAccount.iban, and a message stating the account number is invalid. The treasury system logs the error, alerts the operator, and does not retry, because retrying the same invalid request will fail again. The operator corrects the account number and resubmits with a new idempotency key, because the instruction has changed. A client that retries a 422 error with the same body is wasting its rate limit; a client that retries a 500 error without an idempotency key is creating a duplicate. For a business analyst, the requirement is to define the error code for each failure, the HTTP status, and the client behaviour for each, and to test each with a real call. Last reviewed 7 November 2026. Further reading: Berlin Group NextGenPSD2 API framework; ISO 20022 ExternalPaymentTransactionStatus1Code. Take a payment initiation through a REST API. The client sends POST /v1/payments with a JSON body containing the debtor account, the creditor account, the amount of EUR 5,000, and an idempotency key. The bank returns 202 Accepted with a payment identifier and a status of ACCP. The client then sends GET /v1/payments/{id}/status and receives ACCC when the payment has settled. If the client sends the same POST again with the same key, the bank returns the original 202 response, not a new payment. If the amount in the body is invalid, the bank returns 400 Bad Request with a machine readable code and a human readable message. Each of these steps is a test case, and the BA should write all of them. Versioning failures are common and expensive. Suppose the bank releases v2 of its payments API with a new mandatory field, and a corporate client still on v1 sends a payment without it. The bank must either reject the payment with a clear error, which breaks the client's integration, or accept it and fill the field with a default, which may be wrong. The right approach is to version in the URL, to keep v1 working until its published sunset date, and to tell clients a year in advance. A BA should specify the versioning policy, the sunset notice period, and the behaviour when a client calls a retired version, because a retired version that still accepts payments is a security risk. The error catalogue is the most important part of an API specification, and the BA should review it line by line. Each error needs a status code, a business code, a message, and the action the client should take. A 400 means the request was wrong, a 401 means the token is invalid, a 409 means the payment already exists, a 422 means a business rule failed, and a 429 means the client is calling too fast. The BA should also define the support process: when a developer gets an error they do not understand, who do they call, and how quickly do they get an answer. An API with a good error catalogue and a good support process is adopted; an API without them is abandoned.