mozillafoundation/donate-wagtail

[Legacy] - Wagtail based donation stack

donate-wagtail's Issues

Site-wide data models

I propose to use site-wide settings to store the following:

• Legal footer text: rich text (required)
• Top navigation menu links: orderable sequence of link blocks that can link either to a page on site or to an absolute URL (required)
• Footer links: orderable sequence of link blocks that can link either to a page on site or to an absolute URL (required)
• Language code to currency mapping (as defined in #1).
• Currency information:
  • Code
  • Symbol
  • Allowed payment methods
  • Default donation amounts: for each currency, 4 default suggestion values for that currency.

It might be easier to store currency information in code instead - to make a call before starting work on this.

Detail page

Design / Wireframe:

Desktop: https://redpen.io/jc07fc459ff5f3fe81
Tablet: https://redpen.io/gpa264abeea7f4c799
Mobile: https://redpen.io/ykdc92900c06af901c

Components that form this template:

• Detail form
• Legal text

Disable certain payment options for certain currencies

Add the ability to disable certain payment options for certain currencies - e.g., to disable Paypal for AED.

A list of supported payment methods for each currency will be maintained as part of the data for that currency, and this will be used to determine which options are visible to the user on the landing/campaign pages.

Information required

1. Is it possible to control which card types are accepted on a per-transaction basis in Braintree (I haven't been able to find documentation that suggests it is)?

Side note - support for Amex has to be explicitly requested.

Translation functionality

This is a broad description of the translation functionality/workflow that we need to implement - which we can then break into specific tasks for implementation. My understanding of the key requirements and flows as follows - subject to review from the Mozilla team.

Translations will be provided by Pontoon, which operates on git repositories - i.e., it pulls translatable strings from a repository and will push translated strings back to it.

Code/template string translations

These will be handled in the normal way. Django will generate .po files which Pontoon will read and update with translations when they become available.

CMS content

CMS content in Wagtail will be made translatable using the wagtail-translation package (work in progress). This package provides a framework for generating translatable pages and a UI for managing those pages within Wagtail. It provides a mechanism for extracting text from page content into a series of translatable strings.

We will need to develop a way for these translatable strings to be relayed to/from Pontoon via a repository that Pontoon can push/pull from.

Landing page model

Field spec

• Featured image: image field (required)
• Introductory text: rich text (required)
• Partner logos: orderable sequence of image fields (optional)

Card payment flow - single payment

Implementation of card payment flow for single payments:

1. User details view for capturing address information. The donation amount is sent from the precending landing/campaign page.
2. Payment view for capturing card details via hosted fields. This view also needs to handle error reporting that isn't caught by Braintree's inline validation - e.g., things like denied transactions and blocked cards.
3. Thank you view.

(Upsell is handled separately in #26).

• I can complete a one-off credit card donation in USD from the landing page.
• After completing a donation I see a thank you page that confirms the amount I have donated.

Paypal payment flow - single payment

Implementation of Paypal payment flow for single payments:

1. Load Paypal checkout flow when Paypal option is selected on landing/campaign pages. Amount is determined via JS from the form on that page.
2. Error reporting on the landing/campaign page - we need to be able to report failures or early cancellation on the page from which the Paypal modal is launched.
3. Thank you view.

(Upsell is handled separately in #26).

Push transaction data to SQS

Push data about completed transactions to SQS.

Information required

1. API for pushing data to SQS.
2. What information should be sent and its structure.

Technical notes

My initial thoughts for implementation are that this should be done asynchronously via a worker process.

There is an open question about how much resiliency is required in terms of retrying failed push, and whether we need to store basic transaction data (a Braintree reference number) in Wagtail as a fallback.

Error message styling

We will need to apply styling to error messages that are rendered in various places:

1. Paypal error if you close the Paypal modal after loading it on the landing/campaign page.
2. Form errors on the card details view (to trigger this, disable browser validation and enter say an invalid email address), and for all other forms (upsell, newsletter).
3. Gateway errors on the card details view (to trigger this, enter a postcode longer than 9 characters for a US address).

Develop field specifications for campaign pages

Depends on #3 - once we are reasonably clear on the functional requirements we can develop field specifications for the key content types. This will describe the editable fields that each content type will expose and any validation requirements.

Error page templates and styles

We will need to update the 404 and 500 templates to be consistent with the rest of the site, and to present some meaningful information to the user.

On a related note I notice that any invalid URL on the current site (e.g., https://donate.mozilla.org/foooo) redirects to the home page. Is this behaviour you want to replicate @alanmoo ? I feel like it might have SEO implications (but not an expert in this) - but would imagine this is a deliberate decision?

Upsell template

Overview:

Asks the user to upgrade their one off donation to a monthly donation. Step 4 (Landing/Campaign > Details > Payment > Upsell) of the process, could potentially be optional, would only show for user that selected a one off payment.

Design / Wireframe:

Desktop: https://redpen.io/gtf39ea26c965f9605
Tablet: https://redpen.io/opc85e9f5502e7ed3f
Mobile: https://redpen.io/hz1a87f231444df639

Components that form this template:

• Title
• Introductory text
• Upsell form

Pass additional information to Braintree custom fields

There is a requirement to pass some additional information about transactions to Braintree in the form of custom fields.

Information required

• The specific data to be collected and passed to Braintree
• The structure of the data - i.e., what data goes into which custom field.

Notes

Braintree custom fields must be set up in the Braintree dashboard before we can pass data to those fields - this means that some decisions need to be made about which fields to set up.

Braintree doesn't appear to restrict the length of data stored in a given field, so it should be possible for example to dump JSON into a single custom field. Whether to do this (vs separating data into multiple fields) depends largely on the use case - e.g., do you need the ability to filter payments based on a field using the Braintree API.

Braintree customer data expects first name, last name

Braintree's customer data model expects a first name and last name for customers, but currently we don't ask for these separately.

My current approach is not to pass name information at all to Braintree - but if we want to store this information there then we will need to look at options:

1. Ask for first name and last name separately.
2. Do some parsing to try and split this ourselves? (This will quickly fall foul of cultural variances).
3. Dump everything into "first name"?

I don't think this has any implication for card verification - seems that only address and CVV is used for that, but that may also be a factor. Flagging as something we need to test before going live.

When I select a payment and submit I enter the payment journey

Define/review meta titles for all steps in all flows

I think it's worth reviewing the meta titles that we're setting on each step of the various flows, to make sure they are (a) consistent and (b) meaningful.

This should probably happen towards the end of the project.

Monthly card payments - set up Braintree support for multiple currencies

In order to process monthly payments, Braintree requires that:

The specified merchant account must be in the same currency as the subscription plan, or any attempted subscription transactions will trigger a validation error. If you want to use a merchant account with a different currency, you must create a new plan in the Control Panel with the indicated currency.

This means:

1. To accept monthly donations in all of the supported currencies, we will need to set up separate merchant accounts and plans for each currency.

2. You will need to talk to Braintree about getting access to all the currencies you want. By default they only provide the following:

   • AUD - Australian Dollar
   • BRL - Brazilian Real
   • CAD - Canadian Dollar
   • CHF - Swiss Franc
   • CZK - Czech Koruna
   • DKK - Danish Krone
   • EUR - Euro
   • GBP - British Pound
   • HKD - Hong Kong Dollar
   • HUF - Hungarian Forint
   • ILS - Israeli New Sheqel
   • INR - Indian Rupee
   • JPY - Japanese Yen
   • MXN - Mexican Peso
   • MYR - Malaysian Ringgit
   • NOK - Norwegian Krone
   • NZD - New Zealand Dollar
   • PHP - Philippine Peso
   • PLN - Polish Złoty
   • RUB - Russian Ruble
   • SEK - Swedish Krona
   • SGD - Singapore Dollar
   • THB - Thai Baht
   • TWD - New Taiwan Dollar
   • USD - United States Dollar

I don't think that either of these should be an issue, but if you haven't already it is worth talking to them about it as early as possible.

Removing primary navigation setting

The primary navigation component will be hardcoded, so there's no longer a need for it to be editable in wagtail. With this in mind we should remove it from the wagtail settings.

Campaign page

Overview:

Similar page to the landing page, but can be tailored to a certain cause, allowing us to create custom campaigns targeting user groups or search terms.

Design / Wireframe:

Desktop: https://redpen.io/te6a33f4a49c6b3522
Tablet: https://redpen.io/vx1e0d3503a45a7ac8
Mobile: https://redpen.io/tebe763a544821f642

Components that form this template:

• Hero (image, title, introduction)
• Partner logo (multiple)
• Donation form
• Legal footer text

Functional testing of flows

We are soon getting to the point where thorough testing of all the flows will be needed to make sure everything works as expected. This is a WIP list of the different flows/scenarios that we need to test, which might be worth putting into a matrix somewhere at some point.

Flows

1. Card single payment
2. Card monthly payment
3. Paypal single payment
4. Paypal monthly payment

All the above can be started from either the landing page or a campaign page - we need to test both.

Variations

1. Valid/invalid card numbers
2. Closing Paypal modal mid-payment
3. Upsell/skip upsell
4. Newsletter signup/skip newsletter signup

Single to monthly payment upsell

Implementation of a workflow to enable donors to set up a monthly payment having just completed a single payment.

Technical notes

Braintree requires a slightly different approach for setting up subscriptions - specifically creating subscriptions requires vaulting of a payment method.

The options here are:

1. Vault all payments (including single), so that we don't have to ask for this information again at point of upsell.
2. Don't vault single payments, in which case the user would have to go through the process of entering their details again at point of upsell.

(2) obviously makes for poor user experience, so I think (1) is the preferred option - we just need to investigate what the implications are of vaulting one-off payments (if any) and whether the Paypal flow for vaulting is more involved (if so there may be a more nuanced tradeoff that we need to make a decision on).

Fix npm tests and get them running on Travis

Card payment flow - monthly payment

Implementation of card payment flow for single payments:

1. User details view for capturing address information. The donation amount is sent from the precending landing/campaign page.
2. Payment view for capturing card details via hosted fields. This view also needs to handle error reporting that isn't caught by Braintree's inline validation - e.g., things like denied transactions and blocked cards.
3. Thank you view.

• I can complete a monthly credit card donation in USD from the landing page.
• After completing a donation I see a thank you page that confirms the amount I have set up a subscription for.

rtl layouts

Ensure that all page designs work with right to left languages.

Recommend we do this by adding a class to the app div that then updates the layout accordingly, app--rtl sounds sensible to me.

This would ensure all text is set to align right, and that the layout is flipped.

Ideally we'd have a design illustrating how this works on one template, then we can interpret the rest, but it's not essential.

Basket update: which fields needs to be changed or added?

After discussing with Samir on Slack about #27, it was decided to first update basket and then connect donate-wagtail to it. To do that, we need to know what fields needs to be updated/added/remove.

Curent JSON payload sent to basket:
first_name: first name of the donor (optional),
last_name: last name of the donor,
email: email of the donor,
donation_amount: amount of the donation,
currency: letter code for the currency,
created: unix timestamp,
recurring: false for a one-time donation or true for a recurring one,
service: name of the payment processor (ex: stripe or paypal)
transaction_id: ID generated by the payment processor,
project: name of the project that will receive the donation (ex: thunderbird, mozillafoundation)
last_4: last 4 digits of the credit card,
donation_url: url from which the donation was made,
locale: language code for the donor,
conversion_amount: donation amount in USD, before transaction fees,
net_amount: donation amount in USD, after transaction fees,
transaction_fee: payment processor's transaction fees in USD.

@solarissmoke Can you review those fields? Meanwhile I'll go and ask fundraising about the transaction fees.

Currency amounts internationalization

Not sure if this is already scoped/planned as part of another ticket, so filing it just to make sure.

Amounts + currency strings everywhere on the website will need to be formatted using Intl.NumberFormat https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat

This API will handle the currency symbol formatting, but also convert numbers to the appropriate script and pick separators (decimal, thousands, etc).

Example in Arabic, where numbers are converted to the Arabic script

I think the current website uses a npm package, but that package relies on this API ultimately (which is definitely the way to go)

This API would also solve #93 (commented in there with the relevant example + method)

Paypal payment flow - monthly payment

Implementation of Paypal payment flow for monthly payments:

1. Load Paypal checkout flow when Paypal option is selected on landing/campaign pages. Amount is determined via JS from the form on that page.
2. Error reporting on the landing/campaign page - we need to be able to report failures or early cancellation on the page from which the Paypal modal is launched.
3. Thank you view.

Footer email signup

The designs include an email signup form in the footer.

What is the desired behaviour when the user submits this form? Will it redirect to a confirmation/thank you page, or do we process via AJAX and indicate success with a UI change?

Confirm approach for localisation and currency detection

A few queries about localisation and currency defaults:

1. Is browser language preference used to determine the default language presented to the user?

2. How should the default currency be determined? Is this currently determined from location (e.g., using IP geolocation)?

3. How should we determine suggested donation amounts in each currency? Will these vary on a per-campaign basis?

Landing page

Overview:

Landing page for the MoFo donation process, gives a brief overview of MoFo and encourages users to make a donation.

Design / Wireframe:

Desktop: https://redpen.io/qmb0c00a7348799ffe
Tablet: https://redpen.io/ng6b764da5350b6e79
Mobile: https://redpen.io/jtc87960cd6f960231

Components that form this template:

• Feature Image
• Introductory text
• Partner logo (multiple)
• Donation form
• Legal footer text

Prevent submission of card details form if all required fields are not completed

Regular browser form validation doesn't work here because the submit button fires Braintree's JS rather than a regular form submission.

Add recaptcha

Add recaptcha to landing/campaign page forms.

We should also review what other steps we need to take to mitigate against carding attacks.

Thank you page

Overview:

Final step in the donation process, thanks the user for their donation and prompts them to share via their social networks.

Design / Wireframe:

Desktop: https://redpen.io/vr3ed558332f842713
Tablet: https://redpen.io/qgcd8ac4753ebe3c23
Mobile: https://redpen.io/dbf4cf795b2beec7c8

Components that form this template:

• Title
• Introductory text
• Social share

Translate JS

Once all the JS is in place for Braintree, we need to add translation for the strings (mostly error messages) that are used there.

Set up sandbox accounts for payment processors

We'll need sandbox accounts for:

1. Braintree
2. Paypal (merchant)
3. Paypal (buyer)

It might make sense for Mozilla to set these up and share access privately, so that you have these for development going forward.

Global header/footer

Design / Wireframe:

Desktop: https://redpen.io/qmb0c00a7348799ffe
Tablet: https://redpen.io/ng6b764da5350b6e79
Mobile: https://redpen.io/jtc87960cd6f960231

Notes: Header code can be taken from existing site's repo, as it's unchanged https://donate.mozilla.org/en-US/ . Footer TBC

Set correct Site hostname for default site during deployment

It would be nice if we can set the correct hostname on the default Site during deployment on heroku, so that things like page previews work without having to manually alter the site settings (a 500 is thrown if you forget to do this).

See also the approach taken here for generating sample data for review apps: https://github.com/mozilla/foundation.mozilla.org/blob/master/network-api/networkapi/wagtailpages/factory/homepage.py

Newsletter step is being skipped on upsell flows

Develop functional specification for campaign journey

A functional specification for the campaign functionality will help us to ensure we've got all the required features covered (perhaps just this ticket can be the spec as we develop it). The bits that I think we've discussed already (but open to feedback/refinement):

• Ability to specify custom content on the landing page for a campaign.
• Ability to specify default donation amounts for a campaign (e.g, $3.14 for Pi day), in different currencies, with fallback to global defaults. (NB note from Jesse - "my strong preference so we don't wind up with a complex matrix of prices...").
• Ability to specify default donation frequency (single/monthly) for a campaign.
• Ability to specify the benefactor for a campaign and for this information to be passed through to Braintree.

Open questions/potential features to discuss:

• Custom content on thank you page after a donation is made?
• Confirmation email sent to donor (or is this handled separately via Salesforce)?

Tech Spike - Pontoon integration

To ensure we make the best implementation of pontoon we will undertake a tech spike to explore our approach

More flexible handling of currency symbols

From discussion on #82:

A lot of locales will want the currency symbol to be displayed after the value, would it be possible to add a conditional for that? Maybe storing that preference in settings?

To give you an idea: https://transvision.mozfr.org/string/?entity=mozilla_org/mozorg/home/index-quantum.lang:3fe118b0ed61665a878f4a81ef2d3357&repo=mozilla_org

Better handling of Paypal failures

Our currently handling of Paypal failures is to render a page with "Something went wrong! Please try again later", which isn't particularly helpful to the user.

I am not sure what the best UX here is, but I think we should probably send the user back to the landing page and display an error message there.

Currency switching

Add currency switching capability to the landing/campaign page forms. Propose to do this after the basic donation flows (single/monthly) have been set up in USD.

Other amount donation selection

The other amount field will require some js to select the checkbox when focused, and also to populate a hidden input with the amount entered.

Campaign page model

Field spec

• Hero image: image field (required)
• Title: plain text (required)
• Lead text: plain text (required)
• Partner logos: orderable sequence of image fields (optional)
• Default donation amount overrides: optional list of items mapping a currency to list of 4 suggested donation amounts.

Notes

• If a currency is not listed in the donation amount overrides, then we will fall back to the global defaults.
• Legal text is fetched from global configuration (i.e., does not vary per-campaign).

No menu class when on a non-English language

I've added a class (app--no-menu) to apply to app that hides the burger menu, we just need the backend to apply this based on current language.

Email signup

Overview:

Prompts the user to signup to the Mozilla email list by entering their email address, and confirming they have read the privacy policy.

Step 4/5 (Landing/Campaign > Details > Payment > Upsell (optional) > Email signup) of the process, could potentially be optional, and could show for both monthly and one off donations.

Design / Wireframe:

Desktop: https://redpen.io/eo137e0b58bf3ace18
Tablet: https://redpen.io/axd4e004cbcfbd16dd
Mobile: https://redpen.io/ahe3dd0e181414c277

Components that form this template:

• Title
• Sub title
• Introductory text
• Email signup form

Payment page

Design / Wireframe:

Desktop: https://redpen.io/wc32042c29a9469ca3
Tablet: https://redpen.io/htf5aa93e00a71214e
Mobile: https://redpen.io/sr0030705d1be8c65f

Components that form this template:

• Steps (Payment active)
• Payment form
• Partner logo (multiple)
• Legal text

Post-payment email sign up

Provide the option for the user to sign up to the newsletter after they have completed payment.

Information required

1. Where should the form data be sent (SQS)?

When I land on the donations page I want to select either single or ongoing payment

When I land on the donations page I want to select either single or ongoing payment.

• The user can switch between making a single or ongoing payment

• The user will see different suggested donations depending on their selection

• 3x suggested values will be shown for each option

• Each view (single/ongoing) will have a default suggested donation