Skip to main content

Payment flows

EVA supports multiple payment providers. The CreatePayment services tries not to interpret or fully normalize method specific properties but instead opts for a pass-through strategy. The payment methods broadly fall into the following categories:

  • cash (physical drawer)
  • PIN (physical terminal)
  • gift cards
  • hosted service

Below we will detail the call sequences for each method type.

The payments are performed as an important step in the Checkout process. There is an Order level IsPaid requirement in the response from GetRequiredDataForOrder. To fulfill this requirement you will need to complete one of the payment flows detailed below. The order state in EVA applications is usually driving the front-end user interface. The fulfilled requirement should open up new buttons and or panels to complete the checkout. Should you be interested in the result of a single payment transaction you can use GetPaymentTransaction with the ID returned from CreatePayment. Alternatively the GetOrder request can be amended with IncludePendingPayments and IncludeFailedPayments to retrieve the payment details that way.

Cash payments#

The simplest of all payment methods which is handled synchronously. The employee performs the required actions to complete the payment. This involves opening the cash drawer and handling the currency to return to the customer.

Required data:

  • OrderID
  • StationID
  • AmountGiven

Optional data:

  • Amount (defaults to OpenAmount)

Known method names:

  • CASH
sequenceDiagram participant POS participant OrderHub %%participant PaymentHub participant GetAvailablePaymentMethods participant CreatePayment participant GetCurrentOrder %% Create and subscribe to order POS ->> OrderHub: Subscribe: CurrentOrderID %% Available methods POS ->> GetAvailablePaymentMethods: CurrentOrderID GetAvailablePaymentMethods ->> POS: AvailableMethods %% Perform payment POS ->> CreatePayment: PaymentData CreatePayment -->> POS: AmountReturned %% Post payment update OrderHub ->> POS: OrderUpdated POS ->> GetCurrentOrder: Update POS ->> GetRequiredDataForOrder: Update

Gift or user card payments#

Prepaid currency that needs to be verified with an external provider. Balance is reserved and finalized when the order is shipped. If the card balance is lower then the open amount the order will remain not fully paid. The remaining amount will be paid using another payment method

Required data:

  • OrderID
  • StationID
  • CardNumber

Optional data:

  • Amount (defaults to OpenAmount)
  • PinCode (depends on card type)

Known method names:

  • INTERSOLVE
  • VALUTEC
  • FASHIONCHEQUE
  • USERCARD
sequenceDiagram participant POS participant OrderHub %%participant PaymentHub participant GetAvailablePaymentMethods participant CreatePayment participant GetCurrentOrder %% Create and subscribe to order POS ->> OrderHub: Subscribe: CurrentOrderID %% Available methods POS ->> GetAvailablePaymentMethods: CurrentOrderID GetAvailablePaymentMethods ->> POS: AvailableMethods %% Perform payment POS ->> CreatePayment: PaymentData CreatePayment ->> POS: AmountReturned %% Post payment update OrderHub ->> POS: OrderUpdated POS ->> GetCurrentOrder: Update POS ->> GetRequiredDataForOrder: Update

PIN payments#

A PIN payment is asynchronous by nature because it relies on the customer to perform the required actions to complete it. In the past we polled the GetPaymentTransactionDetails service with multiple retries which worked most of the time. This moment of waiting is susceptible to network issues which is why we now rely on SignalR. The SDK will resubscribe to the payment transaction again automatically when the hub loses connection. However the transaction update event might have occurred in the downtime so the POS should update the order state on reconnection or using some sort of pulldown refresh.

Required data:

  • OrderID
  • StationID

Optional data:

  • Amount (defaults to OpenAmount)
  • MerchantAccount (from configuration, prefilled by SDK)

Known method names:

  • ADYEN_ALIPAY
  • ADYEN_PIN
  • ADYEN_WECHATPAY_POS
  • PIN
