Create an invoice payment extension and modify the checkout page

To create a custom integration with an invoice payment gateway, you perform the following steps:

1. Create the gateway extension. See Invoice payment extension details for information specific to this extension.
2. Upload the extension to the administration interface.
3. Enable the gateway for the sites that require it.
4. Add an invoice payment option to the checkout page.
5. Configure the Generic Payment webhook by specifying the gateway URL and the username and password. (This step is optional. See Validate the purchase order number.) Note that webhook settings are not site-specific. The configuration you supply applies to all sites that use this webhook.
6. Add invoice payment information to order pages.

Invoice payment extension details

The format of a payment gateway extension is described in the Create a Credit Card Payment Gateway Integration chapter. For an invoice gateway, the gateway.json file should be similar to the following:

{
  "provider": "Invoice Payment Provider",
  "paymentMethodTypes": ["invoice"],
  "transactionTypes": {
    "invoice": ["authorization"]
  }
}

Add an invoice payment option to the checkout page

To enable paying through a purchase order, you need to add an invoice option to the checkout page:

1. Open the Checkout Layout that you are using on your storefront. (The default is Checkout Layout with GiftCard.)
2. Switch to grid view.
3. Add the Payment Gateway widget to the layout.
4. Add the Invoice Payment element to the Payment Gateway widget.
5. Publish your changes.

If the invoice gateway is enabled, the checkout page displays a checkbox for optionally requesting an invoice. When the shopper selects this checkbox, a text field appears for specifying a purchase order number:

Validate the purchase order number

When a shopper checks out using a purchase order number, the Store API createOrder endpoint includes the purchase order number in the submitted order. The merchant can then issue an invoice for the amount owed. After receiving payment, the merchant should invoke the updateOrder endpoint to update the order.

You can optionally configure the Generic Payment webhook to send transaction data, including the purchase order number, to an external service for validation. If the webhook is configured, Commerce waits for the result of the validation to determine whether to submit the order.

Add invoice payment information to order pages

To display information about the invoice payment selection and purchase order number on the order details and order confirmation pages, you need to make changes to the corresponding layouts.

To update the order details page perform the following steps:

1. Open the Order Details Layout.
2. Switch to grid view.
3. Replace the Order Details widget with the Order Details with Additional Info widget.
4. Publish your changes.

To update the order confirmation page:

1. Open the Order Confirmation Layout.
2. Switch to grid view.
3. Replace the Order Confirmation widget with the Order Confirmation with Additional Info widget.
4. Publish your changes.