Payment parameters
Payment parametersThe system uses a range of parameters internally to create a fixed payment (only one amount), a variable payment (the user can choose out of multiple amounts or can enter his own amount within a specified range, for instance for donations), a partial payment setup or a ‘direct collect’ payment. With a partial payment the total amount is spread out over two or more payments within a specific time. A direct collect can only be initiated if a mandate contract is available.
In these payment types the system parameters can be used and also system functions can be used as described in the first chapter. Own parameters can be added too if needed in logging or communication to the customer. You can always create your own internal parameters and set them to fixed values or to values that were supplied to the system within an external API parameter. The names of the parameters can be chosen freely, as long as they are mapped within the PayByLink system to the mandatory system parameters. The following system parameters can be used in the mapping:
- = not allowed (must be left empty)
X = mandatory
O = mandatory with rules
| MANDATORY PER 'PAYMENT TYPE' | ||||||
|---|---|---|---|---|---|---|
| OUTPUT NAME | DESCRIPTION | FORMAT | FIXED | VARIABLE | PARTIAL | COMMENTS |
| *LanguageCode | The payment language | xx-XX (i.e. en-US) | If empty: entity language is used | |||
| *CurrencyCode | The currency of the amount | XXX (i.e. EUR, USD) | If empty: entity currency is used | |||
| *Amount | The total amount to pay | Decimal (xx,xx or xx.xx) | x | - | x | |
| *VariableAmounts | 2 or more amounts where the customer can choose from or enter an own amount within a range | <v1>#<v2>#<v3>... i.e. 5#7,50#10#12,50#15 <v1>#<v2>#range:<v3>:<v4> i.e. 5#50#range:10:45 | - | x | - | |
| *Description | A brief order description | String | If empty: no company name | |||
| *OrderID | A unique order ID | String | x | x | x | Must be unique per entity |
| *Gender | Gender of the client | Char (M, F or U) | If empty: U (unknown) is used | |||
| *ClientName | Name of the client | String | x | x | x | |
| *CompanyName | Company name | String | ||||
| *MailAddress | Mail address | String (xx@xx.xx) | o | o | o | Mandatory when SendType is mail |
| *MailAddressesCC | Mail address(es) in the CC (; separated) | String (xx@xx.xx); (yy@yy.yy) | Interesting when SendType is mail | |||
| *PhoneNumber | (Mobile) phone number | String | o | o | o | Mandatory when SendType is sms |
| *SendType | Indicates via what medium a payment link must be sent | mail, sms or nosend | If emtpy: nosend | |||
| *SendDateTime | The date when a payment must be sent to the customer | Date | If empty: current date and time (send immediately) | |||
| *ExpirationDateTime | The date that this payment will expire | Date | If empty: default expiration time after send is used | |||
| *MailTemplate | The name of the mail template that must be used (when *SendType is mail) | String (name of the mail template) | If empty and *SendType is mail: the default mail template is used | |||
| *MessageTemplate | The name of the message template that must be used (when *SendType is sms) | String (name of the message template) | If empty and *SendType is sms: default message template is used | |||
| *AttachmentUrl | The url to a pdf attachment that can be downloaded from the Internet or from an ftp/sftp server. The username and password can be added before the URL. | String (see comments below for more information) | If supplied, only a pdf file with a maximum of 2mb is allowed. URL must start with: http:// or https:// or ftp:// or sftp:// | |||
| A valid value must be supplied in the form: <user>#<pwd>#<url> or <url> (if no user/pwd is used). The <url> can contain the port number to connect to as well: For instance: ftp://spbl.eu:21/doc.pdf In case of an FTP server, extra parameters ‘ssl’ / ‘nossl’ and/or ‘active’ / ‘passive’ can be sent too, to indicate if an SSL or NO SSL (default) connection and/or ACTIVE or PASSIVE (default) ftp connection must be used. For instance: adm#pwd1#active#ssl#ftp://pb.eu/a/x.pdf or adm#pwd1#nossl#ftp://pb.eu/a/x.pdf | ||||||
| *AttachmentUrl2 | A second attachment can be supplied | String (see comments above for more information) | ||||
| *AttachmentUrl3 | A third attachment can be supplied | String (see comments above for more information) | ||||
| *AttachmentUrl4 | A fourth attachment can be supplied | String (see comments above for more information) | ||||
| *AttachmentUrl5 | A fifth attachment can be supplied | String (see comments above for more information) | ||||
| *PaymentMethodCodes | A list of allowed payment method codes for this payment, separated with #. See further chapter Payment method codes for a list of allowed codes. | <CODE1>#<CODE2>#... i.e. IDEAL#VISA#MASTERCARD#BANCONTACT | If empty, the default enabled payment methods on entity level are used. Only payment methods that are enabled on entity level can be supplied. | |||
| *PspPaymentMethod | The payment method that was used on a successful payment at the PSP (ie: iDEAL, VISA, etc.) | |||||
| *PspPaymentMethodCode | The code of the payment method that was used for a successful payment at the PSP (ie: IDEAL, VISA, etc.) | |||||
| *PartialTemplate | If 'partial payments' must be created, this parameter holds the name of the template | String (name of the template) | - | - | o | Only one of these parameters can have a value: |
| *PartialPercentages | If 'partial payments' must be created, this parameter holds the percentages per partial | <perc1>#<perc2>#<perc3>... i.e. 20#30#40#10 means 4 partial payments | - | - | o | Only one of these parameters can have a value: [*PartialTemplate] [*PartialPercentages] [*PartialAmounts] [*PartialPercentageAmounts] |
| *PartialAmounts | If you want to supply your own amounts for each partial, you can use this parameter. Otherwise the percentages will be used to calculate the amounts for each partial payment using the *Amount value | <am1>#<am2>#<am3>... The sum of all these amounts MUST be equal to the *Amount value | - | - | o | Only one of these parameters can have a value: [*PartialTemplate] [*PartialPercentages] [*PartialAmounts] [*PartialPercentageAmounts] |
| *PartialPercentageAmounts | If a payment must be paid in several parts, the percentages and/or amounts for each payment can be set here, separated with # and must sum up to the amount entered at *Amount | <amnt/perc1>#<amnt/perc2> 150#50%#? indicates three partial payments for an amount of 150, 50% and the remaining amount by indicating ? | - | - | o | Only one of these parameters can have a value: [*PartialTemplate] [*PartialPercentages] [*PartialAmounts] [*PartialPercentageAmounts] |
| *PartialExpirationDates | If you want to supply your own expiration date per partial, you can use this parameter | <date1>#<date2>#<date3>... The last date MUST be equal to the *ExpirationDateTime value | - | - | o | If empty, the percentages/amounts will be used to calculate the time between each partial payment using the time between the *SendDateTime value and *ExpirationDateTime value |
| *PartialFreeAmountsAllowed | Used to indicate if the user is allowed to enter a free amount between the current partial payment amount and the total outstanding amount | true/false | - | - | o | If this value is empty and PartialPercentages, PartialAmount or PartialExpirationDates are filled, 'false' is used |
| *PartialWholeAmountAllowed | Used to indicate if the user is allowed to pay the total outstanding amount at once | true/false | - | - | o | If this value is empty and PartialPercentages, PartialAmount or PartialExpirationDates are filled, 'false' is used |
| *PartialSendFirstPaymentLink | Used to indicate if the first payment must be sent by mail/sms or not (when SendType is mail or sms) | true/false | - | - | o | If this value is empty and PartialPercentages, PartialAmount or PartialExpirationDates are filled, 'false' is used |
| *DirectConfirm | Used to indicate if the payment must be confirmed directly | true/false | - | Default the value is 'false' | ||
| *ShortenedUrl | You can supply a shortened URL that has been created before | String | The URL must be valid and unique. If left empty, the system will generate a shortened URL | |||
| *AcceptUrl | The URL to which the customer is directed after a successful transaction. | Available to automated external calls when creating a payment. | ||||
| *DeclineUrl | The URL to which the customer is directed after a rejected transaction. | Available to automated external calls when creating a payment. | ||||
| *ErrorUrl | The URL to which the customer is directed when an error occurs. | Available to automated external calls when creating a payment. | ||||
| *FailUrl | The URL to which the customer is directed when the transaction failed or the user clicked on 'cancel'. | Available to automated external calls when creating a payment. | ||||
| *HomeUrl | The URL to which the customer is directed when he clicks on 'home'. | Available to automated external calls when creating a payment. | ||||
| *ContactName | The name that must be used as contact setting instead of the entity name. | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactMailAddress | The e-mail address to be used with contact details instead of the entity e-mail address | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactPhoneNumber | The telephone number to be used with contact details instead of the entity telephone number | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactAddressStreet | The street of the address to be used with contact information instead of the street of the entity | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactAddressNumber | The house number of the address to be used with contact details instead of the house number of the entity | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactAddressExtraAddressLine | The extra address line of the address to be used with contact information instead of the extra address line of the entity | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactAddressZipCode | The zip code of the address to be used with contact details instead of the zip code of the entity | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactAddressCity | The city of the address to be used with contact information instead of the city of the entity | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *ContactAddressCountry | The country of the address to be used with contact details instead of the country of the entity | When this parameter is used, the parameter information will be used on the payment screen and NOT the data of the account. | ||||
| *EntityEnableFullWidthScreenHeader | Returns 'True' if the full width screen header is enabled, otherwise 'False' is returned | |||||
| *EntityEnableFullWidthMailHeader | Returns 'True' if the full width mail header is enabled, otherwise 'False' is returned | |||||
Date updated: 2022-03-28
