Our Drupal contributions and client engagements this year have let us continue to expand JSON:API support in Drupal Commerce. We released the first alpha version of the Commerce API module earlier this year and have been constantly working on it since then, resulting in the module's 1.0-beta4 release last week.

What's new in the latest release?

One feature that has been heavily requested is the ability to use on-site payment gateways like Braintree or Stripe in a decoupled context, and guess what? This is now possible since the latest release! Furthermore, "manual" payment gateways (i.e "offline" payments such as cash on delivery...) are now also fully supported.

Great! But... how does this work?

The frontend application is responsible for collecting (usually through a gateway's JS library) and submitting a "payment_instrument" to the backend. The payment instrument instructs the Drupal Commerce backend how to process a customer's payment through the specified payment gateway.

This payload for Braintree demonstrates the payment instrument format:

{
   "payment_instrument":{
      "payment_gateway_id":"braintree",
      "payment_method_type":"credit_card",
      "payment_details":{
         "card_type":"Visa",
         "payment_method_nonce":"xxxxxxxxxx",
         "last2" => 18,
      }
   }

Note that the expected "payment_details" differs for each payment gateway.

The "payment_instrument" is submitted by performing a "PATCH" request to the /jsonapi/checkout/{commerce_order} resource.