Skip to main content
The Cariqa Connect API eliminates the need to implement Stripe server-side logic. Consequently, you only need to configure Stripe for the frontend. This guide provides the high-level configuration required to handle the use cases supported by the platform, including the Playground Reference Client.

​
1. Preamble: The Payment Lifecycle

The Cariqa Platform operates on a post-payment flow. Although we utilize payment pre-authorization, the final charge may exceed this amount. Therefore, a user must have a valid payment method attached at:
  • The moment the session begins.
  • The moment the platform receives the Charge Detail Record (CDR) to bill the user for the actual usage.
This ensures the platform can either return the unused pre-authorization amount or bill the user for any additional charges.

​
2. Intent Entities: Setup vs. Payment

Stripe utilizes two primary entities to manage transaction flows:
EntityRoleDescription
Setup IntentPrimaryA user-specific token used to attach a payment method to Stripe. The Connect API generates this via the Stripe Admin API. Every user is required to add a payment method via this intent.
Payment IntentSecondaryA user-specific token for frontend-initiated payments. While Cariqa primarily uses backend billing (via Setup Intents), a Payment Intent is generated if a charge fails due to specific payment method restrictions (insufficient funds, 3DS confirmation, etc.).

​
3. Production Implementation (setup intent)

Stripe publishableKey (dev/prod modes) required for the front-end are provided during the onboarding process.
The Stripe publishable key is public by design, so it’s safe to expose in client apps. Even so, our strong recommendation is to fetch it from your backend at runtime rather than bundling it into the app. This keeps it ready for a hot-swap if it ever needs to be rotated — without having to re-release your mobile app.

​
🍏 Mobile iOS (Cards + Apple Pay)

Refer to the official Stripe Payment Sheet iOS guide. The “Server-side” chapters are not required for this integration.
  • Set up Stripe (client-side): Install the SDK.
  • Collect payment details
    • Payment Details: You do not need to provide customer or customerSessionClientSecret.
    • Intent Usage: Use setupIntent instead of paymentIntent to add a payment method.
    • Skip allowsDelayedPaymentMethods.
    • Disable billing details collection in Stripe’s UI. Instead, collect and display billing details in your own UI if needed.
configuration.billingDetailsCollectionConfiguration.name = .never
configuration.billingDetailsCollectionConfiguration.email = .never
configuration.billingDetailsCollectionConfiguration.phone = .never
configuration.billingDetailsCollectionConfiguration.address = .never
  • Set up a return URL: Ensure a return URL is configured.
  • Enable Apple Pay:
    • Certificate creation requires interaction with the Cariqa team.
    • We will provide the stripe.certSigningRequest for you to upload to the Apple Developer Portal.
    • Upload the resulting apple_pay.cer back to us to register it with Stripe.
    • Use the following item, adding your app name to the label:
paymentSummaryItems: [
  PKPaymentSummaryItem(
    label: "Authorisation for Your App Name",
		amount: 0.00,
		type: .pending
	)
]
  • Skip “Recurring payments” tab.
  • Skip “Order tracking” chapter.
  • Enable card scanning: Optional, but without a permission description it may cause an error during App Store distribution.
  • Customize the sheet: Optional: apply the desired styling.
  • Handle user logout: Ensure you handle user logout correctly.

​
🤖 Mobile Android (Cards + Google Pay)

Refer to the official Stripe Payment Sheet Android guide. The “Server-side” chapters are not required.
  • Set up Stripe (client side): Skip the financial-connections import.
  • Collect payment details:
    • Payment Details: You do not need to provide customer or customerSessionClientSecret.
    • Intent Usage: Use setupIntent instead of paymentIntent to add a payment method.
    • Skip allowsDelayedPaymentMethods.
    • Disable billing details collection in Stripe’s UI. Instead, collect and display billing details in your own UI if needed.
val billingDetailsConfig = PaymentSheet.BillingDetailsCollectionConfiguration(
  name = PaymentSheet.BillingDetailsCollectionConfiguration.CollectionMode.Never,
  email = PaymentSheet.BillingDetailsCollectionConfiguration.CollectionMode.Never,
  phone = PaymentSheet.BillingDetailsCollectionConfiguration.CollectionMode.Never,
  address = PaymentSheet.BillingDetailsCollectionConfiguration.AddressCollectionMode.Never
)  

val googlePayConfiguration = PaymentSheet.GooglePayConfiguration(
    // ...
    countryCode = "DE",
    currencyCode = "EUR",
    amount = 0, 
    label = "Authorisation for Your App Name"
)
  • Note: Your app must be uploaded to at least the Internal Track in the Google Play Console to appear in the Google Pay Console.
  • Customize the sheet: Optional: apply the desired styling.
  • Handle user logout: Ensure you handle user logout correctly.

​
💻 Web (Cards + Google Pay)

Stripe provides a dedicated guide for Stripe Elements Guide. As with other platforms, the server-side implementation chapters should be ignored.

Credit Cards: No specialized configuration is required.
Apple/Google Pay: You must share your production domain with the Cariqa team.
  • Collect payment details:
    • Skip Collect addresses
    • Skip Request Apple Pay merchant token
  • Apple Pay and Google Pay: these payment methods are already enabled in the Stripe account — ensure they are added (or not disabled) in the PaymentElement initialization config.

​
⚛️ React Native

Stripe provides a dedicated guide for React Native. As with other platforms, the server-side implementation chapters should be ignored.

​
4. Testing the Integration

Use the following test cards in the DEV environment. For Apple Pay and Google Pay, you can use a simulator or real device; no real charges will be made, and the card will be replaced with the *4242 test card.
Card NumberBehavior
4242 4242 4242 4242Frictionless addition and payment.
4000 0027 6000 3184Requires manual 3DS confirmation for both setup and payment (useful for edge cases).
More Stripe testing cards here.

​
5. Manual Payment Confirmation (payment intent)

If the backend fails to process a payment (e.g., due to insufficient funds or a requirement for user authentication), the frontend will receive a Payment Intent. This intent must then be passed to the Stripe SDK. For implementation details, refer to the Outstanding payments documentation.