Payments Frontend Setup

Documentation Index

Fetch the complete documentation index at: https://docs.cariqa.com/llms.txt

Use this file to discover all available pages before exploring further.

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:

---

​

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. 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.