REST API

A REST API is an application programming interface that follows the conventions of the web. One program sends a request over HTTP to an address that represents a resource, such as a customer or a payment, and receives a structured reply, almost always in the JSON data format. REST stands for representational state transfer, an architectural style described by the computer scientist Roy Fielding in his doctoral dissertation in 2000.

In payments, REST has become the default way for merchants, platforms and fintech companies to connect to processors, banking-as-a-service providers and open banking services. It has largely replaced older integration methods for new work, although card networks and banks still exchange fixed-format messages and files between themselves. A merchant typically meets REST at the edge of the system and never sees the formats behind it.

A REST API models a business as a set of resources, each with its own address. A payments provider might expose resources called payments, refunds, customers and payouts. The action to take is expressed by the HTTP method.

• GET reads a resource or a list of resources without changing anything.
• POST creates a new resource, such as a payment.
• PUT and PATCH replace or partly update an existing resource.
• DELETE removes or cancels a resource.

Requests are stateless. Each one carries everything the server needs to process it, including credentials, and the server does not rely on memory of earlier calls. The reply includes a standard status code. Codes in the 200 range mean success, codes in the 400 range mean the request was wrong or not permitted, and codes in the 500 range mean the server failed.

To charge a customer, a merchant's server sends a POST request to the provider's payments address. The body of the request, called the payload, states the amount, currency, a token standing for the customer's card and the merchant's own order reference. The provider validates the request, sends an authorization through the card network and returns a payment object containing a unique identifier and a status such as succeeded, requires action or failed.

The merchant stores the identifier and uses it afterwards. A GET request to the same address with the identifier appended returns the current state of the payment, and a POST to a refunds address that quotes the identifier returns the money. Every later event in the payment's life is linked to that one resource.

All traffic is encrypted in transit with Transport Layer Security. The caller proves its identity on every request, most simply with a secret API key sent in a header. Where an application acts on behalf of another party, such as a platform accessing a seller's account or an app reading a bank customer's data, access is delegated through OAuth tokens that are limited in scope and time. Banks and open banking schemes often add mutual certificate authentication and signed messages.

Providers keep raw card numbers out of merchants' REST calls where they can. Card details are collected by the provider's own hosted fields and exchanged for a token, so the merchant's server handles only the token and stays outside most card data security requirements.

Networks fail, and a merchant may not know whether a request that timed out was processed. Payment APIs deal with this through an idempotency key, a unique value the client attaches to a request. If the same key is sent again, the server returns the original result instead of creating a second payment.

Many payment outcomes are not known immediately. A bank transfer may settle hours later, and a card payment may be disputed weeks later. REST is a request and response model, so the server cannot speak first. Providers therefore send a webhook notification, an HTTP request in the opposite direction, to tell the client that something has changed, with status polling as a fallback. Providers also apply rate limiting, page long lists and label each version of the interface so that changes do not break existing integrations.

Providers publish reference documentation, often as a machine-readable OpenAPI description, along with software libraries for common programming languages. Developers build against a sandbox that accepts test credentials and simulates approvals, declines and errors, then switch to live keys in the production environment.

REST is one of several ways that financial systems exchange data. Card authorization between acquirers, networks and issuers runs on ISO 8583 messages over dedicated connections. Corporate customers have traditionally sent payment files to banks through a host-to-host link, and many still do for large batches. Older web services used the SOAP protocol with XML messages.

REST suits single, immediate requests and is easy for developers to adopt, which is why a bank API or an open banking API is normally built this way. It is less suited to very large batches or to continuous streams of events, for which files, message queues and streaming interfaces remain in use alongside it.