@raisenow/tamaro-core v2.8.3

Introduction

Tamaro consists of several parts, which reside on different repositories:

• Tamaro Core
• Tamaro customer configurations
• Tamaro CLI

This document describes Tamaro Core configuration options and features.

Concepts

Hence, Tamaro is quite complex and flexible, below is a brief description of the various concepts that are being used for Tamaro configuration.

Conditionals

Conditionals allow us to write configuration that changes based on various factors. For example, if payment methods is VISA, show the card block. To achieve something like that, you have to write a conditional. There are many different config keys that support conditionals. A conditional can either be a value of any kind - a simple value without a condition, or the same value wrapped into a if, then structure – a value inside a condition.

Amounts without a condition:

# config.yml

amounts:
  - 5
  - 10
  - 50
  - 100

Amounts with a condition:

# config.yml

amounts:
  - if: currency() == chf
    then:
      - 5
      - 10
      - 50
      - 100
  - if: currency() == usd
    then:
      - 10
      - 20
      - 100
      - 200

In the example above, we want different amounts to be displayed depending on chosen currency.

A condition usually consists of operators and methods. The > token is an operator. There are many operators that you're already used to and some that might be new to you. New operators can easily be added to the "Parser" class. Besides operators, there are methods. The currency() expression is a method. Methods are simple functions that may, or may not, take arguments and return a value. New methods can easily be added like this:

window.rnw.tamaro.instance.parser.addMethods({
  date: () => new Date().toLocaleString()
})

You might write conditions either in traditional or functional format, for example, traditional: 1 < 2 and 3 > 2, functional: and(lt(1, 2), gt(3, 2)).

List of available operators:

List of available methods:

Note: This list might be outdated, you can find an up-to-date list of operators and methods in debug tools (console):

window.rnw.tamaro.instance.parser.methods

Events

The full list of available events are:

beforeLoad
afterLoad

beforeCreate
afterCreate

beforeRender
afterRender

fetchPaymentDataStart
fetchPaymentDataEnd

purposeChanged
amountChanged
currencyChanged
paymentTypeChanged
recurringIntervalChanged
paymentMethodChanged

beforePaymentValidateAndSend
beforePaymentValidate
afterPaymentValidate
paymentValidateSuccess
paymentValidateError

beforePaymentSend
paymentComplete

subscriptionUpdateComplete
subscriptionCancelled

To subscribe to an event you should call subscribe method of that one, passing a callback function as below:

function callbackPurposeChanged(event) {
  console.log('The purpose was changed!')
}

window.rnw.tamaro.events.purposeChanged.subscribe(callbackPurposeChanged)

Subscribe to all events:

for (let eventName of Object.keys(rnw.tamaro.events)) {
  window.rnw.tamaro.events[eventName].subscribe((event) => {
    console.log(event.eventName, event.data)
  })
}

All event handlers receive event object as an argument with eventName and data properties. data property is an object that contains widget instance API object under api property for ell events except beforeLoad, afterLoad, beforeCreate.

Calling subscribe function will return new function that allows you to unsubscribe from this event.

Example:

let unsubscribe = window.rnw.tamaro.events.purposeChanged.subscribe(callbackPurposeChanged)
unsubscribe()

Slots

Slots is a concept used in Tamaro that allows views to be extended with additional components. A slot is basically a placeholder that can be filled with an arbitrary component. Slots are identified by names. Check out debug tools for additional slot debugging helpers.

Configuration

Tamaro can be configured using different ways:

• during build process
• in runtime

Configuration during build process

If you want customizations to be included into the bundle, you need to apply them during build process.

For more information how to build widget custom configurations, please checkout documentation in Tamaro configurations repository.

In example below:

• configurations are applied from custom YAML file
• styles are overridden in separate scss file
• widgetPreloader instance is exposed to window as window.rnw.tamaro global variable

// widget.tsx

import {set} from 'lodash'
import {createWidgetPreloader} from 'lib/WidgetPreloader'

