Digital Payment system design

Design a payment backend system for an eCommerce application like Amazon.com. When a customer places an order on Amazon.com the payment system handles everything related to money movement.

Payment system should support payment by Credit Card, PayPal, Bank cards etc. Underline credit card payment will be taken care by third parties processors such as Stripe, Square etc.

Design system to support payment transaction of 1 million transaction per day.

It should also support pay-out flow to pay sellers.

High level system design

At a high level the payment flow is broken down into two steps to reflect how money flows

1. Pay in flow: After a buyer places an order the money flows into Amazon’s bank account. This money is substantially owned by seller. eCommerce only works as the money custodian for a fee.
2. Pay out flow: Once products are delivered to buyer then eCommerce takes its fee and remaining balance is transferred from eCommerce’s bank account to the seller’s bank account.

Pay-in flow system design

Following are different components in the Pay-in flow system.

Following are steps for Pay-in flow.

1. When a user clicks the place order button, a payment event is generated and and request is send to the payment service.
2. The payment service stores the payment event in the database.
3. In case of paying multiple products at a time, a single payment event may contain several payment orders. In this case payment service calls the payment executor for each payment order.
4. The payment executor stores the payment order in the database.
5. The payment executor calls an external PSP to process the credit card payment.
6. After the payment executor has successfully processed the payment, the payment service updates the wallet to record how much a given seller has.
7. The wallet server stores the updated balance information in the database.
8. After the wallet service has successfully updated the seller’s balance information, the payment service also calls the ledger to update it.
9. The ledger service appends the new ledge information to the database.

Following is schema for PaymentEvents

Name                 Type
checkout_id          string PK
buyer_info           string
seller_info          string
credit_card_info     string - based on card provider
is_payment_completd  boolean

PaymentOrders stores the execution of each payment order. Following is schema for this table.

Field            Type        Description    
payment_order_id string PK   The globally unique Id for this payment   
buyer_account    string      Buyer account to deduct money        
seller_account   string      Which seller will receive the money
amount           string      The transaction amount for the order
currency         string      The currency for the order
checkout_id      string FK
payment_order_Status string
ledger_updated  boolean
wallet_updated  boolean

payment_order_id is UUID and payment executor sends a payment request to third party PSP with payment_order_id which is used by PSP as deduplication to support idempotent operation.

Q. What are different values for payment_order_Status?

1. NOT_STARTED
2. EXECUTING
3. SUCCESS
4. FAILED

Q. Why amount is not double?

Different hardware may support difference numeric precisions in serialization and deserialization. This may cause rounding error.

Double entry ledger system

Double entry ledger system is fundamental to any payment system and is key to accurate bookkeeping. It records every payment transaction into two separate ledger accounts with the same amount. One amount is debited and other is credited with the same amount.

Account        Debit        Credit
buyer          $1            
seller                      $1

The double entry system states that the sum of all the transaction entries must be 0. One cent loss means gain for someone else. It provides end-to-end traceability and ensures consistency throughout the payment cycle.

Hosted Payment page

Most companies prefer not to store credit card information internally because if they do they have to deal with complex regulations. To avoid handling credit card information, system use hosted credit card pages provided by PST.

It’s a typical widget of a iframe or page on mobile SDK. Following is example for PayPal checkout page.

Pay-out flow

The components of the pay-out flows are very similar to pay-in flow. One difference is that instead of using PSP to move money from buyer’s credit card to the eCommerce bank account, the pay-out flow uses a third party pay-out provider to move money from eCommerce bank account to the seller’s bank account.

Reconciliation

In distributed system therefore no guarantee that every components will always works. To handle failure we use reconciliation process for correctness purpose.

This is a practice that periodically compares the states among related services in order to verify that they are in agreement. It is usually last line of defense in the payment system.

Every night the PSP or banks send a settlement file to their clients. The settlement file contains the balance of the bank account, together with the all the transactions that took place on this bank account during day. The reconciliation system parses the settlement file and compares the details with the ledger system.

It is also used to verify the payment system is internally consistent.

Handling payment processing delays

Due to distributed nature sometime payment process may takes hours or stall for days or get rejected.

PSP would handle these long running payment requests in the following ways

1. The PSP would return a pending status to our client. Our client would display that to the user. Our client would also provide a page for the customer to check the current payment status.
2. The PSP tracks the pending payment on our behalf, and notifies the payment service of any status update via the webhook the payment service registered with the PSP.

This post is based on ByteByteGo system design. Feel free to go through original course.

Happy learning :-)