Skip to main content

Migration guides

v2.7.0​

Following config options are considered deprecated:

  • defaultPurpose
  • defaultPaymentType
  • defaultRecurringInterval
  • defaultCurrency
  • defaultAmount
  • defaultPaymentMethod

It's not recommended to use them anymore, while they are still supported for backwards compatibility.

Now it's recommended to use paymentFormPrefill config option.

Old config example​

New config example​

v2.6.0​

New standard fields​

Several standard fields were added:

  • stored_is_company_donation
  • stored_customer_company
  • stored_customer_phone

They are hidden by default.

To show them, use the config option as in the following example:

If you want to show stored_customer_company dynamically depending on stored_is_company_donation value, it's enough to just specify stored_is_company_donation checkbox to be shown. If it's checked, stored_customer_company field will be shown automatically:

CSS variables changes​

Default values are changed for several variables.

Previous default values:

:root {
  --tamaro-text-color__inverse: var(--tamaro-bg-color);
  --tamaro-button-bg-color: var(--tamaro-bg-color);
  --tamaro-checkable-bg-color: var(--tamaro-bg-color);
}

New default values:

:root {
  --tamaro-text-color__inverse: #fff;
  --tamaro-button-bg-color: #fff;
  --tamaro-checkable-bg-color: #fff;
}

Several new CSS variables were added:

:root {
  --tamaro-dropdown-bg-color: #fff;
  --tamaro-overlay-bg-color: #fff;
  --tamaro-overlay-backdrop-bg-color: #fff;
  --tamaro-overlay-backdrop-opacity: 0.75;
  --tamaro-spinner-outer-bg-color: #fff;
  --tamaro-spinner-outer-opacity: 0.75;
}

Using slots​

To check which slots are available, click "Debug Slots" checkbox in "Debug → Main" section.

The following slots are considered legacy and not recommended to be used, while still supported for backwards compatibility:

direct_debit_form_start
direct_debit_form_1
direct_debit_form_2
direct_debit_form_end

elektronisches_lastschriftverfahren_form_start
elektronisches_lastschriftverfahren_form_end

sepa_one_form_start
sepa_one_form_1
sepa_one_form_end

sepa_dd_form_1

swiss_qr_bill_form_start
swiss_qr_bill_form_1
swiss_qr_bill_form_2
swiss_qr_bill_form_end

profile_form_1
profile_form_2
profile_form_3
profile_form_4
profile_form_5
profile_form_6
profile_form_7

address_form_1
address_form_2
address_form_3
address_form_4
address_form_5
address_form_6
address_form_7

Here are some new slots, which were added:

dd_form_start
dd_form_before_iban
dd_form_after_iban
dd_form_before_bic
dd_form_after_bic
dd_form_end

elv_form_start
elv_form_before_iban
elv_form_after_iban
elv_form_end

sod_form_start
sod_form_before_iban
sod_form_after_iban
sod_form_before_bic
sod_form_after_bic
sod_form_end

sepa_dd_form_after_iban
sepa_dd_form_before_bic

chqr_form_start
chqr_form_before_chqr_ordered
chqr_form_after_chqr_ordered
chqr_form_end

net_form_start
net_form_before_netbanking_issuer_id
net_form_after_netbanking_issuer_id
net_form_end

profile_form_before_is_company_donation
profile_form_after_is_company_donation
profile_form_before_company
profile_form_after_company
profile_form_before_salutation
profile_form_after_salutation
profile_form_before_firstname
profile_form_after_firstname
profile_form_before_lastname
profile_form_after_lastname
profile_form_before_raw_name
profile_form_after_raw_name
profile_form_before_phone
profile_form_after_phone
profile_form_before_email
profile_form_after_email
profile_form_before_birthdate
profile_form_after_birthdate
profile_form_before_pan
profile_form_after_pan
profile_form_before_email_permission
profile_form_after_email_permission
profile_form_before_message
profile_form_after_message
profile_form_before_donation_receipt
profile_form_after_donation_receipt

address_form_before_street
address_form_after_street
address_form_before_street_number
address_form_after_street_number
address_form_before_street2
address_form_after_street2
address_form_before_pobox
address_form_after_pobox
address_form_before_zip_code
address_form_after_zip_code
address_form_before_city
address_form_after_city
address_form_before_country
address_form_after_country
address_form_before_state
address_form_after_state
address_form_before_raw_address
address_form_after_raw_address

v2.5.0​

Extend validations​

