Using the PayByLink API a payment can be created by an external system. The way this API is implemented, there is hardly need to change the supplied values to a PayByLink format because these values can be mapped to internal values within the PayByLink environment by the entity administrator.
As described, the PayByLink system uses an internal mapping system, to map input values to other input values that are mandatory for creating payments. There is no need to comply to the internal names of parameters because names, as well as values for these names, can be mapped as well using mapping rules.
To create a payment, a currency is mandatory. Internally the name for this parameter is named ‘*CurrencyCode’. We can choose to set this value in the PayByLink system to a fixed (and allowed) value, like ‘EUR’ but we can also choose to map a value that is supplied externally to the correct internal value.
In this example, we have input parameters called ‘Currency’ and ‘LanguageName’ with its own values that must be mapped to an accepted *CurrencyCode and *LanguageCode value. The following mapping rules can apply:
| # | INPUT VALUE | INPUT CONDITION | OUTPUT NAME |
|---|---|---|---|
| 1 | EUR | [Currency] = ‘Euros’ | *CurrencyCode |
| 2 | USD | [Currency] = ‘Dollars’ or [Currency] = ‘Us dollars’ | *CurrencyCode |
| 3 | AUD | *CurrencyCode | |
| 4 | nl-NL | [LanguageName] = ‘Dutch’ | *LanguageCode |
| 5 | en-US | *LanguageCode | |
| 6 | [*AddHours([*DateNow], 4)] | *ExpirationDateTime | |
| 7 | [LoggedOnUser] | UserName |
The system checks the rules from top to bottom and skips a rule if an output name already has been set before. When rule 1 is checked, the system asks for the input value for ‘Currency’ and checks this with the value ‘Euros’. If these values are the same, the system sets the (internal) value ‘*CurrencyCode’ to ‘EUR’. If not, the system checks if ‘Currency’ contains the value ‘Dollars’ or ‘Us dollars’ and, if true, sets the ‘*CurrencyCode’ to ‘USD’. If this is also not the case, the ‘*CurrencyCode’ value is set to ‘AUD’ so *CurrencyCode will always get a value.
Also values can contain functions. In rule 6 we set the ExpirationDate to four hours from now. Finally in rule 7, we just create our own parameter called ‘UserName’ that is set by using the input value for ‘LoggedOnUser’ that is supplied. If a parameter is used as input in the mapping, and this parameter is not supplied, an error is thrown. In this example ‘Currency’, ‘LanguageName’ and ‘LoggedOnUser’ must be supplied as input parameters.
Only input parameters that were mapped, can be used within the PayByLink system. So in the mapping example ‘[LanguageName]’, ‘[Currency]’ and ‘[LoggedOnUser]’ cannot be used, but only the ‘Output name’ parameters they were mapped to internally. In the system these ‘own’ parameters can be used by mentioning them like [<name>]. For instance: ‘[UserName]’ from the mapping example.
Using this mapping tool, PayByLink can be used by any external system to create a payment hardly without any expensive development needed. When a connection is made to the PayByLink system, payments can be created by ‘configuring’ instead of ‘developing’! This can be done by the entity administrator or by PayByLink employees.
Because multiple mapping templates can be created within the PayByLink system on entity or on a license level, the caller that uses the API has to identify what mapping must used to process the supplied information. This can be done by supplying a parameter with the name MappingTemplate. If this parameter is not supplied, or if it has no or an empty value, the default mapping will be used for that entity.
When a new mapping is created, all the mandatory output names will be created automatically. These values must be supplied but some of them can be left empty.
Parameters that can be used to create payments or in the mappings are described in the Glossary
