Stripe

ShipAny integrates Stripe as a payment service provider, allowing you to access it with simple configuration.

Integrate Stripe Payment

Follow these steps to integrate Stripe payment for your project.

Design Pricing Table

The default pricing table is configured in the src/config/locale/messages/{locale}/pricing.json file, which supports multiple languages. Each locale corresponds to an independent pricing table configuration.

The pricing.groups field defines the pricing plan groups, with default values as follows:

{
  "pricing": {
    "groups": [
      {
        "name": "one-time",
        "title": "Pay as you go"
      },
      {
        "name": "monthly",
        "title": "Monthly",
        "is_featured": true,
        "label": "save 15%"
      },
      {
        "name": "yearly",
        "title": "Annually"
      }
    ]
  }
}

• name: The unique identifier of the group. In pricing.items, each pricing plan is associated with the group name through the group field.
• title: The display name of the group.
• is_featured: Whether it is a recommended group. If true, this group and the recommended pricing plans it contains will be displayed by default.
• label: The label of the group. It is displayed as a badge in the upper right corner of the display name.

The pricing.items field defines the list of pricing plans. The data structure of one of the default pricing plans is as follows:

{
  "pricing": {
    "items": [
      {
        "title": "Starter",
        "description": "Get started with your first SaaS startup.",
        "features_title": "Includes",
        "features": [
          "100 credits, valid for 1 month",
          "NextJS boilerplate",
          "SEO-friendly structure",
          "Payment with Stripe",
          "Data storage with Supabase",
          "Google Oauth & One-Tap Login",
          "i18n support"
        ],
        "interval": "one-time",
        "amount": 9900,
        "currency": "USD",
        "price": "$99",
        "original_price": "$199",
        "unit": "",
        "is_featured": false,
        "tip": "Pay once. Build unlimited projects!",
        "button": {
          "title": "Get ShipAny",
          "url": "/#pricing",
          "icon": "RiFlashlightFill"
        },
        "product_id": "starter",
        "product_name": "ShipAny Boilerplate Starter",
        "credits": 100,
        "valid_days": 30,
        "group": "one-time"
      }
    ]
  }
}

• title: Pricing plan title.
• description: Pricing plan description.
• features_title: Pricing plan feature list title.
• features: Pricing plan feature list.
• interval: Pricing plan billing cycle. Possible values are one-time (one-time payment), month (monthly subscription), year (annual subscription).
• amount: Pricing plan amount. This value is used to request a Stripe order, unit: cents.
• currency: Pricing plan currency. Possible values are USD (US Dollar), CNY (Chinese Yuan), etc.
• price: The displayed selling price of the pricing plan.
• original_price: The displayed original price of the pricing plan. With strikethrough effect.
• unit: The displayed unit of the pricing plan. Such as / month, / year, etc.
• is_featured: Whether it is a recommended pricing plan. If set to true, it will be displayed by default in the pricing table.
• tip: Order tip.
• button: Order button. You can customize the display text title and icon icon. url is currently a placeholder and has no actual effect.
• product_id: Unique identifier of the pricing plan. The backend interface locates the pricing plan based on this parameter when placing an order. Please ensure that the product_id of each pricing plan is unique.
• product_name: Pricing plan name.
• credits: The number of credits purchased. If it is not a scenario for purchasing credits, it can be set to 0.
• valid_days: The validity period of the credits in days. Monthly credits can be set to 30, and annual one-time credits can be set to 365.
• group: The group to which the pricing plan belongs. Associated with name in pricing.groups.

Please refer to the default pricing table configuration, modify the corresponding field content, and design the pricing table according to your project requirements.

Note: If your project supports multiple languages, please modify the pricing table configuration corresponding to each locale.

After selecting a pricing plan, the interface for requesting an order is /api/payment/checkout. Example request parameters:

{
  "product_id": "starter",
  "currency": "USD",
  "locale": "en",
  "payment_provider": "stripe",
  "metadata": {}
}

• product_id: Unique identifier of the pricing plan. The order interface locates the pricing plan based on this parameter.
• currency: Order currency. Can be selected by the user, default is USD.
• locale: Order language. Pass the user's currently selected page locale. The order interface locates the pricing table configuration based on this parameter.
• payment_provider: Payment provider.
• metadata: Payment metadata. Custom parameters can be passed.

