Copied to clipboard

Flag this post as spam?

This post will be reported to the moderators as potential spam to be looked at

  • Flavio Spezi 128 posts 314 karma points
    Jan 17, 2015 @ 16:24
    Flavio Spezi

    How to use GatewayProviderService.ApplyPaymentToInvoice method

    I am developing a Payment Gateway.

    I am in writing of "PeformAuthorizePayment", "PeformAuthorizeCapturePayment", "PerformCapturePayment", "PerformRefundPayment", "PerformVoidPayment".

    Can you spell me how they must be works?

    I would invoke GatewayProviderService.ApplyPaymentToInvoice. What is it? What is the amount argument? How is it to set when the payment action is completed with success? And if the action fails?

    When is payment.Authorized to set to true?
    When is payment.Collected to set to true?


  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Jan 20, 2015 @ 17:53
    Rusty Swayne

    When writing a payment provider, your Provider will inherit from PaymentGatewayProviderBase and include the GatewayProviderActivationAttribute and your method will inherit from the PaymentGatewayMethodBase (which has optional attributes for injecting configuration editors in the angular back office).

    It looks like you've figured this part out.


    /// <summary>
    /// Represents a CashPaymentGatewayProvider
    /// </summary>
    [GatewayProviderActivation("B2612C3D-8BF0-411C-8C56-32E7495AE79C", "Cash Payment Provider", "Cash Payment Provider")]
    public class CashPaymentGatewayProvider : PaymentGatewayProviderBase, ICashPaymentGatewayProvider


    /// <summary>
    /// Represents a CashPaymentMethod
    /// </summary>    
    [GatewayMethodEditor("Cash Method Editor", "~/App_Plugins/Merchello/Modules/Settings/Payment/Dialogs/paymentmethod.html")]
    public class CashPaymentGatewayMethod : PaymentGatewayMethodBase, ICashPaymentGatewayMethod

    Merchello creates records for payments and then applies the payments to an invoice. When we build out all of the planned functionality, you will be able to capture a payment for say $100.00 and then apply the payment to one or more invoices like one would do in a simple accounting program.

    So what your doing in these methods is the accounting logic.

    When authorizing you are receiving a promise to pay - so it creates a payment record and applies an amount of $0 to the invoice since the money has not been collected. When the payment is later captured, you the amount is generally the amount of the invoice total. However, it is possible to capture a different amount either leaving a partial payment (for less than the balance due on the invoice) or have a situation where the invoice has been overpaid and thus having a customer credit.

    payment.Authorized and payment.Captured are generally set in the Perform methods you are currently writing.

    Example from the Merchello.Core.Gateways.Payment.Cash.CashPaymentGatewayMethod

     /// <summary>
        /// Does the actual work of creating and processing the payment
        /// </summary>
        /// <param name="invoice">The <see cref="IInvoice"/></param>
        /// <param name="args">Any arguments required to process the payment. (Maybe a username, password or some Api Key)</param>
        /// <returns>The <see cref="IPaymentResult"/></returns>
        protected override IPaymentResult PerformAuthorizePayment(IInvoice invoice, ProcessorArgumentCollection args)
            var payment = GatewayProviderService.CreatePayment(PaymentMethodType.Cash, invoice.Total, PaymentMethod.Key);
            payment.CustomerKey = invoice.CustomerKey;
            payment.PaymentMethodName = PaymentMethod.Name;
            payment.ReferenceNumber = PaymentMethod.PaymentCode + "-" + invoice.PrefixedInvoiceNumber();
            payment.Collected = false;
            payment.Authorized = true;
            // In this case, we want to do our own Apply Payment operation as the amount has not been collected -
            // so we create an applied payment with a 0 amount.  Once the payment has been "collected", another Applied Payment record will
            // be created showing the full amount and the invoice status will be set to Paid.
            GatewayProviderService.ApplyPaymentToInvoice(payment.Key, invoice.Key, AppliedPaymentType.Debit, string.Format("To show promise of a {0} payment", PaymentMethod.Name), 0);
            //// If this were using a service we might want to store some of the transaction data in the ExtendedData for record
            return new PaymentResult(Attempt.Succeed(payment), invoice, false);
  • Flavio Spezi 128 posts 314 karma points
    Jan 20, 2015 @ 18:26
    Flavio Spezi

    Beautiful response.
    Thanks @Rusty.

    Only one question remains unanswered: when is payment.Collected to set to true?

  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Jan 20, 2015 @ 18:50
    Rusty Swayne

    payment.Collected is generally set to true in AuthorizedCaptured and Captured if the captured amount is equal to the amount authorized.

  • Flavio Spezi 128 posts 314 karma points
    Jan 20, 2015 @ 19:15
    Flavio Spezi


    I forgot a question.

    Can you explain what are these method?

    • "PeformAuthorizePayment"
    • "PeformAuthorizeCapturePayment"
    • "PerformCapturePayment"
    • "PerformRefundPayment"
    • "PerformVoidPayment"

    I think that:

    • PeformAuthorizePayment
      is to request an authorization payment.
    • PeformAuthorizeCapturePayment
      is to request an authorization and capture a payment.
    • PerformCapturePayment
      is to capture an already authorized payment (authorized with "PerformAuthorizePayment").
    • PerformRefundPayment
      is to give back a payment that was previously captured.
    • PerformVoidPayment
      is to abort a payment that was never received.

    Is it true?

    Then, in a credit card payment gateway, these methods will be set payment.Authorized and payment.Collected. How?
    What is the value of amount argumento of ApplyPaymentToInvoice for each these methods?


    payment.Authorized = true;  
    payment.Collected = false;  
    amountArgument = 0;

    PeformAuthorizeCapturePayment and PerformCapturePayment:

    payment.Authorized = true;
    payment.Collected = [already paid] + payment.amount >=;  
    amountArgument = payment.amount;


    payment.Authorized = ???;
    payment.Collected = ???;
    amountArgument = - payment.amount;


    payment.Authorized = ???;
    payment.Collected = ???;
    amountArgument = 0;

    Is it true?

  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Jan 21, 2015 @ 15:26
    Rusty Swayne

    Pretty close.

    PerformRefundPayment is to give back either the full amount or a partial amount

     amountArgument = [amount to be refunded];  // if payment.Amount != invoice.Total invoice will be set to Partial status

    PerformVoidPayment is to cancel a payment but it should keep a record of the transaction. Applied payments should be 0

    payment.Authorized = false; // (but should not be relevant)
    payment.Collected = false; // (but should not be relevant)
    amount = 0;  // I may add an extended data value for the payment with the original amount in PaymentGatewayMethodBase on a void.
  • Biagio Paruolo 1505 posts 1647 karma points c-trib
    Jul 16, 2015 @ 12:10
    Biagio Paruolo

    Is't better to capture from gateway backend or from Merchello backoffice? How works if you made authorize&capture and not authorize and then capture?

  • Rusty Swayne 1655 posts 4993 karma points c-trib
    Jul 16, 2015 @ 15:58
    Rusty Swayne

    They are different operations. An AuthorizeCapture does everything in a single go.

    The way I think of the providers that redirect to another site and then send a response back is:

    • Customer clicks a button saying they are ready to pay. This implies THEY are Authorizing the payment (which I understand is not really a payment authorization like on a credit card). This information is saved to Merchello so that the invoice is persisted and a payment record is created so that there is a record in the store before redirecting to whatever provider site.
    • Customer does their thing on the provider site (e.g. PayPal in this case). If payment is successful the return can generally include a few parameters that will allow you to lookup the invoice and payment so that you can do the Capture which will do a second applied payment for the amount of the the transaction - this one with an actual amount. This would be done in an HttpHandler, Api Controller whatever.

    In the back office, you can capture payments, but the method has to be setup for that. It needs a few more dialogs added so that the correct information can be collected from the provider. I did some for the Braintree provider if you want to take a look and see how those are done.

Please Sign in or register to post replies

Write your reply to: