Frontend Integration

The steps below outline the work required on the front-end of your store to enable Stripe payments with Self-Managed Commerce. These instructions make use of Stripe Payment Elements.

In Self-Managed Commerce, a shopper's payment details (such as a specific credit card, bank account, etc) is known as a payment instrument. Payment instruments can be added to a shopper's profile, or to an account profile (for B2B scenarios), or added to a shopping cart for single-use.

To add a payment instrument to a shopper's profile, lookup the Stripe payment method resource from the profile resource in Cortex. To add a payment method to an account, lookup the Stripe payment method resource from the account resource. To add a payment method to a shopping cart, lookup the Stripe payment method resource from the cart order resource. In each of these cases, the Stripe payment method can be identified using the name that was specified when configuring the Stripe payment plugin.

From the payment method resource, follow the requestinstructionsform link. Post to the requestpaymentinstructionsaction link with an empty request body, and the response will be a JSON blob containing a client_secret value and a customer_id value.

Follow the Stripe Payment Element instructions to display the UI for collecting payment details. You will need the publishable key from your Stripe Dashboard and the client secret from Cortex. For an example of how to set this up, see the Elastic Path Stripe Payment Flow test harness.

After the payment details are collected, make sure to call stripe.confirmSetup as described in the guide above, and then call stripe.retrieveSetupIntent to collect the payment-method value.

Next, return to the payment method resource in Cortex and follow the paymentinstrumentform link. This form will request display-name, customer_id, and payment_method_id. The display-name can be set to any value that the shopper will recognize if they want to use this payment instrument again in the future. The customer_id should be set to the customer_id value that was returned from the Cortex requestpaymentinstructionsaction response. The payment_method_id value should be set to the payment_method value returned by stripe.retrieveSetupIntent. Post these values to the createpaymentinstrumentaction link.

If you added this payment instrument to the shopping cart, it will be selected automatically. Otherwise, when the shopper is ready to select a payment instrument, you can retrieve the list of saved payment instruments using the paymentinstrumentselector link on the cart order resource. Post to the selectaction link to associate it to the shopping cart.

Finally, when the shopper is ready to checkout, simply follow the purchaseform link on the cart order resource, and post to the submitorderaction link.