Merchant API

Overview

A merchant API lets a business integrate payment creation, status retrieval, transaction history, callbacks, and related merchant operations into its own systems. Duplicate creation, mismatched order identifiers, and incorrect status mapping cause operational errors. A merchant API connects checkout, orders, billing, support, and accounting with a payment provider. Reconciliation should connect provider tracking IDs with merchant orders, fees, refunds, and settlement records. For Merchant API, the application should preserve a correlation path from request construction through response, asynchronous completion, and final business state. Data handled by Merchant API should use documented types, units, timestamp rules, nullable fields, and enum behavior to prevent silent interpretation errors.

Integrations should use scoped credentials, unique order references, idempotency, strict amount handling, signed callbacks, and authoritative status checks. Typical capabilities create invoices or payment sessions, retrieve accepted currencies, inspect payment status, search history, and configure asynchronous notification workflows. Payment processing is asynchronous and can produce uncertain outcomes. A successful request may create an obligation without final payment, while a timeout may occur after the provider accepted it. A successful transport result from Merchant API should not be interpreted beyond the exact API state documented by the provider.

Testing Merchant API should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

The Merchant API owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

The Merchant API contract should define identifiers, validation, authorization, status semantics, errors, limits, and version behavior at the same boundary.