Payments

The payment flow itself — placing the order first, handing it to handle-payment, following the redirect and reading the transaction state on the return page — is covered end-to-end in the Payment recipe. This page covers what the recipe does not: authenticating a headless storefront against a payment app server.

Prior knowledge

• Payments concept
• Payment API

Payment Integrations

See also all our Payment Integrations.

App server integration

When a payment method uses an app server, for example as a gateway or middleware, there are some key information needed to identify the client source and the store related to the app itself.

In detached API consumer like headless app, the mentioned information can be obtained by using a tailored endpoint:

⚠️ works only for logged-in customers

import { useShopwareContext } from "#imports";

const { apiClient } = useShopwareContext(); // or use an instance of @shopware/api-client library

const tokenResponse = await apiClient.invoke(
  "generateJWTAppSystemAppServer post /app-system/{name}/generate-token",
  {
    pathParams: {
      name: "MyPaymentApp",
    },
  },
);

The response may look like this:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJVZXF4S1RtSHBKVHZmZkRQIiwiaWF0IjoxNzMzNDA5NTM3LjQ1NzYxMSwibmJmIjoxNzMzNDA5NTM3LjQ1NzYxMywiZXhwIjoxNzMzNDEwMTM3LjQ1BzUzOSwic2FsZXNDaGFubmVsSWQiOiI4ODQzMmRlZjM5ZmM0NjI0YjMzMjEzYTU2YjhjOTQ0ZCJ9.M2GZ6hFFBgQAgoAQAVC--aIG2pl5wytEBBwpCN0UFCw",
  "expires": "2024-12-05T14:48:57+00:00",
  "shopId": "QeqxZlmHpJBvfvDP"
}

Since the endpoint returns a jwt token containing all required data to identify the further requests: salesChannelId and shopId. Therefore using the jwt token should be the only way of authorization, in a request's header. The token is valid for 10 minutes by default.

For example:

const tokenResponse = {
  data: {
    token: "example-jwt",
  },
};

await fetch("https://shopware.mypaymentgateway.com/api/store/card", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${tokenResponse.data?.token}`, // jwt token from the sample code above
  },
  body: JSON.stringify({
    cardId: "card_123",
    tokenId: "some-secret-token_123",
  }),
});