Skip to main content

Integrating the Stripe Client-Side SDKs with the API

This guide outlines the steps required to collect and securely save a payment method using Stripe's client-side SDKs in conjunction with our API. This workflow is specifically scoped to creating and saving payment methods for future use, without making an immediate payment.

The integration process consists of four main steps:

  1. Retrieve the Stripe Publishable Key
  2. Retrieve the Stripe Client Secret
  3. Initialize the Stripe Client-Side SDK (Web, Android, or iOS)
  4. Save the Payment Method to our system

Step 1: Retrieve the Stripe Publishable Key​

Before you can initialize the Stripe SDK on your frontend, you need to retrieve our configured Stripe Publishable Key.

Endpoint:

GET /api/employers/{employerId}/employees/{employeeId}/payment-methods/stripe/publishable-key

Description: Returns Stripe's publishable key used to embed the Payment Service Provider's UI components securely.

Example Response:

{
  "publishableKey": "pk_test_..."
}

API Reference for retrieving the Stripe Publishable Key

Step 2: Retrieve the Stripe Client Secret​

To securely save a payment method for a specific employee without charging them, you need a Stripe Setup Intent Client Secret.

Endpoint:

GET /api/employers/{employerId}/employees/{employeeId}/payment-methods/stripe/client-secret

Description: Returns a Stripe client secret tied to a specific Setup Intent for the given employee. This tells Stripe that the intention is strictly to save the payment method for future use.

Example Response:

{
  "clientSecret": "seti_1..._secret_..."
}

API Reference for retrieving a Stripe Client Secret

Step 3: Initialize the Stripe SDK (Platform-Specific)​

Using the Publishable Key (from Step 1) and the Client Secret (from Step 2), initialize the Stripe client-side SDK for your specific platform. You will use these credentials to render Stripe's pre-built UI components, collect the user's payment details, and confirm the Setup Intent directly with Stripe.

Choose your platform below for specific implementation details and official Stripe documentation on saving payment details without an initial charge:

Web (Stripe.js & Elements)​

On the web, you will load Stripe.js, initialize it with the Publishable Key, and mount the Payment Element using the Client Secret.

Android (Stripe Android SDK)​

On Android, you will use the stripe-android SDK. It is recommended to use the PaymentSheet UI for the most seamless integration. You will configure the SDK with the Publishable Key and present the PaymentSheet using the Client Secret.

iOS (Stripe iOS SDK)​

On iOS, you will use the stripe-ios SDK, generally utilizing the Swift PaymentSheet component. Configure the shared StripeAPI with your Publishable Key and initialize the PaymentSheet with your Client Secret.

Step 4: Save the Payment Method​

Once the user completes the flow and Stripe confirms the Setup Intent successfully on the client side, the SDK will return a SetupIntent object to your frontend.

You must extract the setupIntent.id (which begins with seti_...) from that success callback and pass it to our backend API. This finalizes the process by attaching the newly created payment method to the employee in our system.

Endpoint:

POST /api/employers/{employerId}/employees/{employeeId}/payment-methods/stripe

Description: Creates a payment method in the Paytient system from the completed Stripe Setup Intent.

Request Body:

{
  "setupIntentId": "seti_1..."
}

Example Response: The API will return the successfully created PaymentMethodResponse object.

{
  "id": 1,
  "type": "CardCredit",
  "name": "Bank Of America",
  "description": "My debit account.",
  "lastFour": "1234",
  "expiration": {
    "month": 1,
    "year": 2022
  },
  "paymentMethodStatus": "Verified"
}

API Reference for creating a Payment Method from a Stripe Setup Intent