Usage (Card Payment)

Step 1 Install via Nuget:

install-packge Our.Umbraco.Cashier Step 2 Payment Intents are stored in a database. This can point to your Umbraco database. A table called PaymentIntents will be created.

Step 3 Install a Cashier Payment Provider solution package: (currently only stripe exists)

install-package Our.Umbraco.Cashier.Stripe For instructions on how to finish the Stripe setup (configure keys etc.), click here.

Step 4 Create an Umbraco Composition to register your selected payment gateway. You only need to register what your are planning to use.

public class RegisterPaymentGatewayComposer : IUserComposer { public void Compose(Composition composition) { composition.Register(typeof(ICardPaymentGateway), typeof(StripeCardPaymentGateway), Lifetime.Request); composition.Register(typeof(IDirectDebitPaymentGateway), typeof(StripeDirectDebitPaymentGateway), Lifetime.Request); } } Step 5 Now you are ready to take payment. First of all, set up a controller that injects ICashier

public class DonationFormSurfaceController : SurfaceController { public ICashier Cashier { get; }

public DonationFormSurfaceController(ICashier cashier)
{
    Cashier = cashier;
}
    
public ActionResult HandleDonation(DonationFormModel model)
{
    //<---- we will take payment here
}

} Now we have a controller, all we need to do is arrange for payment to be taken. To do this, all we do is:

var paymentIntentRequest = PaymentIntentRequest.CreateCardPayment( transactionReference: transactionReference, description: "Donation", amount: model.Amount, customerEmail: model.Email, confirmationPageUrl: CurrentPage.Url, failurePageUrl: Umbraco.Content(1148).Url, callbackUrl: "/umbraco/surface/DonationFormSurface/HandleCallback", additionalData: "" );

//here I am going to store the donation model against the PaymentIntent so that I can load it later to complete the process paymentIntentRequest.AdditionalData = JsonConvert.SerializeObject(model);

var paymentIntentCreated = Cashier.CreateNewPaymentIntent(paymentIntentRequest);

return paymentIntentCreated.ActionResult; At this point, we have now returned the ActionResult returned from the Payment Provider implementation. We will need to write the callback method so that Cashier can tell us whether the payment was successful or not. This callback is asynchronous and will happen in the background.

You will see that we have already set the callbackUrl to /umbraco/surface/DonationFormSurface/HandleCallback. Let's write it.

The success page, failure page and callback url will recieve two querystring parameters tr and hs. The tr parameter is the Transaction Reference and the hs parameter is handshake.

We will need to get the PaymentIntent from Cashier using the Transaction Reference and validate the Handshake is correct. The Handshake is secret and only known by Cashier.

public ActionResult HandleCallback(string tr, string hs) { var paymentIntent = Cashier.GetPaymentIntentByTransactionRef(tr);

//validate the handshake matches
if(paymentIntent.HandShake != hs)
{
    return new HttpStatusCodeResult(400);
}

//now we can load our donation model out
var model = JsonConvert.DeserializeObject<DonationFormModel>(paymentIntent.AdditionalData);

if(paymentIntent.PaymentStatus == PaymentStatus.Succeeded)
{
    //do whatever here: register in CRM, send email, etc.
}

} Remember! The success page should validate the PaymentIntent handshake in the exact same way.