sequenceDiagram participant POS participant OrderHub participant PaymentHub participant GetAvailablePaymentMethods participant CreatePayment participant GetCurrentOrder %% Create and subscribe to order POS ->> OrderHub: Subscribe: CurrentOrderID %% Available methods POS ->> GetAvailablePaymentMethods: CurrentOrderID GetAvailablePaymentMethods ->> POS: AvailableMethods %% Perform payment POS ->> CreatePayment: Method: CASH Data: AmountGiven CreatePayment ->> POS: PaymentTransactionID POS ->> PaymentHub: Subscribe: PaymentTransactionID PaymentHub ->> POS: TransactionUpdated %% Post payment update OrderHub ->> POS: OrderUpdated POS ->> CurrentOrder: Update POS ->> GetRequiredDataForOrder: Update

External payment portals#

External payment providers will be handed the order as-is and will become responsible for fulfilling they payment of the order. Specialised customer specific payment methods also fall into this category. The order will often not immediately be marked as fully paid as this happens asynchronously on an external system. Unlike PIN payments there is no transaction ID available we can monitor so we will rely on the OrderHub to notify us of status changes. There is also no option for partial payments.

Required data:

  • OrderID

Optional data:

  • ReturnUrl

A selection of method names:

  • ADYEN_CHECKOUT_API
  • BUCKAROO
  • EVAPAY
  • PUBLICRELATIONS
  • TREATWELL
sequenceDiagram participant POS participant OrderHub %%participant PaymentHub participant GetAvailablePaymentMethods participant CreatePayment participant GetCurrentOrder %% Create and subscribe to order POS ->> OrderHub: Subscribe: CurrentOrderID %% Available methods POS ->> GetAvailablePaymentMethods: CurrentOrderID GetAvailablePaymentMethods ->> POS: AvailableMethods %% Perform payment POS ->> CreatePayment: PaymentData CreatePayment ->> POS: PaymentAccepted %% Post payment update OrderHub ->> POS: OrderUpdated POS ->> GetCurrentOrder: Update POS ->> GetRequiredDataForOrder: Update

Refund payments#

Refunds work much the same as normal payments however the following services are replaced:

  • CreatePayment -> CreateRefund
  • GetAvailablePaymentMethods -> GetAvailableRefundPaymentMethodsForOrder

So for a cash refund the flow would look like this:

sequenceDiagram participant POS participant OrderHub %%participant PaymentHub participant GetAvailableRefundPaymentMethodsForOrder participant CreateRefund participant GetCurrentOrder %% Create and subscribe to order POS ->> OrderHub: Subscribe: CurrentOrderID %% Available methods POS ->> GetAvailableRefundPaymentMethodsForOrder: CurrentOrderID GetAvailableRefundPaymentMethodsForOrder ->> POS: AvailableMethods %% Perform payment POS ->> CreateRefund: PaymentData CreateRefund -->> POS: AmountReturned %% Post payment update OrderHub ->> POS: OrderUpdated POS ->> GetCurrentOrder: Update POS ->> GetRequiredDataForOrder: Update

And similarly for a PIN based refund:

sequenceDiagram participant POS participant OrderHub participant PaymentHub participant GetAvailableRefundPaymentMethodsForOrder participant CreateRefund participant GetCurrentOrder %% Create and subscribe to order POS ->> OrderHub: Subscribe: CurrentOrderID %% Available methods POS ->> GetAvailableRefundPaymentMethodsForOrder: CurrentOrderID GetAvailableRefundPaymentMethodsForOrder ->> POS: AvailableMethods %% Perform payment POS ->> CreateRefund: Method: CASH Data: AmountGiven CreateRefund ->> POS: PaymentTransactionID POS ->> PaymentHub: Subscribe: PaymentTransactionID PaymentHub ->> POS: TransactionUpdated %% Post payment update OrderHub ->> POS: OrderUpdated POS ->> CurrentOrder: Update POS ->> GetRequiredDataForOrder: Update