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.

Provider

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

Method

/// <summary>
/// Represents a CashPaymentMethod
/// </summary>    
[GatewayMethodUi("CashPaymentMethod")]
[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;

        GatewayProviderService.Save(payment);

        // 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
        ////payment.ExtendData

        return new PaymentResult(Attempt.Succeed(payment), invoice, false);
    }

Beautiful response.
Thanks @Rusty.

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

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

Ok.

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?

PeformAuthorizePayment:

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

PeformAuthorizeCapturePayment and PerformCapturePayment:

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

PerformRefundPayment:

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

PerformVoidPayment:

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

Is it true?

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.

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?

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.

is working on a reply...