Skip to main content

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:

ServiceDescription
GetPaymentMethodByIDFetch all information available for a payment method.
CreatePaymentMethodCreate a new payment method, all PaymentMethods created with this service will be Custom
UpdatePaymentMethodUpdate the Name and/or Code of a custom payment method
DeletePaymentMethodDelete a custom payment method
ListPaymentMethodsList 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:

PropertyDescription
RequiredUserTypeMakes the PaymentType exclusively available to users with a certain UserType
RequiredFunctionalityMakes the PaymentType exclusively available to users with a certain functionality
RequiredFunctionalityScopeMakes the PaymentType exclusively available to users with a certain functionality
PendingPaymentTransactions created with this PaymentType will always get the status Pending and need to be approved manually
RefundPendingRefunds created with this PaymentType will always get the status Pending and need to be approved manually
CanBeUsedForPaymentsCan be used to make it available for refunds only (still dependent on other refund-related options)
CanBeRefundedCan PaymentTransactions with this type be refunded?
CanBeCancelledCan PaymentTransactions with this type be cancelled?
CanRefundWithoutOriginalPaymentTransactionCan a refund with this PaymentType be created without an original transaction?
RequiresAmountRequires the user to specify an amount
RequiresConfirmationForPaymentsDisplays a modal to let employees verify if the payment was successful; if it is not, another payment method can be selected
RequiresConfirmationForRefundsDisplays 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:

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:

PropertyDescription
GetCustomFieldTypesFetch all available types.
CreateCustomFieldTypeCreate a new type.
UpdateCustomFieldTypeUpdate a type.
DeleteCustomFieldTypeDelete 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