Custom payment methods

To enable customers to manage their own specific payment methods we introduced CustomPaymentMethod.

A practical example for this is to be able to accept certain gift cards of providers which are not linked to EVA. As you can see under the Custom fields header, you could even add a custom field in which you can add the gift card's number.

note

Instead of creating custom payment methods via API, you can also create them in EVA Suite. See Payment methods in Suite.

PaymentMethods

Creating and updating payment methods can be done using the following services:

Service	Description
GetPaymentMethodByID	Fetch all information available for a payment method.
CreatePaymentMethod	Create a new payment method, all PaymentMethods created with this service will be Custom
UpdatePaymentMethod	Update the Name and/or Code of a custom payment method
DeletePaymentMethod	Delete a custom payment method
ListPaymentMethods	List all available payment methods. Filters available on Name, Code and IsCustom

PaymentTypes

Every PaymentMethod requires at least one PaymentType to make it available in EVA. To increase configuration options for the custom PaymentMethods, you can use the Options object on the PaymentTypes. Options has the following properties, all optional:

Property	Description
RequiredUserType	Makes the PaymentType exclusively available to users with a certain UserType
RequiredFunctionality	Makes the PaymentType exclusively available to users with a certain functionality
RequiredFunctionalityScope	Makes the PaymentType exclusively available to users with a certain functionality
Pending	PaymentTransactions created with this PaymentType will always get the status Pending and need to be approved manually
RefundPending	Refunds created with this PaymentType will always get the status Pending and need to be approved manually
CanBeUsedForPayments	Can be used to make it available for refunds only (still dependent on other refund-related options)
CanBeRefunded	Can PaymentTransactions with this type be refunded?
CanBeCancelled	Can PaymentTransactions with this type be cancelled?
CanRefundWithoutOriginalPaymentTransaction	Can a refund with this PaymentType be created without an original transaction?
RequiresAmount	Requires the user to specify an amount
RequiresConfirmationForPayments	Displays a modal to let employees verify if the payment was successful; if it is not, another payment method can be selected
RequiresConfirmationForRefunds	Displays a modal to let employees verify if the refund was successful; if it is not, another refund method can be selected

This Options object can be managed with the existing services:

• GetPaymentTypeByID
• CreatePaymentType
• UpdatePaymentType
• DeletePaymentType
• ListPaymentTypes

Payment types based on roles

Aside from the properties in the above table, payment types can also be shown/hidden from certain roles in the POS and Companion. To set these roles and payment types, use SetPaymentTypeRoles.

CustomFields

To gather additional information while creating a payment with these new custom PaymentMethods it is possible to create CustomFields. A CustomField is an additional field that can be created on different objects in EVA.

To determine where a CustomField is used a CustomFieldType is needed. This is a manageable enum, like there are more in EVA. Services available:

Property	Description
GetCustomFieldTypes	Fetch all available types.
CreateCustomFieldType	Create a new type.
UpdateCustomFieldType	Update a type.
DeleteCustomFieldType	Delete a type.

A CustomField exists of the following properties:

• Type: the CustomFieldType this field belongs to
• TypeKey: when the field matches a specific part of the type, a key should be set. For PaymentMethods this should contain the ID of the PaymentType or which this field is created
• Name: display name of the field
• DataType: what sort of data can be set for this field? Options are:
  • String = 0
  • Bool = 1
  • Integer = 2: Whole numbers, no fractions
  • Decimal = 3
  • Enum = 4
  • Text = 5: Multiline string -> think textarea
  • DateTime = 6
  • Date = 7
• Order: To determine the order of the fields for the front end
• Options: Some options to validate the values for this field
  • IsArray: Can this field contain multiple values?
  • IsRequired: Is this field required to fill?
  • MinimumValue: Minimum value for Integer/Decimal field
  • MaximumValue: Maximum value for Integer/Decimal field
  • MinimumLength: Minimum length for String/Text field
  • MaximumLength: Maximum length for String/Text field
  • MinimumDate: Minimum date for DateTime field
  • MaximumDate: Maximum date for DateTime field
  • EnumValues: available options for Enum field
    • Format: { 'option1': 'This is the first option', 'option2': 'This is the second option' }
• BackendID: identifier of the field for 3rd party systems

To manage the CustomFields there are some services available:

• GetCustomFieldByID
• CreateCustomField
• UpdateCustomField
• DeleteCustomField
• ListCustomFields: Filter options
  • TypeID
  • TypeKey
  • Name
  • DataType
  • BackendID