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-sessionprepareSession
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-sessiononSessionDataUpdated
can be used to react to changed session-datatoApiSessionPaymentMethod
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:
|
the configured or sandbox domain from Mailgun |
|
the API key provided by Mailgun, usually in the format |
|
the sender of the email, as displayed in the from field |
|
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
|
the send endpoint, currently |
|
the name of the registered user at SureSMS |
|
the matching password for the user |
|
the sender's name, as displayed in the SMS |
|
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
|
the send endpoint, it may contain placeholders for SID and token, e.g. |
|
the URL part used while sending a message, may also contain placeholders |
|
the unique SID of the Twilio account |
|
the matching identifying token of the Twilio account |
|
the sender's phone number, as displayed in the SMS |
|
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.