Tips and Donations

Adding Tips

To add tips to an order, there is a method:

IOperationService.AddDonation

IPaymentItem AddDonation([NotNull] ICredentials credentials, [NotNull] IOrder order, [NotNull] IDonationType donationType, [NotNull] IPaymentType paymentType, [CanBeNull] IPaymentItemAdditionalData additionalData, bool isProcessed, decimal donationSum);

• The parameter passed is the tip type IDonationType. The list of tip types available for a specific order can be obtained by calling the method IOperationService.GetDonationTypesCompatibleWith and passing the order as a parameter.
• One of the parameters is the payment type IPaymentType, which will be used to process the tips. The list of available payment types for the selected tip type can be found from the previously selected tip type IDonationType.PaymentTypes.
• The parameter isProcessed indicates whether the tips should be processed through SyrveFront or if they have already been processed externally.

Examples

• Adding cash tips to an open order.

  const bool isProcessed = true;
  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.New);
  var donationType = PluginContext.Operations.GetDonationTypesCompatibleWith(order).Last(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.Cash));
  var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.Cash);
  var credentials = PluginContext.Operations.GetCredentials();
  var paymentItem = PluginContext.Operations.AddDonation(credentials, order, donationType, paymentType, null, isProcessed, order.ResultSum / 10);
  order = PluginContext.Operations.GetOrderById(order.Id);
  Debug.Assert(order.Donations.Contains(paymentItem));
  

• Adding card tips to a closed order.

  const bool isProcessed = true;
  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.Closed);
  var donationType = PluginContext.Operations.GetDonationTypesCompatibleWith(order).First(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.Card));
  var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.Card && x.Name.ToUpper() == "VISA");
  var additionalData = new CardPaymentItemAdditionalData { CardNumber = "123456" };
  var credentials = PluginContext.Operations.GetCredentials();
  var paymentItem = PluginContext.Operations.AddDonation(credentials, order, donationType, paymentType, additionalData, isProcessed, order.ResultSum / 4);
  order = PluginContext.Operations.GetOrderById(order.Id);
  Debug.Assert(order.Donations.Contains(paymentItem));
  

• Adding tips to an open order using a plugin payment type.

  const bool isProcessed = true;
  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.New);
  var donationType = PluginContext.Operations.GetDonationTypesCompatibleWith(order).First(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.External));
  var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.External && x.Name == "SampleApiPayment");
  var credentials = PluginContext.Operations.GetCredentials();
  var paymentItem = PluginContext.Operations.AddDonation(credentials, order, donationType, paymentType, null, isProcessed, order.ResultSum / 3);
  order = PluginContext.Operations.GetOrderById(order.Id);
  Debug.Assert(order.Donations.Contains(paymentItem));
  

• Adding cash tips to an open order that will be processed on the SyrveFront side.

  const bool isProcessed = false;
  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.New);
  var donationType = PluginContext.Operations.GetDonationTypesCompatibleWith(order).Last(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.Cash));
  var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.Cash);
  var credentials = PluginContext.Operations.GetCredentials();
  var paymentItem = PluginContext.Operations.AddDonation(credentials, order, donationType, paymentType, null, isProcessed, order.ResultSum / 10);
  order = PluginContext.Operations.GetOrderById(order.Id);
  Debug.Assert(order.Donations.Contains(paymentItem));
  

• Adding card tips to a closed order, processing is done on the SyrveFront side.

  const bool isProcessed = false;
  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.Closed);
  var donationType = PluginContext.Operations.GetDonationTypesCompatibleWith(order).First(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.Card));
  var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.Card && x.Name.ToUpper() == "VISA");
  var additionalData = new CardPaymentItemAdditionalData { CardNumber = "123456" };
  var credentials = PluginContext.Operations.GetCredentials();
  var paymentItem = PluginContext.Operations.AddDonation(credentials, order, donationType, paymentType, additionalData, isProcessed, order.ResultSum / 4);
  order = PluginContext.Operations.GetOrderById(order.Id);
  Debug.Assert(order.Donations.Contains(paymentItem));
  

• Adding tips to an open order using a non-processed plugin payment type. It is worth noting that for a non-processed payment type, the plugin must support Silent payment.

  const bool isProcessed = false;
  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.New);
  var donationType = PluginContext.Operations.GetDonationTypesCompatibleWith(order).First(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.External));
  var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.External && x.Name == "SampleApiPayment");
  var additionalData = new ExternalPaymentItemAdditionalData { CustomData = Serializer.Serialize(new PaymentAdditionalData { SilentPay = true }) };
  var credentials = PluginContext.Operations.GetCredentials();
  var paymentItem = PluginContext.Operations.AddDonation(credentials, order, donationType, paymentType, additionalData, isProcessed, order.ResultSum / 2);
  order = PluginContext.Operations.GetOrderById(order.Id);
  Debug.Assert(order.Donations.Contains(paymentItem));
  

• Adding tips during the payment processing with an external plugin type. In this example, it is required to change the implementation of the method IExternalPaymentProcessor.Pay.

  public void Pay(decimal sum, [NotNull] IOrder order, Guid paymentTypeId, Guid transactionId, [NotNull] IPointOfSale pointOfSale, [NotNull] IUser cashier,
    [NotNull] IOperationService operations, IReceiptPrinter printer, IViewManager viewManager, IPaymentDataContext context)
  {
    var donationType = operations.GetDonationTypesCompatibleWith(order).FirstOrDefault(dt => dt.PaymentTypes.Any(pt => pt.Kind == PaymentTypeKind.External));
    if (donationType != null)
    {
        var paymentType = donationType.PaymentTypes.First(x => x.Kind == PaymentTypeKind.External && x.Name == "SampleApiPayment");
        var additionalData = new ExternalPaymentItemAdditionalData { CustomData = Serializer.Serialize(new PaymentAdditionalData { SilentPay = true }) };
        var credentials = operations.GetCredentials();
  
        operations.AddDonation(credentials, order, donationType, paymentType, additionalData, false, order.ResultSum / 2);
    }
  }
  

Comments:

• In the examples, the expression PluginContext.Operations.GetOrders().Last(...) is used — obtaining the last order from the list. Similar expressions are used to obtain tip and payment types. To solve business tasks, the appropriate selection criteria should be used.
• PluginContext.Operations.GetCredentials() — here and further in the examples, an extension method is provided, implemented in the SamplePlugin project example.
• Debug.Assert(order.Donations.Contains(paymentItem)) — merely demonstrates that the recently added tips should be present in the list of tips in the order (unless, of course, someone managed to remove them in the time between adding and checking).

Additionally:

• Silent payment for an order can be found in the section External Payment Types.
• More about payments, prepayments, and deposits can be found in the section Payment Actions.

Removing Tips

To remove previously added tips from an order, there is a method:

IOperationService.DeleteDonation

void DeleteDonation([NotNull] ICredentials credentials, [NotNull] IOrder order, [NotNull] Data.Payments.IPaymentItem paymentItem);

• One of the parameters is the payment item (tip) IPaymentItem that needs to be removed.
• The list of tips added to the order can be obtained from IOrder.Donations.

Examples

• Attempting to remove tips from an order

  var order = PluginContext.Operations.GetOrders().Last(o => o.Status == OrderStatus.New || o.Status == OrderStatus.Bill || o.Status == OrderStatus.Closed);
  var donationItem = order.Donations.LastOrDefault();
  if (donationItem != null)
  {
    PluginContext.Operations.DeleteDonation(PluginContext.Operations.GetCredentials(), order, donationItem);
  }