Here are default Tamaro validation rules.
All custom validation rules, specified in runtime config, are merged with default rules, so this config should not be copy-pasted.
It's here just for reference, so you can clearly understand which exact rules Tamaro applies by default:

Since v2.5.0 validations are applied only to shown fields.
It means in the most of the cases you don't need to modify validation rules at all – everything should work correctly out of the box.
For example if payment_address block is hidden, all validations for address-related fields are just ignored, the same applies for all other fields.

If you have redefined paymentValidations config option, please check it – if you see that validations for some particular fields are the same, as specified above, it's recommended to remove them since they are not needed anymore, and they just bloat the config.

If you want to modify existing validations for some of the fields (for example make stored_customer_birthdate not required and make stored_customer_street_number required), you don't need to copy-paste all validation rules as was done before – you just need to specify what's different comparing to default validation rules.

New config example​

Allowed card types​

Previously you used a mix of payment methods and card types in a paymentMethods config option.
This way it was possible to limit which card types are supported.

Old config example​

If all available card types should be supported, you used special meta-value cc for that.
When we implemented card payments for EPMS, we added another meta-value card, which works the same as cc.

But this mixing of payment methods and card types is error-prone and complex to manage.

Since Tamaro v2.5.0, we changed the approach, but preserved the old one for backwards compatibility.

Since now on for both EPP and EPMS, it's recommended to always use card as a payment method in paymentMethods config option.
The correct detected card type is set in a payment object automatically for EPP payments.

If cc value is used in a paymentMethods config option, its value is rewritten as card under the hood.
Calling rnw.tamaro.instance.paymentForm.getPaymentMethod() always returns card now.

If you need to limit which card types are supported, there is a new config option allowedCardTypes.

New config example​

You can still use the old approach, it's backwards compatible, but it's not recommended to do so.

Flow with conditions​

In previous Tamaro versions when payment method was set to cc and when you selected card payment method and then started to type card number, it detected card type and set this value as a payment method (vis, eca, amx etc.), which led condition, which is used in the flow config option, to be re-evaluated, and Card form to be re-rendered.

This is fixed in v2.5.0, starting from which it's recommended to use the following approach (if you need to specify flow with conditions):

1. If both twint and card payment methods should use EPMS:​

2. If twint should use EPMS, but card should use EPP:​

3. If twint should use EPP, but card should use EPMS:​

4. If both twint and card should use EPP:​

Always use those payment methods in the flow condition, which should use EPMS (not vice versa!) because:

  • If later some new payment method (like pp) will start supporting EPMS, then automatically resolved updated Tamaro version will not break anything, existing condition will still work exactly the same – if pp is selected, flow will be resolved as "epp". If your condition uses the opposite approach (with else: epms statement) and you forgot to explicitly mention pp in your condition, then flow will be resolved as "epms", which is NOT what you want and you config will be BROKEN right away without making any changes to it.
  • We have less available payment methods, which support EPMS at the moment, so your conditions will be simpler and shorter.

EPP/EPMS configs​

Parameters from epikConfig option of Tamaro are moved to separate epp, eppStage, epms, epmsStage config options, which allows to specify different parameters for each EPP and EPMS environment separately.

It's not necessary to specify parameters for all environment – specify only for these environments, which are used by customer.

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

  • Switch eppEnv and epmsEnv config options values.
  • Explore resolved EPP/EPMS configs.
    These computed getters also accessible in the browser console as rnw.tamaro.instance.eppConfig and rnw.tamaro.instance.epmsConfig.
    The old one rnw.tamaro.instance.epik.config is also available for backwards compatibility.

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).

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).

Now 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.
  • For all EPP properties in epp and eppStage config options: apiKey, merchantId, successUrl, errorUrl, cancelUrl and immediateExecution.

Config options are moved as follows:

  • Generic:
    • epikConfig.skipCvv moved to skipCvv.
    • epikConfig.paymentStatusPollInterval moved to paymentStatusPollInterval.
  • EPP-related:
    • epikConfig.eppEnv moved to eppEnv.
    • epikConfig.eppApiKey moved to epp.apiKey and eppStage.apiKey.
    • epikConfig.eppMerchantId moved to epp.merchantId and eppStage.merchantId.
    • epikConfig.successUrl moved to epp.successUrl and eppStage.successUrl (considered legacy, not recommended to use).
    • epikConfig.errorUrl moved to epp.errorUrl and eppStage.errorUrl (considered legacy, not recommended to use).
    • epikConfig.cancelUrl moved to epp.cancelUrl and eppStage.cancelUrl (considered legacy, not recommended to use).
    • immediateExecution moved to epp.immediateExecution and eppStage.immediateExecution. Old config option is still supported for backwards compatibility.
  • EPMS-related:
    • epikConfig.epmsEnv moved to epmsEnv.
    • epikConfig.epmsAccountUuid moved to epms.accountUuid and epmsStage.accountUuid.
    • epikConfig.paymentMethodProfile moved to epms.paymentMethodProfile and epmsStage.paymentMethodProfile.
    • epikConfig.stripePublicKey moved to epms.stripePublicKey and epmsStage.stripePublicKey.
    • stripeAccount moved from root level to epms.stripeAccount and epmsStage.stripeAccount. Old config option is still supported for backwards compatibility.
  • Legacy epikConfig option is still supported for backwards compatibility, but not recommended to use.

