Tablet Fundraising

info

If you are planning to use payment methods where the payment is processed in real time, for example a credit card payment that is immediately confirmed by an acquiring partner, often these payment methods require user input of confidential data. Potential donors will be very hesitant to enter confidential data like credit card details or login credentials for Apple Pay on a tablet provided by a stranger on the street. A simple solution to this problem can be provided using RaiseNow technology. By directing users to a prefilled donation form, where user can add those crucial details using their own device, the trust problem can be eliminated. This guide will show you how.

Outline

• Your Face-to-Face fundraiser uses your tablet fundraising application to collect the donors data.
• Your application generates an identifier for this particular submission. Your application will pass this identifier to RaiseNow. When RaiseNow has processed the payment or subscription submitted, your application can receive a notification containing this identifier.
• You generate a QR code on your tablet fundraising application. That QR code includes the information collected on your application as well as the identifier generated above.
• The donor scans that QR code and is redirected to a RaiseNow donation form. The form will be prefilled with the data passed in the QR code.
• The donor selects the desired payment method and enters required payment details.
• Upon successful processing of the payment or subscription, RaiseNow notifies your application and you can load the success screen.

Setup

Assumptions

For the below example we will make a couple of assumpations:

• Your app generates a record identifer app_record_identifier=your-identifier
• You have requested and received a tamaro widget from RaiseNow support for your customer. This widget is available under https://url-to-your-widget. Note: This approach will not work with a RaiseNow solution registered via Hub self-service.

Register Hub event subscriptions

Depending on your requirements integration you may want to subscribe to the following events:

• rnw.event.payment_gateway.payment.succeeded
• rnw.event.payment_gateway.payment.failed
• rnw.event.subscription_service.subscription.activated
• rnw.event.subscription_service.subscription.cancelled

Please refer to the webhook section for details on registering endpoints and event subscriptions. An identifier provided with a payment or subscription will be added to the custom_parameters element in the event body of the corresponding object. Please see the events section for examples.

QR Code

This string is an example of the information you should put into your QR Code:

https://url-to-your-widget?rnw-stored_customer_salutation=mr&rnw-stored_customer_firstname=Anton&rnw-stored_customer_lastname=Tablet&rnw-stored_customer_email=doe%40raisenow.com&rnw-stored_customer_street=Hardturmstrasse%20101&rnw-stored_customer_zip_code=8005&rnw-stored_customer_city=Zurich&rnw-stored_customer_country=CH&rnw-payment_type=recurring&rnw-recurring_interval=yearly&rnw-stored_app_record_identifier=your-identifier&rnw-stored_campaign_id=7011i00000024uHAAQ&app-prefill-amount=90&app-prefill-payment-method=card

A note on some of the fields passed here:

• rnw-stored_campaign_id: The value provided in the above example will not be correct for your case. This value will be specific to your customer and their campaign. Especially if the customer has a third party system connected to RaiseNow (such as Salesforce or Dynamics CRM systems), it is crucial these parameters are coordinated with your customer. Please check with RaiseNow support when in doubt.
• rnw-recurring_interval=yearly|quarterly|semestral|monthly: This will set the recurring interval. You can remove this parameter to allow for one-time payments.
• rnw-stored_app_record_identifier=your-identifier: Set his parameter according to the identifier you expect to receive upon form submission via the RaiseNow event notification.
• For a complete list of available fields, please check the field names in the Tamaro widget itself.

Widget configuration

This code snippet will customize a Tamaro widget to hide certain fields and steps to optimize the checkout experience for a link pre-selecting most fields. You must adapt this according to the fields passed in above url parameters and according to the requirements of your customer. This example optimizes to request as little information as possible. Note, that in some cases Tamaro may overwrite this configuration if required fields must be provided to complete the requested operation.

