This article will focus on the system implementation of the Transaction system.

ORM Data Fields

Timestamps

• Compulsory
  • created_time Time when buyer start a transaction
• Optional
  • accepted_time Time when seller accept the transaction
  • confirmed_time Time when seller confirm transaction finished
  • completed_time Time when buyer confirm transaction finished

For more info about the design, check out Transaction Design page in Ref.

There are 3 gaps that may cause a timeout in this system. Some of them lead to Transaction Cancel, some of them lead to other operations like auto-confirm.

Seller Accept Timeout

Seller did not accept the transaction in time after buyer started a transaction.

This should lead to Transaction Cancel with cancel reason: seller_accept_timeout

Seller Confirm Timeout

Similar to Seller Accept Timeout, with cancel reason: seller_confirm_timeout

Buyer Confirm Timeout

This will not lead to the cancellation of a transaction. The default action will be auto-confirm this transaction.

Cancel Reason

Cancel reason is represented using an Enum class:

class TradeCancelReason(Enum):
    seller_rejected = "seller_rejected"
    seller_accept_timeout = "seller_accept_timeout"
    cancelled_by_buyer = "cancelled_by_buyer"
    cancelled_by_seller = "cancelled_by_seller"
    seller_confirm_timeout = "seller_confirm_timeout"

Cancel reason is Nullable, usually be set when timeout or user manually cancel a transaction.

Endpoints Design

The following only list endpoints and infos that are not be abled to directly into the code comment, and act more as a supplement to the endpoint docs and code comments. Please also read API endpoints comment before using them.

Get Transactions

Just like the Transactions in other apps, we categorized the transaction mainly by it's state:

• Active
  • Pending
  • Processing
• Inactive
  • Completed
  • Cancelled

Basically, we should provide a unified endpoint to allow users retrieving all related transactions. Endpoint receives a list of Transaction Type as parameter, which will later be used as filtering conditions.

Also, special marks active and inactive should be allowed to passed to endpoint as filter. And this is recommended way of using this endpoint. This is because more transaction state could be added to the systems in the future, and using active and inactive could improve forward compatiblity in some cases.

Another thing to notice is that: this endpoint will return transaction related to current user, both considering current user as buyer and seller. This means the transaction with this user as the seller will also appeared in the result list.

Accept Transaction

Endpoint will check:

• If item is valid to start a transaction. (This is because, if an item is valid for start a new transaction, then it should be valid to have a accepted transaction)
• If the transaction is in pending state.

If check passed, endpoint will update accepted_time, update transaction state to processing

Confirm Transaction

Before a user try to confirm a transaction, we need to check:

• If this user seller or buyer of the transaction
• If the transaction is in processing state

If check passed, we need to check:

• If the user is seller
  • Update confirmed_time, notify buyer to confirm.
• If the user is buyer
  • Update confirmed_time, call complete_transaction()

---

Note that do not directly complete transaction using functions like complete_transaction(). Instead, using confirm_transaction() to finally trigger the state update of transaction state and mark it as success.

However, some of the logic could be seperated into functions like complete_transaction(), for example:

• Update transaction completed_time
• Update transaction state
• Update item state
• Notify users.
• Etc.

Ref

Transaction Design