Designing a public payments API for outside developers: flows, endpoints and safeguards

Design an API that lets third-party software build payments into its product. The prompt leaves open whose API this is and which payment flows it covers, so pin down the scope first. Then walk through who integrates and why, a single payment from the integrator's point of view, the resources and endpoints, and how the design keeps money correct, protects sensitive data and stays easy to adopt. ```hint Decide who calls whom "Third-party integration" can mean outside merchants and apps calling your payment service, or your product calling outside payment providers. Choose one, name the integrator, and trace one payment from checkout to the money landing before you list any endpoints. ``` ### Clarifying Questions - Whose API is it: a payment provider offering merchants and apps a way to accept payments, or a product that needs to plug into outside gateways and processors? - Which integrators come first: online stores and apps, in-person point-of-sale systems, or business software such as ERP and accounting tools? - Which flows are in scope: one-time card payments, wallets and bank transfers, refunds, saved payment methods, subscriptions, payouts? - Which countries launch first, given that dominant payment methods and regulation differ by market? ### What a Strong Answer Covers - A stated scope: the API owner, the integrator, the payer and the business goal, plus what is deliberately left out. - The payment lifecycle and the resources and endpoints that drive it, with representative requests, responses and error behavior. - How timeouts, retries and asynchronous outcomes are handled so no one is charged twice and both sides can reconcile. - Security and compliance: how integrators authenticate, where card data lives, customer authentication, and how notifications are verified. - Developer experience and success metrics: test environment, versioning, documentation, and how you would know integrations are succeeding. ### Follow-up Questions - A merchant's server sends a create-payment request, times out and sends it again. Walk through what your API does so the customer pays once. - How would you ship a breaking change to the API without disrupting merchants who are already live? - If the authorization success rate drops overnight in one country, how would the data your API records help you find the cause?