Payments Frontend Setup

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:

Entity	Role	Description
Setup Intent	Primary	A 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 Intent	Secondary	A 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.).

In the event of a backend billing failure, the user must proceed with a manual payment via the Stripe SDK to confirm the 3DS operation (payment intent).

---

3. Production Implementation (setup intent)

🍏 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.
• 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.
  • Skip “Recurring payments” tab.
  • Skip “Order tracking” chapter.
• 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.
• Enable Google Pay:
  • Registration in the Google Pay & Wallet Console is required for production.
  • Review the Google frontend integration guide. Passing Google Pay review is required to access production payments.
  • Note: Your app must be uploaded to at least the Internal Track in the Google Play Console to appear in the Google Pay Console.
• Logout: Ensure you handle user logout correctly.

💻 Web

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

⚛️ 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 TEST 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 Number	Behavior
4242 4242 4242 4242	Frictionless addition and payment.
4000 0027 6000 3184	Requires 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.