Old config example​

New config example​

Default values, if not explicitly specified, are:

Placing default fields in different places​

If customer wants to place default fields ("profile" or "address" fields) in different places (slots or custom slot blocks), it can be achieved by:

  • configuring default payment_profile and payment_address blocks to not be shown
  • using custom fields to render fields in slots

This setup is kinda fragile and recommended to be avoided if possible because Tamaro has its own rules, when "profile" and "address" fields are shown and required depending on for example selected payment method or other conditions.

In such case, if all required fields are rendered in slots, then all good – blocks, where these fields should be rendered by default (payment_profile and payment_address blocks) will not be rendered.

But if you forgot to configure some of such required fields to be rendered in a slot along with other fields, then such field anyway will be rendered (because it's required by Tamaro), but it will be rendered in its default place – payment_profile or payment_address block respectively, which is NOT what you want.

To avoid such situation, if you are moving default Tamaro fields to custom slots, always move all the following fields:

  • If you're moving any of the following "profile" fields, move all these 3 fields:
    • stored_customer_firstname
    • stored_customer_lastname
    • stored_customer_email
  • If you're moving any of the following "address" fields, move all these 5 fields:
    • stored_customer_street
    • stored_customer_zip_code
    • stored_customer_city
    • stored_customer_country
    • stored_customer_state

It was hard to do in previous Tamaro versions because defining "countries" and "states" fields in a slot required defining dropdown options for these custom fields.
It was done with pretty complex custom code in customer configuration, but now it's simplified – since v2.5.0 we added additional custom fields types, which don't require defining dropdown options, Tamaro provides dropdown options for these custom field types out of the box:

  • select-salutations
  • select-countries
  • select-states

If you use default fields names for these fields (like stored_customer_country etc.), you don't need to define label and placeholder properties for these fields – existing default translations will be picked up for them.

But if you're adding custom fields with different names (like for example stored_recipient_country), then providing label and placeholder translation keys is needed because Tamaro doesn't have translation for the fields with such names.

Custom field with select-states type is country-specific – it depends on selected country and is rendered only in case states are defined for this country.
At the moment we have defined states only for the following 4 countries: US, CA, CL, AR.

By default, custom field with select-states type depends on stored_customer_country field, if you need it to depend on some other field (like for example stored_recipient_country), you need to explicitly specify it with countryFieldName: stored_customer_country property (see relevant commented line in the example below).

You should also skip adding label and placeholder keys for select-states field type – it uses default translations because the logic behind selecting proper translation key is country-specific – for some countries it's "State", for some it's "Region", for some it's "Province" etc.

New config example​

v2.2.0​

Show/hide blocks​

When you want some block to be shown/hidden (for example payment_purposes block to be hidden and payment_cover_fee to be shown), the old approach was to specify the following option:

Old config example​

The config option above is considered deprecated (while it's still supported for backwards compatibility).

It's highly recommended to use the new simpler approach – remove old option and specify the following instead:

New config example (1)​

You don't need to explicitly mention all the blocks – you just need to specify what should be different from default config.

Blocks, which are shown by default, are:

  • payment_payment_purposes
  • payment_amounts_and_intervals
  • payment_payment_methods
  • payment_profile

Please note that payment_address block is not shown by default – Tamaro will automatically show it if address fields are required for selected payment method, there is no need to configure it explicitly anymore.

If customer wants payment_address block to be shown for certain payment methods (for example for card payment method), you can specify it as follows:

New config example (2)​

Show/hide fields​

Previously you were using the following separate config options for specifying which fields should be shown/hidden:

Old config example​

Now these config options are considered deprecated and not recommended to use.
It's recommended to use single option instead – showFields.

New config example (1)​

Each field here can be specified with condition:

New config example (2)​