<div class="root"></div>
<script>
  // Set amount and payment method based on query parameters
  window.rnw.tamaro.events.afterCreate.subscribe((event) => {
    const api = event.data.api;
    const urlParams = new URLSearchParams(window.location.search);

    const amount = urlParams.get("app-prefill-amount");
    const paymentMethod = urlParams.get("app-prefill-payment-method");

    if (amount) {
      // Set passed amount as only one value in the list of possible amounts,
      // disable custom amount
      api.extendConfig({
        amounts: [amount],
        allowCustomAmount: false,
      });
      // Select it
      api.paymentForm.setAmount(amount);
    } else {
      // If it's not passed, clear the list and enable custom amount
      api.extendConfig({
        amounts: [],
        allowCustomAmount: true,
      });
    }

    // if payment method is passed, select it
    if (paymentMethod) {
      api.paymentForm.setPaymentMethod(paymentMethod);
    }
  });

  // If some of supporter fields is present in query parameters:
  // - show "payment_profile_short" block
  // - forcibly hide this field in "payment_profile" and "payment_address" blocks
  window.rnw.tamaro.events.afterCreate.subscribe((event) => {
    const api = event.data.api;
    const urlParams = new URLSearchParams(window.location.search);

    const fields = [
      "stored_customer_raw_name",
      "stored_customer_salutation",
      "stored_customer_firstname",
      "stored_customer_lastname",
      "stored_customer_raw_address",
      "stored_customer_street",
      "stored_customer_street_number",
      "stored_customer_street2",
      "stored_customer_zip_code",
      "stored_customer_city",
      "stored_customer_country",
    ];

    fields.forEach((field) => {
      const param = urlParams.get(`rnw-${field}`);

      if (param) {
        api.extendConfig({
          showBlocks: {
            payment_profile_short: true,
          },
          // overrule Tamaro default bahavior
          forceShowFields: {
            [field]: false,
          },
          showBlockHeaders: {
            payment_profile: false,
            payment_address: false,
          },
        });
      }
    });
  });

  // Initialize widget
  window.rnw.tamaro.runWidget(".root", {
    // Hide all fields by default
    showFields: {
      stored_is_company_donation: false,
      stored_customer_company: false,
      stored_customer_salutation: false,
      stored_customer_firstname: false,
      stored_customer_lastname: false,
      stored_customer_raw_name: false,
      stored_customer_phone: false,
      stored_customer_email: false,
      stored_customer_birthdate: false,
      stored_customer_pan: false,
      stored_customer_email_permission: false,
      stored_customer_message: false,
      stored_customer_donation_receipt: false,
      stored_customer_street: false,
      stored_customer_street_number: false,
      stored_customer_street2: false,
      stored_customer_pobox: false,
      stored_customer_zip_code: false,
      stored_customer_city: false,
      stored_customer_country: false,
      stored_customer_state: false,
      stored_customer_raw_address: false,
      bic: false,
    },
    // Hide all blocks except "payment_amounts_and_intervals" and "payment_payment_methods"
    showBlocks: {
      payment_purposes: false,
      payment_amounts_and_intervals: true,
      payment_payment_methods: true,
      payment_profile_short: false,
      payment_profile: false,
      payment_address: false,
      payment_email_permission: false,
      payment_cover_fee: false,
    },
    blocksOrder: [
      "payment_purposes",
      "payment_amounts_and_intervals",
      "payment_payment_methods",
      "payment_profile_short",
      "payment_profile",
      "payment_address",
      "payment_email_permission",
      "payment_cover_fee",
    ],
    debug: true,
    testMode: true,
  });
</script>

We recommend you also review this section on custom parameters. Also note the usage of test_mode and the debug flag in this example. These options are provided to help you test your implementation and facilitate debugging. These options must be deactivated before going to production. Production payment methods will be rejected in test_mode.

Receiving the event notification

Upon form submission you will receive an event notification according to the object created (usually payment or subscription).

The event notification will have this element:

      "custom_parameters": {
        "campaign_id": "7011i00000024uHAAQ",
        "app_record_identifier": "your-identifier",
        ...
      }

Example

Given you have queried for user data in your tablet fundraising application, you would build a link to the Tamaro widget like this (replace with your widget url):

https://tamaro.raisenow.com/futurogoal-salesforce-preprod/latest/qr-initialized-checkout.html?rnw-stored_customer_salutation=mr&rnw-stored_customer_firstname=Anton&rnw-stored_customer_lastname=Tablet&rnw-stored_customer_email=doe%40raisenow.com&rnw-stored_customer_street=Hardturmstrasse%20101&rnw-stored_customer_zip_code=8005&rnw-stored_customer_city=Zurich&rnw-stored_customer_country=CH&rnw-payment_type=recurring&rnw-recurring_interval=yearly&rnw-stored_app_record_identifier=your-identifier&app-prefill-payment-method=card&rnw-stored_campaign_id=7011i00000024uHAAQ&rnw-amount=90&app-prefill-amount=90

And you have included this string in a QR code like this:

Scanning this qr code will direct you to this Tamaro widget, with prefilled values.

Upon submission of a new subscription, and given that you have registered an endpoint and a corresponding event subscription, you will receive a confirmation of the successfully created subscription, containing your specified app_record_identifier. You can use this to trigger a confirmation for your face-to-face fundraiser on your device.