Instant Card Top-Ups

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This guide explains how to implement Instant Card Top-Ups, allowing your customers to fund their Solaris accounts immediately using external debit/credit cards or digital wallets (Google Pay/Apple Pay).

Overview

How it works

The Instant Top-Up feature is a collaboration between Solaris and Stripe (the Acquirer).

1. Collection: Stripe collects the card details and processes the payment in your frontend.
2. Settlement: Solaris credits the funds to the customer's account immediately upon successful authorization.
3. Reconciliation: The actual funds settle from Stripe to Solaris in a background cycle (typically T+2).

To implement this, you must integrate both the Solaris API (for account crediting) and the Stripe SDK (for payment processing).

Product flow

The following sequence diagram illustrates the interaction between your App, Solaris, and Stripe.

User journey

1. Initiation: The customer enters a Top-Up amount in your app.
2. Validation (Client-Side): Perform a soft validation in your UI to ensure the amount is within the allowed limits.
3. Creation: You call Solaris POST /topups. Solaris performs hard validation and returns a Stripe client_secret.
4. Payment: You pass this secret to the Stripe SDK.
   • Recommendation: Use Stripe's PaymentSheet UI component for the best compliance and user experience.
5. Authentication: The customer authorizes the payment (including 3DS challenge if required).
6. Execution: Stripe confirms the payment to Solaris.
7. Crediting: Solaris instantly credits the customer's account.

Prerequisites

Before implementing Top-Ups, ensure you have:

1. Onboarded Customers: Persons with active accounts.
2. Stripe Configuration: Obtained your publishable keys from your Partner Manager.

Apple Pay configuration

If you intend to offer Apple Pay, you must split the configuration between your Apple Developer account and Solaris:

1. Merchant ID: Register an Apple Merchant ID in your Apple Developer account. See Stripe Documentation.
2. Certificates: Contact your Solaris Account Manager. Solaris manages the certificate exchange between your Merchant ID and the Solaris Stripe account.

1. Integrate Stripe SDK

You must implement the Stripe SDK in your mobile or web application to securely collect card data.

Core concepts

• PaymentIntent: The object representing the transaction. Solaris creates this on Stripe's behalf.
• PaymentSheet: Stripe's pre-built UI component. It handles card collection, validation, and 3DS authentication automatically.
• Billing Address: You must pre-fill the billing address in the Stripe SDK using the customer's address stored in Solaris (line1, postal_code, city, country).

SDK resources

Use the official Stripe documentation to install and configure the SDKs.

Handling errors

Your solution must handle errors returned by the Stripe SDK (e.g., card declines, network issues).

• Stripe Error Handling Guide
• Stripe Error Codes
• Card Decline Codes

2. Subscribe to webhooks

Listen for these events to update your UI in real-time.

• Webhook Reference

3. Top-Up lifecycle

Limits and compliance

Ensure your UI respects these limits to prevent unnecessary API errors:

• Transaction Limit: Default 2,000.00 EUR per Top-Up.
• Monthly Cumulative Limit: The maximum total amount a customer can top up per month. This is defined by the Solaris Compliance Team.
• Note: Contact your Partner Manager to confirm the specific limits configured for your solution.

Create a Top-Up

Call this endpoint to initialize the payment. Solaris validates limits and creates the underlying PaymentIntent with Stripe.

Request Parameters:

• amount: The value (in cents) and currency.
• payment_method_id:
  • Set to null for a new card.
  • Set to an existing ID (retrieved from List Payment Methods) to use a saved card.

Response:

• client_secret: Pass this to the Stripe SDK to initialize the PaymentSheet.
• instruction_id: The Solaris reference for this operation.

// POST /v1/persons/{person_id}/accounts/{account_id}/topups
{
  "amount": {
    "value": 10000,
    "currency": "EUR"
  },
  "payment_method_id": null
}

Handle the payment (Client-Side)

Use the client_secret from the response to show the Stripe UI.

• Success: Stripe notifies Solaris -> Solaris triggers ACQUIRER_TOPUP_EXECUTED.
• Failure: Stripe returns an error to your app.

Cancel a Top-Up

If the user cancels the flow or the app crashes, call this endpoint to release the limit reservation.

// POST /v1/persons/{person_id}/accounts/{account_id}/topups/{topup_id}/cancel
{
  "cancellation_reason": "abandoned"
}

4. Manage saved cards

You can allow customers to save their card details for faster future Top-Ups. Solaris retrieves these "Payment Methods" directly from Stripe.

List payment methods

Retrieve all cards stored for a specific customer.

// GET /v1/persons/{person_id}/topups/payment_methods
[
  {
    "person_id": "18de883f507d49b8a074519c73cecper",
    "payment_method_id": "pm_123456789",
    "card_last4": "4242",
    "card_brand": "visa"
  }
]

Delete payment method

Remove a saved card.

// DELETE /v1/persons/{person_id}/topups/payment_methods/{payment_method_id}
{
  "payment_method_id": "pm_123456789"
}

Appendix: Status definitions