Home / Wiki / P / Payment API

Payment API

Financial InfrastructureUpdated 16 Nov 2026

A payment API is an application programming interface that lets software start, track and manage payments. Through it a website, app or business system can charge a customer, refund a purchase, send money to a supplier or check whether a payment has arrived, without staff entering each payment by hand. Payment APIs are offered by payment gateways, processors, banks, payout providers and card issuers.

The term covers several kinds of interface. A payment gateway API accepts card and wallet payments from customers; a payout API sends money out to many recipients; a payment initiation API starts bank transfers from a customer's account under open banking rules; and bank APIs let corporate clients send and track transfers directly. Most modern payment APIs follow the REST style and exchange data in JSON over the web.

01

Core functions

Although each provider designs its own interface, most payment APIs offer a similar set of operations:

  • Create a payment. The caller submits an amount, a currency, a payment method or token and a reference, and receives an identifier and a status, such as pending, succeeded or failed.
  • Authorize and capture. Card payments can be authorized first and captured later, for example when goods ship.
  • Refund and cancel. A captured payment can be refunded in full or in part, and an uncaptured one can be voided.
  • Pay out. Funds are sent to a bank account, card or wallet, singly or in batches.
  • Retrieve status. The caller can look up a payment's current status and history, and list payments for reconciliation.

Many APIs also store payment details as tokens through payment tokenization, so that a saved card or bank mandate can be charged again without the full details passing through the merchant's systems.

02

Webhooks and idempotency

Payments often do not finish in a single step. A bank transfer may take hours, a customer may need to complete authentication in another window, or a payout may be returned days later. Rather than asking the API repeatedly, the calling system registers a webhook, a web address to which the provider sends a message whenever a payment changes state. Providers usually sign these messages so that the receiver can confirm their origin, and resend them if they are not acknowledged. Because messages can arrive late, twice or out of order, receivers are expected to check each event against the payment's current state before acting on it.

Networks fail, and a request may time out without the caller knowing whether it succeeded. Sending it again could charge a customer twice. To prevent this, many payment APIs accept an idempotency key, a unique value the caller attaches to each request. If the same key arrives twice, the provider returns the original result instead of creating a second payment. This property, called idempotency, is a basic requirement for safe payment integrations.

03

Security and access

Every request must prove who is making it. Simple integrations use a secret API key sent with each call; others use OAuth tokens, which can be limited to certain actions and expire, or certificates that identify both sides of the connection. All traffic is encrypted with transport layer security. Providers also limit how many requests a client may send per second to protect their systems, and keep separate keys for testing and live use.

Card data brings extra obligations. A merchant whose servers receive full card numbers falls within the scope of the PCI DSS. Payment APIs therefore usually pair with hosted payment pages or embedded fields that send card details straight to the provider, so the merchant handles only tokens. In Europe, payments started through an API may also need strong customer authentication.

04

Testing and versioning

Providers offer a sandbox environment that mimics the live service with test cards, test bank accounts and simulated failures, so that developers can build and test an integration without moving real money. Many also publish a software development kit in common programming languages and a developer portal with reference documentation.

Because merchants build their systems around an API, changes must not break existing integrations. Providers therefore release new versions alongside old ones, let each merchant choose when to upgrade, and give notice before retiring an old version. Clear error codes and stable identifiers matter as much as speed, because payment failures must be handled automatically and reconciled later against bank statements. A good error response distinguishes a temporary problem worth retrying, such as a network fault, from a final decline that should not be repeated.

Last updated 16 Nov 2026