I’m not saying Stripe API is bad. But there are limits to how much differences you can hide behind a generic API while keeping it consistent.
Off the top of my head I can think of a few cases I would qualify as a leaky abstraction. To start with - there is a payment method abstraction and there is SetupIntent that works with it. Normal use case is tokenizing a CC. But for ACH it does something different if ever works. Same setup intent would work with debit cards, but not in Brazil because of local regulations. I don’t remember if you get a decent error code when attempt to tokenize a Brazilian debit card.
Customers making cards payments can initiate a dispute which would cost you 15 usd + payment amount if they win. This cannot happen with some other payment methods. It became important when you implement Stripe connect because you might want to set different fees for different payment methods to account for cost of disputes. The leaky abstraction part here is as soon as you start creating certain type of payment intents you also have to subscribe to Stripe webhooks for disputes.
To save on refund fees you may want to authorize payments (confirm payment intent) and capture them after a period of time. During that window you can cancel the payment and pay only authorization fee instead of paying full refund fee. This strategy works only for payment methods supporting authorization and capture semantics and having favorable commission structure. Max amount of time between confirm and capture depends on the payment method as well.
Not specific to Stripe Terminals but still. Tapping a card gives you an anonymized payment method while dipping the same card reveals some cardholder data. This is beyond Stripe control, but puzzling at first because at the API level you deal generic PaymentMethod object.
With Stripe connect what happens after the payment is defined in terms of abstract transfers between Stripe accounts. In some regions transfers works across countries while not in the others. One example is Canada-USA vs Brazil and rest of the world. From one end you have abstract transfers API to move money between Stripe accounts. From another you have to implement a number of workarounds to make transfers work in all interesting scenarios because of regional and currency conversion considerations. For example in some cases you do transfers while in other you do payment intents.
What I’m trying to say here is you have to know specifics of payment methods, underlying technologies and regions you work with. By looking at high-level API you may think it is easy to support many payment methods when in fact many of them would require very specific code.
Off the top of my head I can think of a few cases I would qualify as a leaky abstraction. To start with - there is a payment method abstraction and there is SetupIntent that works with it. Normal use case is tokenizing a CC. But for ACH it does something different if ever works. Same setup intent would work with debit cards, but not in Brazil because of local regulations. I don’t remember if you get a decent error code when attempt to tokenize a Brazilian debit card.
Customers making cards payments can initiate a dispute which would cost you 15 usd + payment amount if they win. This cannot happen with some other payment methods. It became important when you implement Stripe connect because you might want to set different fees for different payment methods to account for cost of disputes. The leaky abstraction part here is as soon as you start creating certain type of payment intents you also have to subscribe to Stripe webhooks for disputes.
To save on refund fees you may want to authorize payments (confirm payment intent) and capture them after a period of time. During that window you can cancel the payment and pay only authorization fee instead of paying full refund fee. This strategy works only for payment methods supporting authorization and capture semantics and having favorable commission structure. Max amount of time between confirm and capture depends on the payment method as well.
Not specific to Stripe Terminals but still. Tapping a card gives you an anonymized payment method while dipping the same card reveals some cardholder data. This is beyond Stripe control, but puzzling at first because at the API level you deal generic PaymentMethod object.
With Stripe connect what happens after the payment is defined in terms of abstract transfers between Stripe accounts. In some regions transfers works across countries while not in the others. One example is Canada-USA vs Brazil and rest of the world. From one end you have abstract transfers API to move money between Stripe accounts. From another you have to implement a number of workarounds to make transfers work in all interesting scenarios because of regional and currency conversion considerations. For example in some cases you do transfers while in other you do payment intents.
What I’m trying to say here is you have to know specifics of payment methods, underlying technologies and regions you work with. By looking at high-level API you may think it is easy to support many payment methods when in fact many of them would require very specific code.