const widgetPreloader = createWidgetPreloader({
  resolvers: {
    config: () => import('./config.yml'),
    styles: () => import('./styles/widget.scss'),
    translations: (language) => import(`./translations/${language}.yml`),
  },
})

// EXPOSE_VAR is set to 'rnw.tamaro' by default
set(window, process.env.EXPOSE_VAR!, widgetPreloader)

IMPORTANT: It's recommended to use snake case for configuration options in YAML files and use camel case in runtime configuration. For example:

• use recurring_intervals in YAML
• use recurringIntervals in runtime.

Configuration in runtime

You can specify config object during widget initialization:

<!--index.html-->

<div id="root"></div>
<script>
  window.rnw.tamaro.runWidget('#root', {
    debug: false,
    language: 'de',
  })
</script>

You can override config values later by using the widget instance. For example:

window.rnw.tamaro.instance.config.debug = true
window.rnw.tamaro.instance.config.language = 'en'

You can also extend the widget configuration in event handlers, using the extendConfig helper method.

If the passed configuration option value is a plain object, it's merged with its target value. Otherwise (if the passed configuration option value is bool, string, number, array, etc.), its target value is overridden by passed value.

Example:

// widget.tsx

import {set} from 'lodash'
import {createWidgetPreloader} from 'lib/WidgetPreloader'

const widgetPreloader = createWidgetPreloader()

widgetPreloader.events.afterCreate.subscribe((event) => {
  const api = event.data.api

  api.extendConfig({
    // bool, string and array values override its target values
    debug: false,
    language: 'de',
    amounts: [5, 10, 20, 50],
    purposes: ['p1', 'p2'],
    paymentMethods: ['cc', 'pp'],
    // plain object value is deeply merged with its target value
    translations: {
      de: {
        purposes: {
          p1: 'Purpose 1',
          p2: 'Purpose 2',
        },
      },
    },
  })
})

// EXPOSE_VAR is set to 'rnw.tamaro' by default
set(window, process.env.EXPOSE_VAR!, widgetPreloader)

Since the config object is reactive, whenever a value changes, the widget will update its user interface if necessary.

It is fine to combine these configuration options. For example, you might want to use YAML to set translations and some defaults, use JavaScript to set some landing-page specific configuration, and use a runtime configuration as reaction to certain events. No matter what configuration formats you've used, the widget will merge them all together using the priority Runtime > Customer's YML > Tamaro Defaults and create a new configuration object based on it.

Configuration options

Available configuration options are:

E-mail configuration

This section lists the configuration option for the EPMS e-mail service that sends transactional e-mails. The configuration files for e-mails reside in the email-config directory of every Tamaro configuration.

The configuration is deployed with npx -y @raisenow/tamaro-cli deploy-email-config both for prod and stage environments. When you run this command, you will be prompted for both AWS profile and environment.

Make sure selected AWS profile has proper permissions to access the desired environment. Deploying to stage using prod profile and vice versa will end up with the error in the console.

In case you don't have properly configured AWS SSO Enabled profiles, please read the article in the Wiki describing the steps how to get AWS SSO Enabled Profiles.

E-mails are sent over the service if it is set as a webhook endpoint for the organisation. In other words, organisations have to activate e-mails in the "Settings" section in their Hub account.

Parameters

The organisation's name should be set as parameter in the file email-config/parameters.yaml. Optionally, you can specify the organisation's e-mail address.

It is also possible to define an address to which a blind copy of the e-mail is sent. The e-mail is also sent to the blind-copy address if no supporter e-mail address is specified.

The parameters can be set per language, with a fallback (all).

all:
  organisation_name: ICRC
  organisation_email: info@icrc.org
  blind_copy: transactions@icrc.org
de:
  organisation_name: IKRK

Templates

To define the texts used in the e-mails body and subject, you can create files of the form templates/{lang}/{scenario}.hbs or templates/{lang}/{scenario}.subject.hbs, respectively.

