Payment Gateway API Design: Stripe

Payment gateway fundamentals

A payment gateway enables customers to transfer funds to merchants via credit or debit cards, connecting millions of buyers and sellers through a deceptively complex set of services. Both customers and merchants interact with the gateway through its API. Designing an API for a service like Stripe requires clearly defined functional and non-functional requirements.

Functional requirements

• Payment: Allow merchants to charge customers for purchases.

• Customer data: Support creating, updating, deleting, and securely storing customer information (cards, personal details).

• Invoices: Generate invoices before charging customers.

• Transaction details: Expose all transaction data (purchases, refunds, payouts) and support both one-timeA one-time payment is when customers are charged only once for a product or service. and recurring paymentsA recurring payment is when customers are charged periodically..

• Balance: Enable merchants to view account status, current balance, and statements.

Nonfunctional requirements

• Strong consistency: All sources of truth must be updated atomically. A deduction from one account must always be reflected as a credit in another.

• Security: State-of-the-art encryption, authentication, and authorization protect transactions, accounts, and card details.

• Reliability: Continued operation despite component failures.

• Availability: Uninterrupted service for all customers and merchants.

• Scalability: Support for any number of customers, merchants, and transactions.

Prerequisites

• API security

• Client-server communication

• Data formats

• Architecture styles

• Latency budget

The payment process

Fintech advancements have enabled e-commerce by building trust between merchants and customers. Modern payment systems go beyond simple fund transfers, improving the customer experience and simplifying operations for merchants. An online payment appears instantaneous, but behind the scenes, it involves cardholder verification, payment processing, merchant registration, and multiple interacting entities.

The following figure illustrates the flow of a payment processing system:

The roles of the entities involved in the payment processing system are listed in the following table:

Note: An issuer processor sometimes sits between the issuer bank and the card network, facilitating authorization, clearing, and settlement on behalf of the issuing bank. Many issuer banks run in-house processors for greater control and cost savings.

The fund transfer process behind the scenes occurs in two phases:

1. The authorization phase

2. The settlement phase

The authorization phase

We assume that the customer holds an account at the issuing bank and the merchant holds an account at the acquiring bank, with a virtual Stripe account storing all transactions. The authorization steps are:

1. The customer selects goods, proceeds to checkout, and enters credit card information, creating a transaction record.

2. Transaction information is forwarded to Stripe, which stores the details for later fund transfer.

3. Stripe routes card details and transaction information to the card network.

4. The card network authenticates the card and passes transaction information to the issuing bank for account validation.

5. The issuing bank verifies account status and fund availability, placing a hold on the required amount.

6. The issuing bank responds with a successful authorization codeAn authorization code is an alphanumeric value that approves a transaction. This code is later used in the settlement phase. via the card network to Stripe.

7. Stripe sends the authorization code to the acquiring bank.

8. The acquiring bank approves the merchant's terminal, which may issue a receipt to the customer.

9. Stripe updates its database with the authorization codes provided by the issuing bank.

The authorization phase is explained in the following illustrations:

Note: Every organization that processes, stores, or transfers credit card information must be PCI compliant. The PCIThe PCI (Payment Card Industry) Security Standards Council is an organization that administers and enforces data security standards related to online payment transactions. mandates using the Secure File Transfer Protocol (SFTP) to transmit sensitive data.

The settlement phase

With authorization complete and funds locked, the settlement phase transfers the accumulated successful transaction amounts to the ...