Fundraising tech/orphan slayer

What is the Pending Table?

The pending table is a SQL Database Table which exists in the Smashpig database. Basically, the Pending table holds information about transactions which have already begun but are yet to be completed on our servers.

Removing data from the Pending Table on the Smashpig Database

As well as the OrphanSlayer, other ways by which rows are removed from the Pending Table are:

1. The payment initial queue consumer would delete rows in the Pending table that correspond to rows in the fredge payment initial table with a status of “Rejected”.
2. Donation queue consumer deletes items in the pending database with an existing order ID in the donations table. This is done in order to leave only ongoing transactions with undetermined final status in the pending table.

The donation queue consumer is run every 3 minutes after the 5th minute of any hour up to the 59th minute, while the payment initial queue consumer is run every 2 minutes after the 1st minute of any hour up to the 59th minute.

What transaction is considered an orphan?

A transaction is considered an orphan if it exists in the pending table with a "PENDING-POKE" status.

What is the OrphanSlayer?

The orphan slayer is a Drupal module that basically reinitialises SmashPig on the orphan transactions described above. It works on transactions that are in the PENDING-POKE status. Transactions in the PENDING-POKE status are basically transactions that made it to the gateways but for some reason weren’t able to return back to our servers for the final steps. The overall goal of the orphan slayer is to remove orphan transactions from the Pending table of the SmashPig database.

How does the OrphanSlayer work?

The following steps are taken in the OrphanSlayer module in order to remove orphan transactions from the Pending table of the smashpig database:

1. Get the oldest transaction from a particular gateway (for ex. Ingenico, Paypal) in the Pending table.
2. In order not to perform the rectification operation on the transactions hastily, there exists a loop that checks to ensure the oldest transaction is above 30mins old. At that age, it's safe to assume that something occurred that prevented the action from being completed.
3. The “Contribution tracking ID” is a unique ID assigned to a donation in the pending queue. If the selected transaction has a “Contribution tracking ID”, the method goes ahead to rectify the transaction. Else, the transaction is cancelled.
4. In order to rectify an orphaned transaction, the gateway adapter would be reinitialized using information from the transaction.
5. The “Contribution ID” is the unique ID assigned to a completed donation transaction. Hence, a donation in the pending table with a “contribution_id” value would imply that the transaction has been completed and as such wouldn’t need to be rectified.
6. The rectification process depends on the gateway selected due to the different implementation of the “processDonorReturn” method across the gateway adapter. The “processDonorReturn” method ideally should be run immediately after the donor makes payment on the gateway and is redirected to our servers for final steps. Hence in order to get orphaned transactions to the final status, the “processDonorReturn” method would have to be reinitialised on the transaction. For ingenico, the procedure followed in the “processDonorReturn” method are as follows:
   1. Get the pending transaction order status from payment processor
   2. Perform action for ‘Confirm_CreditCard’ transaction
   3. Initiate stopwatch for the transaction logging
   4. The server’s validation action determines if the transaction needs to be captured.
   5. Transaction is either cancelled or captured depending on the order status and the validation action result.
   6. Stopwatch is stopped and transaction process time is logged.
7. If rectification is successful or process is cancelled the corresponding row on the Pending table is deleted, if the payment was captured the message is pushed to the donation table.

UML diagram

A visual representation of this process can be viewed on this UML diagram

Note

The OrphanSlayer does not work for the Adyen/Astropay gateway transactions because they allow donors to reuse the merchant reference by reloading the hosted page.