Configuration and Extension Points

The CoreWallet can be configured and extended for Product-specific requirements. This section describes significant configuration and extension points.

Wallet ProductConfiguration

The Wallet component has a configuration-interface ProductConfiguration which defines several behaviors in Wallet processes. Instances are accessed via the ProductConfigurationProvider.getProductConfiguration() which allows to provide a specific configuration per subsidiary.

Example behaviors configured through the ProductConfiguration in the Wallet module:

  • The brand name
  • The lead-currency (per default EUR)
  • The supported country codes for user registration
  • The currencies for initial wallet-accounts for user-registration per country
  • The supported currencies for transactions
  • The supported currencies for wallet-accounts
  • The email configuration (which emails are supported)
  • The sms configuration (which SMS are supported)
  • The default payment-category-code per payment-type/currency/country
  • The deposit-configuration per deposit-type (e.g. for risk-deposits)
  • The payment-approval-configuration per payment-type and amount
  • The default subsidiary-id per country for user registration
  • The purchase-process-configuration
  • The required user-identifiers for user registration (e.g. Email and/or PhoneNumber)
  • The voucher-based-P2P-configuration
  • The payment-instrument-configuration to determine which payment-instrument-types are allowed for certain processes
  • The one-time-password-configuration for 2-factor-authentication checks in P2P and payment processes
  • The password-validator
  • Whether or not certain limits apply for an Admin security-context

Wallet SubsdiaryResolver

The Wallet component provides a WalletSubsidiaryResolver to customize the mapping for a country-code to subsidiary-id for a user-registration.

Wallet LoginProcess

The Wallet component provides a WalletLoginProcess to customize the login process, especially as what should happen before and after a login.

ExternalAuthenticationServiceProvider

The ExternalAuthenticationServiceProvider interface can be used to return a collection of ExternalAuthenticationService implementations that provide integration with e.g. Facebook, LinkedIn, etc for the login/registration-process.

User ProductConfiguration

The User component also provides a ProductConfiguration to customize certain behaviors. Instances are accessed via the ProductConfigurationProvider.getProductConfiguration() which allows to provide a specific configuration per subsidiary and country.

Example behaviors are:

  • Minimum/maximum number of user addresses, phone-numbers, email-addresses, id-documents
  • User-data-update configuration
  • Which user-data is required
  • Which user-roles are allowed (e.g. to prevent accidentally giving a user the SYSTEM role)
  • Minimum/maximum user age
  • The supported user-verification-levels (for KYC)

WalletAccountingConfiguration

The WalletAccountConfiguration defines emoney-relevant behavior for the Wallet component. Instances are accessed via WalletAccountingConfigurationProvider.getConfiguration() which allows to override the configuration in a product.

Example configurations are:

  • Available currencies (both FIAT and virtual)
  • Wallet-account configuration per currency
    • Which are automatically created
    • Which are considered for balance calculation
    • Which is used per transaction-type
  • Transfer-type configuration per transaction-type
    • Which transfers are allowed
  • Emoney-type configuration
    • Which emoney-types are available
    • In what context can an emoney-type be used
    • In what context will an emoney-type be created
  • Inter-subsidiary account-type configuration per transaction-type
    • Which inter-subsidiary transfers are allowed
  • Various system-account-type configurations

Payment Gateways

The AbstractPaymentGatewayAdapter is the typical base-class for a PaymentGateway, that provides the extension point from the Payment module to a particular gateway, implemented in a product.

The PaymentGateway can implement the methods it supports, and will then be called once applicable (depending on BusinessContract, PaymentMethod and BusinessContractRoute configurations in the database). The following methods are currently available for a PaymentGateway:

  • preauthorize
  • reverse
  • refund
  • capture
  • authorize
  • credit

Typically the gateway implementation delegates to a service that provides all logic for the payment-method, e.g. including file generation, callback processing, administration API.

Session Payment Method Strategy

The AbstractSessionPaymentMethodStrategy is the typical base-class for a strategy that defines how a certain payment-method will appear and interact in a payment-session.

The following methods must be implemented (though some can be left with no implementation, depending on the actual needs):

  • isApplicable to allow for additional preconditions before allowing this payment-method in the payment-session
  • prepareSession to setup the payment-session for this payment-method
    • provide applicable session-payment-instruments (e.g. based on the payment-instruments retrieved from the user, or generated by the system)
  • mergeSession is used to update the payment-session based on the user-input
    • validate entered user data applicable for this payment-method
    • create new payment-instrument if needed
    • create new session-payment-instrument if needed
    • adjust selection for payment-method / payment-instrument
  • derivePaymentInstrumentForCopy can be used to take over session-payment-instruments from a previous payment-session
  • onSessionDataUpdated can be used to react to changed session-data
  • toApiSessionPaymentMethod is used to generate a public representation of the session-payment-method
    • define the required-input-fields for new payment-methods
    • define the payment-instruments and what data is provided

