Create a cash payment extension and configure the webhook

To create a custom integration with a cash payment gateway, perform the following steps:

1. Create the gateway extension. See Cash 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 a cash payment option to the checkout page.
5. Configure the Generic Payment webhook by specifying the gateway URL and the username and password. Note that webhook settings are not site-specific. The configuration you supply applies to all sites that use this webhook.

Cash payment extension details

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

{
  "provider": "Cash Payments",
  "paymentMethodTypes": ["cash"],
  "transactionTypes": {

    "cash": ["initiate", "cancel"]
  },
}

The extension must also create user interface controls (for example, checkboxes) for merchants to specify the countries that cash payments are supported for.

Add a cash payment option to the checkout page

To enable paying through cash, you need to add a cash payment 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 Cash Payment element to the Payment Gateway widget.
5. Publish your changes.

Note that when a shopper checks out, the cash payment option appears on the checkout page only if the country being shipped to appears in the list of countries that cash payments are supported for.

Process the order

When a customer checks out using the cash payment option, the Generic Payment webhook sends a CASH REQUEST transaction type to the payment gateway. The provider can respond with the response code 1000, which acknowledges the payment request. After the payment is received, the provider can update the order with payment details using the updateOrder endpoint in the Admin API.

If payment has already occurred when the webhook request is received, the provider can send the response code 4000 in the webhook response, indicating that the sale is complete. In such cases, updateOrder calls are not needed. If response code 4000 is received, the order is marked as ready for fulfillment.