There are the following scenarios available:

• transaction for successful one-time payments
• subscription-activated for when a subscription becomes active
• subscription-cancelled for when a subscription is cancelled
• subscription-charged for successful charges of subscriptions

The templates support Markdown and Handlebars syntax. Parameters must be set in double curly brackets.

Example

{{greeting}},

You have donated **{{amount}}**
{{payment_method_preposition}} {{payment_method}}.

{{#if additional_information}}
Additionally, you left the following information.
{{#each additional_information}}

**{{this.description}}**
{{this.content}}
{{/each}}
{{/if}}

{{#if custom_parameters.some_custom_identifier}}
Some custom identifier: {{custom_parameters.some_custom_identifier}}
{{/if}}

{{#if supporter.email_permission}}
You asked to receive news from us on {{supporter.email}}.
You can unsubscribe at any time.
{{/if}}

Thank you for your donation,
{{organisation.name}}

Legacy e-mail service

There is also a legacy e-mail service that covers EPP and EPMS. It is still in use, but what was never documented. The legacy e-mail service's configuration files are named email-parameters.yaml and translations.{lang}.yaml. The EPMS e-mail service can read certain information from the legacy configuration (like the organisation name, organisation e-mail, and blind-copy address), but not the e-mail texts.

Examples

Debug and test mode

When working locally or testing the widget, you may want to enable the debug mode:

# config.yml

debug: true

You can also enable debug mode by adding #widgetdebug to the url. This enables debug tools at the bottom of the widget with various useful helpers and inspection views. Alternatively you may also add a query parameter ?widgetdebug to achieve the same effect.

You must disable test mode in order to produce production payments:

# config.yml

test_mode: false

Debug options

To facilitate debugging of data you can set these options:

# config.yml

debug_error_messages: true
debug_slots: true

Specify language

Change widget language.

Default value is 'en'.

# config.yml

language: de

Specify fallback language

This language will be used for case, which don't have translations.

Default value is 'en'.

# config.yml

fallback_language: de

Flows

There are two flows available: EPP (legacy e-payment platform, flow: epp) and EPMS (e-payment micro-services, flow: epms). It defines which backend to use in case a payment method is supported on either of them. The default is EPP.

Field mappings for EPMS flow

You can add custom fields to the payment object. In case the EPP flow is used, the common approach is to use field names with a stored_ or stored_customer_ prefix. You can still use the same naming convention with the EPMS flow, but be aware that fields will be automatically remapped according to the rules below.

To choose the correct custom field names for the EPMS flow, please check out RaiseNow's ontology.

Main supporter fields

stored_customer_birthdate should have YYYY-MM-DD format.

Supporter metadata fields

Raisenow integration fields

Supporter raisenow parameters fields

Additionaly to supporter.email_permission the following is also set:

Raisenow product fields

These 4 fields are automatically injected by Tamaro, you cannot override them.

Custom parameters fields

Providing translations

In order to provide translation customisations, simply add them in dedicated files under "translations" folder:

# translations/en.yml

purposes:
  p1: Purpose 1
  p2: Purpose 2

# translations/de.yml

purposes:
  p1: Zweck 1
  p2: Zweck 2

When providing translations trough JavaScript, translations node is inside the config object and a language key has to be used:

<!--index.html-->

<div id="root"></div>
<script>
  window.rnw.tamaro.runWidget('#root', {
    debug: true,
    translations: {
      en: {
        purposes: {
          p1: 'Purpose 1',
          p2: 'Purpose 2',
        },
      },
      de: {
        purposes: {
          p1: 'Zweck 1',
          p2: 'Zweck 2',
        },
      },
    },
  })
</script>

You can use conditions for all available translation keys if needed. Only the first one value, that matches the condition, will be returned.

# translations/en.yml

purposes:
  p1:
    - if: amount() == 5
      then: Purpose 1 when amount is 5
    - if: amount() == 10
      then: Purpose 1 when amount is 10
    - Default purpose 1

Interpolated translations

You can put any of the supported methods and expressions by the conditionals parser, into a translation by using the %% around the expression, for example:

# translations/en.yml

title: 'Selected %% totalAmount() %% %% currency() %%'

The translated expression above would result in something like Selected 5 chf

You can reference other translations like this:

# translations/en.yml

title: 'Translated key currencies.chf: %% trans(currencies.chf) %%'

This would result in Translated key currencies.chf: Swiss Francs

Configuring blocks

You can configure a list of blocks for payment widget. Specify payment widget blocks like this:

# config.yml

show_blocks:
  payment_purposes: true
  payment_amounts_and_intervals: true
  payment_payment_methods: true
  payment_profile: true
  payment_address: true

There can be circumstances when Tamaro will ignore the value specified in this config option for certain blocks because it's required for the transaction to be successful. For example, file-based Sepa direct debits require the address fields and if this payment method is selected, Tamaro will automatically render "payment_address" block with all required address fields, skipping showBlocks.payment_address: false config option value.

You can use forceShowBlocks config option to overrule this default Tamaro behavior, but in this case you MUST be sure to set all required fields by yourself.

You can reorder blocks. The following option only sets the order, but doesn't show/hide them.

# config.yml

blocks_order:
  - payment_purposes
  - payment_amounts_and_intervals
  - payment_payment_methods
  - payment_profile
  - payment_profile_short
  - payment_address
  - payment_email_permission
  - payment_cover_fee
  - payment_sepa_mandate_terms

You can specify whether block header should be shown/hidden:

# config.yml

show_block_headers:
  payment_payment_methods: false
  slot_info: false

The legacy configuration option payment_widget_blocks is still supported, but deprecated.

Show / hide standard form fields

Fields can be shown and hidden by specifying the following options (shown are the defaults):

# config.yml

show_fields:
  stored_is_company_donation: false
  stored_customer_company: false
  stored_customer_salutation: true
  stored_customer_firstname: true
  stored_customer_lastname: true
  stored_customer_raw_name: false
  stored_customer_phone: false
  stored_customer_email: true
  stored_customer_birthdate: true
  stored_customer_pan: false
  stored_customer_email_permission: true
  stored_customer_message: true
  stored_customer_donation_receipt: true
  stored_customer_street: true
  stored_customer_street_number: true
  stored_customer_street2: true
  stored_customer_pobox: false
  stored_customer_zip_code: true
  stored_customer_city: true
  stored_customer_country: true
  stored_customer_state: true
  stored_customer_raw_address: false
  bic: false

You also can use conditions for these options. Example:

# config.yml

show_fields:
  stored_customer_pobox:
    - if: paymentForm(stored_customer_country) == CH
      then: true
      else: false

There can be circumstances when Tamaro will ignore the value specified in this config option for certain fields because it's required for the transaction to be successful. For example, file-based Sepa direct debits require the address fields and if this payment method is selected, Tamaro will automatically render "payment_address" block with all required address fields, skipping showFields.stored_customer_street: false and similar config option values.

You can use forceShowFields config option to overrule this default Tamaro behavior, but in this case you MUST be sure to set all required fields by yourself.

The legacy configuration option show_{fieldname} is still supported, but deprecated.

If a field is hidden, then its validations are skipped.

Required fields

Depending of different conditions, Tamaro automatically shows some blocks and fields, ignoring the values specified in showBlocks and showFields config options for these fields, and also makes them required.

This may be overruled by forceShowBlocks, forceShowFields and forceFaymentValidations config options, but if you use these config options, you MUST be sure to set all required fields by yourself.

Current main rules

• If payment type is recurring:

  • email is required

• If payment method is card:

  • first_name is required
  • last_name is required

• If payment method is sepa_dd:

  • email is required
  • first_name is required
  • last_name is required
  • if IBAN country is not in EEA (or equals to "FR"):
    • street is required
    • zip_code is required
    • city is required
    • country is required
    • state is required (if states are defined for selected country)

• If stored_email_permission checkbox is checked:

  • email is required

• If stored_is_company_donation checkbox is checked:

  • stored_customer_company is required

• If donation receipt checkbox is checked and if donationReceiptRequiresFields config options is enabled (enabled by default):

  • If organisationCountryCode is "CH" or "DE":
    • first_name is required
    • last_name is required
    • street is required
    • street_number is required
    • zip_code is required
    • city is required
    • country is required
    • state is required (if states are defined for selected country)
  • If organisationCountryCode is "AT":
    • first_name is required
    • last_name is required
    • birthdate is required
  • If organisationCountryCode is other or not specified:
    • first_name is required
    • last_name is required
    • street is required
    • zip_code is required
    • city is required
    • country is required
    • state is required (if states are defined for selected country)

Only submit visible standard fields

If the configuration option onlySubmitVisibleStandardFields is set to true, then prefilled standard fields will only be submitted if they are visible to the supporter.

Default value is false.

# config.yml

only_submit_visible_standard_fields: true

Prefill payment form

You can prefill the payment form by setting the fields that you want to be prefilled trough config:

# config.yml

payment_form_prefill:
  stored_customer_firstname: John
  stored_customer_lastname: Doe
  purpose: p2
  payment_type: recurring
  recurring_interval: monthly
  currency: EUR
  amount: 10
  payment_method: card

EPP config

You can define options separately for "stage" and "prod" EPP environments and specify the environment itself using eppEnv config option.

There is a section "Debug → EPP/EPMS configs", where you can:

• Switch eppEnv config option value for testing purposes.
• Explore resolved EPP config (also accessible in the browser console as rnw.tamaro.instance.eppConfig)

Switching eppEnv config option value:

• If set to "stage":
  • eppStage config option is used to resolve apiKey, merchantId, successUrl, errorUrl, cancelUrl and immediateExecution.
  • testMode forcibly resolves as true.
• If set to "prod":
  • epp config option is used to resolve apiKey, merchantId, successUrl, errorUrl, cancelUrl and immediateExecution.
  • testMode resolves as value specified in the root level of config (either true or false).

It's possible to use conditions for all EPP properties in epp and eppStage config options: apiKey, merchantId, successUrl, errorUrl, cancelUrl and immediateExecution.

Please note that snake case is used in config.yml file instead of camel case for config options names and their properties. It's technically possible to use both cases, but it's highly recommended to not mix them and stick to the snake case in YML config files for consistency and readability.

# config.yml

test_mode: false
epp_env: prod
epp:
  api_key: epp-prod-api-key
  merchant_id: epp-prod-merchant-id
  success_url: https://example.com?success=1&prod=1
  error_url: https://example.com?error=1&prod=1
  cancel_url: https://example.com?cancel=1&prod=1
  immediate_execution: false
epp_stage:
  api_key:
    - if: paymentMethod() == chqr
      then: epp-stage-api-key-1
      else: epp-stage-api-key-2
  merchant_id:
    - if: paymentMethod() == chqr
      then: epp-stage-merchant-id-1
      else: epp-stage-merchant-id-2
  success_url: https://example.com?success=1&stage=1
  error_url: https://example.com?error=1&stage=1
  cancel_url: https://example.com?cancel=1&stage=1
  immediate_execution: false

Default values, if not explicitly specified, are:

# config.yml

epp_env: prod
epp:
  api_key: 1234567890
  merchant_id: srk-aced5e
  immediate_execution: false

Properties successUrl, errorUrl and cancelUrl are considered deprecated and not recommended to use.

Legacy epikConfig configuration option is still supported for backwards compatibility, but considered deprecated and not recommended to use.

EPMS config

You can define options separately for "stage" and "prod" EPMS environments and specify the environment itself using epmsEnv config option.

There is a section "Debug → EPP/EPMS configs", where you can:

• Switch epmsEnv config option value for testing purposes.
• Explore resolved EPMS config (also accessible in the browser console as rnw.tamaro.instance.epmsConfig)

Switching epmsEnv config option value:

• If set to "stage":
  • epmsStage config option is used to resolve accountUuid, paymentMethodProfile, stripePublicKey and stripeAccount.
  • testMode forcibly resolves as true.
• If set to "prod":
  • epms config option is used to resolve accountUuid, paymentMethodProfile, stripePublicKey and stripeAccount.
  • testMode resolves as value specified in the root level of config (either true or false).

It's possible to use conditions:

• For EPMS properties in epms and epmsStage config options: accountUuid, stripePublicKey, stripeAccount.
• For each specific paymentMethodProfile parameter in epms and epmsStage config options.

Please note that snake case is used in config.yml file instead of camel case for config options names and their properties. It's technically possible to use both cases, but it's highly recommended to not mix them and stick to the snake case in YML config files for consistency and readability.

Example:

# config.yml

test_mode: false
epms_env: prod
epms:
  account_uuid: epms-prod-account-uuid
  payment_method_profile:
    card: epms-prod-payment-method-profile-card
    twint:
      - if: testMode() == true
        then: epms-prod-test-payment-method-profile-twint
        else: epms-prod-live-payment-method-profile-twint
    sepa_dd: epms-prod-payment-method-profile-sepa_dd
    apple_pay: epms-prod-payment-method-profile-wallet
    google_pay: epms-prod-payment-method-profile-wallet
  stripe_public_key: epms-prod-stripe-public-key
  stripe_account: epms-prod-stripe-account
epms_stage:
  account_uuid: epms-stage-account-uuid
  payment_method_profile:
    card: epms-stage-payment-method-profile-card
    twint: epms-stage-payment-method-profile-twint
    sepa_dd: epms-stage-payment-method-profile-sepa_dd
    apple_pay: epms-stage-payment-method-profile-wallet
    google_pay: epms-stage-payment-method-profile-wallet
  stripe_public_key: epms-stage-stripe-public-key
  stripe_account: epms-stage-stripe-account

Parser helper testMode() evaluates to the value specified in config on root level.

The stripePublicKey is required for wallet payments, as an alternative to using stripeAccount parameter.

Default values, if not explicitly specified, are:

# config.yml

epms_env: stage
epms_stage:
  account_uuid: d71de4f6-e466-40dc-84ce-c1ce20b29b08

Legacy epikConfig configuration option is still supported for backwards compatibility, but considered deprecated and not recommended to use.

Specify available purposes

You may define available purposes like this:

# config.yml

purposes:
  - p1
  - p2

Do not forget to add a translation for each purpose:

# translations/en.yml

purposes:
  p1: Stop the whitewalkers
  p2: Unite seven kingdoms

Specify available payment methods, types and intervals

You can limit widget to certain payment methods, types and intervals:

# config.yml

payment_methods:
  - card
  - sms
  - sepa_dd
  - apple_pay
  - google_pay
payment_types:
  - onetime
  - recurring
recurring_intervals:
  - monthly
  - quarterly
  - semestral
  - yearly

Don't forget that you can use json format also, of course if this format is more preferable for you.

<!--index.html-->

<div id="root"></div>
<script>
  window.rnw.tamaro.runWidget('#root', {
    paymentMethods: [
      'card',
      'sepa_dd',
      {
        if: 'amount() < 100',
        then: 'sms',
      },
    ],
    paymentTypes: [
      'onetime',
      'recurring'
    ],
    recurringIntervals: [
      'weekly',
      'monthly',
    ],
  })
</script>

Specify allowed card types

You can specify which card types are supported.

Default value is undefined, meaning all card types are supported.

allowed_card_types:
  - vis
  - eca
  - amx

Specify priority card types

You can specify which icons of card types should be shown first in a "Card" block header.

Default value is ['vis', 'eca', 'amx'].

#