Handling payment for orders in REST API

Question

I'm building the order endpoint for an ecommerce rest api so that clients can place orders. I'm trying to determine the advantages or disadvantages of two approaches:

Approach 1

Payload:

{ 
  'total',
  'customer': {'firstName', etc.},
  'shipping_address':{'address1', etc.}
  'items': [{'nameOfItem', 'sku', 'price', etc.}, ...]
  'payment': {'type', 'credit_card':{'number', 'expiration_date', etc.}}
}

Pro:

• Let users pass the payment in the payload. I think this is a simple approach; clients and also the api don't have to synchronize orders and payments. With one POST request, the authorization and capture will be executed for the order.

Con:

• I think it is less flexible. If I want to support different payment types in the future like saved payments, paypal, etc., I might have to make changes that might affect the payload and make it more complex. Also, I think it couples my order placement flow with the transaction operations - authorization and capture.

Approach 2

Take out the payment information from the order POST request payload and have a different endpoint to handle the transaction operations for a given order.

order/<ordernumber>/transaction/capture 

{ 
  'payment': {'type', 'credit_card':{'number', 'expiration_date', etc.}}
}

Pro:

• Decouples operation to create an order from the transaction operations. I'm not sure if flexibility is even needed for this though.
• It seems like it is a pattern used by most ecommerce apis - shopify, woo, magneto - to decouple the payment from the orders, carts, etc. so developers that will use this api will most likely be familiar with this pattern.

Con:

• Not as simple. We need to synchronize two operations: creating orders and paying for them.

I don't have good reasons for going with approach 2 and the software that our organization owns follow the pattern in approach 1. Therefore, I am hoping that someone here can provide guidance or information for me to consider. Thanks.

Answer 1

Use cases which require separate payment screen from order:

1. Payment initially succeeds but then fails or is taken back. The customer is in debit and needs to make a payment but the order has already been placed.
2. Some admin charge or unexpected fee is raised against the account, the customer has make payment to settle, but there is no order.
3. Customer is in credit for some reason, perhaps a refunded order. They place a second order but the payment amount is not value of the order
4. Customer pays on delivery or account, or some other deferred payment approach.
5. You have sold a subscription and needs to take regular payments.
6. The Boss put the order in manually and now the customer wants to pay.

etc

Businesses generally treat orders, invoices, payments etc separately because that's how accounting is done and their eCommerce systems match accounting practices

Answer 2

Actually, I think it's better to have different APIs, My reason for this suggestion is if you have a limited number of products in stock, you might need to manage/reserve the stock from the "add to cart" step till the customer pays the invoice and if you don't do that and return an error to the customer due to unavailability of the product when he tries to pay, it leads to customer dissatisfaction.

But from an Architecture point of view, each API could be provided by different microservices, i.e one microservice for catalog & cart and another one of payment gateway which enables to have scalability and maintainable code.