How to Checkout with Stripe

This guide explains how to implement a complete checkout flow using the Jay Basket API with Stripe integration. The checkout process involves coordinating between your client application and the Jay Basket API, with Stripe handling the payment processing.

Overview

The Jay platform uses Stripe as the payment service provider (PSP) for processing payments. This integration follows a server-side approach where the Jay Basket API communicates directly with Stripe for payment processing, while your client application handles the user interface and payment method collection.

Requirements

Before implementing checkout functionality, ensure that:

• Product Availability: For products with limited inventory, check stock availability using the Product Details endpoint before proceeding with checkout.
• Size Variants: For products with variants (like sizes), ensure a specific variant is selected. Size selection is required for checkout of applicable products.
• Basket Setup: Products must be properly added to the user's basket using the Basket API before initiating checkout.
• Stripe Integration: Your application must include the appropriate Stripe SDK for your platform (Web, iOS, or Android).
• Authentication: Your integration must have valid authentication credentials for the Jay Basket API.

Detailed Checkout Flow

1. Prepare the Basket

Before initiating checkout, ensure all products in the basket have appropriate variants selected (if applicable):

// Check if product has variants that need to be selected
POST /v2/baskets/products/details
Content-Type: application/json

[
  "product-789"
]

// Response will show available variants
{
  "products": [
    {
      "productId": "product-789",
      "name": "T-Shirt",
      "sizes": [
        {
          "id": "size-S",
          "short": "S",
          "long": "Small",
          "currentStockCount": 5,
          "availability": "AVAILABLE"
        }
        // More variants...
      ]
    }
  ]
}

2. Start Checkout Session

Initiate the checkout process by calling the Basket API to create a checkout session:

// Request
POST /v2/baskets/users/{userId}/checkout/sessions
Content-Type: application/json

{
  "mode": "test"  // Optional: Use "test" or "live". If omitted, the default mode for your tenant is used
}

// Response
{
  "sessionId": "cs_123456789",
  "stripe": {
    "publishableKey": "pk_test_1234567890abcdef",
    "clientSecret": "pi_1234_secret_5678",
    "accountId": "acct_12345"
  },
  "amount": {
    "total": "49.99",
    "currency": "EUR",
    "shipping": "5.00",
    "tax": "7.96"
  }
}

The response contains all necessary information to proceed with the checkout, including:

• Stripe publishable key for your environment (test or live)
• Client secret for the Stripe Payment Intent
• Total amount breakdown including shipping and taxes

3. Present Payment Summary

Display an order summary to the user showing:

• Products in the checkout
• Pricing details including subtotal, shipping costs, and taxes
• Total amount to be charged

4. Collect Customer Information

Gather required customer information for order fulfillment:

• Shipping address
• Billing address (if different from shipping)
• Contact E-mail

5. Initialize Stripe Payment

Use the Stripe SDK to initialize the payment flow using the client secret from step 2:

// Web example using Stripe.js
const stripe = Stripe(response.stripe.publishableKey, {
  stripeAccount: response.stripe.accountId
});

const elements = stripe.elements({
  clientSecret: response.stripe.clientSecret
});

// Create and mount the Payment Element
const paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

6. Handle Payment Submission

When the user submits their payment details, use the Stripe SDK to process the payment:

// Web example using Stripe.js
const result = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: 'https://yourapp.com/checkout/complete',
  },
});

if (result.error) {
  // Handle error
} else {
  // Payment processing has started
  // The actual payment completion is handled by Stripe webhooks on the Jay Basket API
}

7. Complete or Cancel Checkout

After payment processing (or if the user cancels), notify the Jay Basket API about the outcome:

// Request - Success case
POST /v2/baskets/users/{userId}/checkout/sessions/finish-active
Content-Type: application/json

{
  "status": "success"
}

// Request - Failure or cancellation case
POST /v2/baskets/users/{userId}/checkout/sessions/finish-active
Content-Type: application/json

{
  "status": "cancelled"
}

8. Handle Webhook Processing

The final payment validation and order processing is handled automatically by the Jay Basket API through Stripe webhooks. Your integration does not need to implement this step, but you should be aware that:

• The basket remains locked until the checkout is completed or cancelled
• Order processing only happens after successful payment validation via webhooks
• Your client application cannot trigger a real order by itself

Stripe Integration Resources

For detailed information on integrating Stripe's SDKs, refer to the official Stripe documentation:

• Payment Intents API - Core concept for processing payments
• Stripe SDK Overview - Available SDKs for different platforms
• Stripe.js and Elements - For web integrations
• Stripe iOS SDK - For iOS integrations
• Stripe Android SDK - For Android integrations

Testing Checkout Implementation

Before going live, thoroughly test your checkout implementation using Stripe's test mode:

• Use test cards provided by Stripe to simulate different payment scenarios
• Test both successful payments and failure cases
• Verify that your integration properly handles checkout session completion and cancellation

For comprehensive testing best practices, refer to Stripe's testing documentation, which covers simulating authentication flows, testing international cards, and handling various payment scenarios.

For detailed information on configuring and using the test mode of our system, which allows you to safely implement the checkout flow without triggering real transactions or orders, see the How to Test Checkout guide.

Common Issues and Troubleshooting

• Session Expiration: Checkout sessions expire after 30 minutes. If a user takes longer than this to complete checkout, they will need to start a new session.
• Product Stock Changes: If stock availability changes during checkout, the Basket API will handle this automatically, but you should inform the user if their order cannot be fulfilled.
• Payment Failures: Handle payment failures gracefully by providing clear error messages and allowing users to try again with different payment methods.

Next Steps

After successfully implementing and testing the checkout flow, follow these steps:

1. Test your integration thoroughly using the test mode
2. Request activation for production use
3. Monitor live checkouts during initial rollout
4. Implement analytics to track conversion rates and identify potential issues