Note: After modifying the pricing table configuration, visit the /pricing page to view the new pricing table. Select a pricing plan to place an order. After successful payment, verify the payment record on the /settings/payments page, checking if the payment amount, currency, and billing cycle are consistent with the configured pricing plan. Check the credit issuance record on the /settings/credits page, verifying if the credit amount and expiration time (payment time + valid days) are consistent with the configured pricing plan.

Configure Payment Callback

After the user selects a pricing plan and successfully places an order on the pricing table page, they will be redirected to the Stripe payment page. After successful payment, they will be redirected to the project's callback interface: /api/payment/callback.

In the callback interface, the order status will be updated based on the order number, and then redirected to the configured callbackUrl.

This configured callbackUrl is specified in the order interface: /api/payment/checkout:

const callbackUrl =
  paymentType === PaymentType.SUBSCRIPTION
    ? `${callbackBaseUrl}/settings/billing`
    : `${callbackBaseUrl}/settings/payments`;

According to the default configuration, if it is a one-time payment, it will eventually redirect to the /settings/payments page; if it is a subscription payment, it will eventually redirect to the /settings/billing page.

You can modify the redirect address after user payment completion according to project requirements.

Note: Payment callback is a synchronous redirect. If the user confirms payment on the Stripe payment page but closes the browser before the page redirects, failing to redirect to the project callback interface normally, the order status cannot be updated, and the user cannot see the paid order in the personal center. This situation is called: Lost Order.

To avoid the Lost Order situation in payment callbacks, it is recommended to configure payment notifications in the Stripe backend when the project is online.

Configure Payment Notification

# Checkout completed
checkout.session.completed
# Payment succeeded
invoice.payment_succeeded
# Payment failed
invoice.payment_failed
# Subscription updated
customer.subscription.updated
# Subscription cancelled
customer.subscription.deleted

https://{your-domain.com}/api/payment/notify/stripe

Local Debugging of Payment Notification

When configuring payment notifications in the previous step, the filled Endpoint URL must be a publicly accessible https address.

Before the project is deployed online, it is necessary to debug locally first, receive payment notification content, and make necessary modifications and verifications.

Through Intranet Penetration, a public network address can be mapped to a local development machine. The following steps mainly demonstrate using ngrok to implement Intranet Penetration.

brew install ngrok

ngrok config add-authtoken {your-authtoken}

pnpm dev --port 8080

ngrok http 8080

https://9d897275dabf.ngrok-free.app/api/payment/notify/stripe

After configuring the payment notification according to the above steps, select a pricing plan on the pricing table page to place an order, and you can receive Stripe payment notifications locally.

The default payment notification processing logic is in the src/app/api/payment/notify/[provider]/route.ts file. You can modify the corresponding logic according to project requirements.

Custom Payment Options

You can customize payment options according to project requirements based on the examples listed below.

Multi-currency Payment

When Designing Pricing Table, use the currency field in the pricing plan to specify the order currency. For example, Original price 199 USD, marked price 99 USD, the corresponding pricing plan configuration is:

{
  "amount": 9900,
  "currency": "USD",
  "price": "$99",
  "original_price": "$199"
}

If you want to allow users to select different currencies for ordering on the pricing table page, you can refer to the following configuration:

{
  "amount": 9900,
  "currency": "usd",
  "price": "$99",
  "original_price": "$199",
  "currencies": [
    {
      "currency": "cny",
      "amount": 69900,
      "price": "¥699",
      "original_price": "¥1399"
    }
  ]
}

After configuration, you can see that the pricing plan has an option to switch currencies. In the pricing plan configuration, the outer currency is the default currency, and the currency inside currencies is the switchable currency.

Note: The currency field is case-insensitive, and the amount unit is: cents.

WeChat / Alipay Payment

Follow these steps to enable WeChat / Alipay payment in your project.

{
  "amount": 69900,
  "currency": "cny",
  "price": "¥699",
  "original_price": "¥1399"
}

{
  "amount": 9900,
  "currency": "usd",
  "price": "$99",
  "original_price": "$199",
  "currencies": [
    {
      "currency": "cny",
      "amount": 69900,
      "price": "¥699",
      "original_price": "¥1399"
    }
  ]
}