Fundraising tech/Refactor

Goal: push as much back-end functionality into SmashPig as possible

SmashPig

Already can

• Directly receive payment confirmations via http and parse them into normalized messages
  • Should the listener front end be split out? Probably not - no need for ui / messages
• Parse audit files into normalized messages

Should be able to

• Determine available payment methods given initial data and merchant account configuration.
• Specify required data and validation rules for each payment method
• Validate provided data before performing an API call
• Make API calls to payment processors and normalize the response
  • select correct credentials for country & call based on merchant account configuration
  • protected function doPaymentApiCall( $name, $data )
    • returns PaymentApiResponse (now called PaymentTransactionResponse)
    • throws Exceptions for anything that stops us before we have a response to normalize, like errors in validation, configuration, or communication
• Perform a series of related API calls to effect a payment and return a PaymentResult
  • public function doPayment( $data )
  • public function doRecurringCharge( $data )
  • public function checkPaymentStatus( $data )

DonationInterface

In a nutshell: renders forms, translates messages, gathers input.

• Passes configuration options to SmashPig (?)
• Collects initial language, country, currency, amount, contribution tracking data, and optional payment method
• Makes initial calls to SmashPig:
  • if payment method requested, validate the initial data against the requested payment method
  • if no method requested or requested method is unavailable, select best alternative method
  • obtain the full specification for the selected method
• Based on the results of above:
  • If specification indicates an immediate redirect processor such as PayPal or Amazon, perform a doPayment call and redirect
  • Otherwise, render the appropriate payment form as determined by form settings and ffname parameter
    • Submethod choices and field visibility driven by method specification obtained from SmashPig
• Perform front-end validation according to rules obtained from SmashPig
• Making a doPayment call to SmashPig and acting on the PaymentResult
  • Displaying appropriate error messages and adapting the form if needed (e.g. making amount editable)
    • Selecting and localizing the messages corresponding to normalized SmashPig error codes.
  • Rendering an appropriate payment failure page
  • Opening an iframe with PaymentResult's URL
  • Redirecting to PaymentResult's URL

Errors

Errors from SmashPig should have

• Severity (basically LogLevel)
• Context (i.e., related field name or 'general')
• Error code - one of our standardized ResponseCodes
• Original error object from processor

Severity + context + code should be expressive enough that the front end can show the appropriate error message without SmashPig picking a message id

Edge cases include validation errors that prompt a change in other data, like fallback currencies

Validation errors can be a result of internal validation or processor validation

Should validation errors have some info beyond just field, like min/max values?

Logging

Move into SmashPig Everything should use PSR compliant loggers, with a way to plug in appropriate LogHandlers for each environment.

Terminology

Invoice number = our internal identifier for a given payment attempt. Standardize on ct_id.num_attempt?

Merchant Account

Can configure multiple accounts for each processor. Account properties:

• merchant id / username
• password
• shared secret
• list of countries
• Processor API URL
• Some other identifier to distinguish between multiple sets of credentials, e.g. how AstroPay has different logins/passwords for different API calls