Enabling payments in Outlook

Enabling payments in Outlook provides a powerful payment solution that allows you to send requests for payments via email that are immediately actionable by the recipient. The recipient can view their invoice, select a payment method, and approve payment, all from within Outlook.

Let's take a look at the flow for a simple invoice scenario.

Sequence of events for sending an invoice and receiving payment

A flow diagram illustrating the sequence of events for an invoice scenario using payments in Outlook

  1. The merchant sends a payment request email to the recipient on Office 365.
  2. The payment service validates that the sender is allowed to send payment requests before delivering to the user.
  3. The user opens the message, which is rendered as a payment card.
  4. The user invokes the payment action on the card.
  5. The payment service POSTs a request to the merchant's server to get the invoice details and allowed payment methods.
  6. The merchant uses the information in the POST to retrieve the invoice and sends it back to Outlook.
  7. The user reviews the invoice, selects a payment method, and approves payment without leaving Outlook.
  8. The payment service POSTs a payment token to the merchant's server.
  9. The merchant processes the token using the appropriate payment processor API (Stripe, Microsoft Pay, etc.) and sends the result back to Outlook.
  10. Outlook displays the result.

Integration components

There are two major components to creating a payment integration in Outlook.

  • Payment request message - This is an email message that includes pay-specific actions. Your service sends these specially-formatted messages to the recipient.
  • Webhook service - This is a web service that implements two distinct webhooks: one that provides up-to-date invoice or checkout information, and one that accepts payment.

Payment request message

The payment request message is an email message with an actionable card embedded in the HTML body. The card is defined by a JSON payload as specified in ActionRequest markup reference.

A screenshot of a payment request message in Outlook

The ActionRequest payload contains a productContext JSON dictionary, which should include the information your webhooks need to locate the corresponding invoice.

Important

The ability to send payment request messages to users requires registration with the actionable email developer dashboard. The payment card markup also requires a merchant ID and display ID generated by the partner dashboard for payments in Outlook. For details, see Get started with payments in Outlook.

Webhooks

The web service implements two distinct webhooks.

  • Payment request webhook: this webhook receives POSTs to load invoices. If your invoicing scenario includes prompting for a shipping address and shipping option, this webhook also receives POSTs when the user selects or changes their shipping information. This webhook returns an up-to-date invoice to be displayed in Outlook. For details, see PaymentRequest webhook.
  • Payment complete webhook: this webhook receives POSTs with payment tokens. This webhook processes payment tokens and returns success or failure to Outlook. For details, see PaymentComplete webhook.

Next steps

Check out our getting started guide to learn how to implement your own payments in Outlook solution.