EmailSendService

The EmailSendService interface must be implemented to provide the actual email-templating and sending, e.g. via a direct SMTP-implementation, or by integrating an external service such as Mandrill.

For convenience and quick start for new projects, CoreWallet offers a Mailgun implementation of the EmailSendService. It can be used as a bean with ID integrations.MailgunEmailSendService. Configuration can be done through the following parameters, all prefixed by trimplement.wallet.server.common.email.mailgun:

subdomain

the configured or sandbox domain from Mailgun

apikey

the API key provided by Mailgun, usually in the format key-...

from

the sender of the email, as displayed in the from field

to

the recipient of the test emails for third-party-tests

subdomain and apikey need to be provided by the customer by creating an account at https://www.mailgun.com.

The MailgunEmailSendService comes preconfigured with a Thymeleaf template strategy. Without any configuration, Thymeleaf templates can be stored in the classpath in a folder named META-INF/templates/email. Below this we need folders with ISO 639-2 language codes (like de for German or en for English), separating templates per language. Within each language folder, we use the EmailId as the filename with extension .html (e.g. for EmailId.RESETPASSWORD we have resetpassword.html and resetpassword_subject.html for the subject line of the email).

To use custom template names, you can configure a ConditionalIdMapping in com.trimplement.wallet.server.common.product.dom.ProductConfiguration, mapping an EmailId to the stored template’s name. The condition-part of the ConditionalIdMapping is currently not used.

More template strategies can be created by implementing the TemplateStrategy interface and replacing the templateStrategy property in the MailgunEmailSendService bean.

SmsSendService

The SmsSendService interface must be implemented to provide the actual SMS-templating and sending, e.g. by integrating an external service such as Twilio.

An implementation of the SmsSendService can use a TemplateStrategy implementation for parameterized multi-language texts. It can also map between IDs with  the ConditionalIdMapping as described for the EmailSendService above.

For convenience and quick start for new projects, CoreWallet offers two implementations of the SmsSendService:

SureSMS

The implementation for SureSMS can be used as a bean with ID integrations.SureSmsSendService. Configuration can be done through the following parameters, all prefixed by trimplement.wallet.server.common.sms.suresms

url

the send endpoint, currently https://api.suresms.com/Script/SendSMS.aspx

username

the name of the registered user at SureSMS

password

the matching password for the user

from

the sender's name, as displayed in the SMS

to

an optional parameter, used in third-party-tests for the recipient phone number of the test-SMS

username and password need to be provided by the customer by creating an account at https://www.suresms.com/en.

The SureSmsSendService comes preconfigured with a simple replacement template strategy.

Twilio

The implementation for Twilio can be used as a bean with ID common.TwilioSmsSendService. Configuration can be done through the following parameters, all prefixed by trimplement.wallet.server.common.sms.twilio

apiUrl

the send endpoint, it may contain placeholders for SID and token, e.g. https://%s:%s@api.twilio.com/2010-04-01/Accounts/

apiUrlSmsSendPart

the URL part used while sending a message, may also contain placeholders

accountSid

the unique SID of the Twilio account

accountToken

the matching identifying token of the Twilio account

fromNumber

the sender's phone number, as displayed in the SMS

to

an optional parameter, used in third-party-tests for the recipient phone number of the test-SMS

accountSid and accountToken need to be provided by the customer by creating an account at https://www.twilio.com.

The TwilioSmsSendService comes preconfigured with a simple replacement template strategy.

ExchangeRateUpdateProvider

The ExchangeRateUpdateProvider must be implemented to fetch currency-exchange-rate updates, if required, e.g. by integrating an external service, such as Yahoo!-Finance.

By default the service will be called every minute, and should return all exchange-rates that were updated. The service may decide to return cached results, only new/changed rates will be added to the database.

Accounting TransferListener

The TransferListener interface in the Accounting module can be used to be informed about every single Transfer that is created or cancelled.

The methods are called with read-only objects to prevent tampering with the data and causing inconsistencies.

VoucherCodeGenerator

The VoucherCodeGenerator interface can be implemented to provide a product-specific implementation for generating, formatting and validating voucher-codes, e.g. used for the P2P-transactions in the CoreWallet.