​
How Mona Works

Mona’s architecture is built on Strong Customer Authentication (SCA) using cryptographic signatures from on-device credentials. Every sensitive operation—whether consenting to future collections or making payments—is cryptographically signed using passkeys or private keys stored securely on the user’s device.

This cryptographic foundation provides unparalleled security, but the complexity is completely abstracted away by our SDKs. You get enterprise-grade authentication without any of the implementation complexity.

Our architecture follows a secure two-step pattern that separates backend operations from client-side implementation. This ensures your sensitive API keys never leave your server while providing seamless user experiences in your apps and websites.

​
Strong Customer Authentication (SCA)

At the heart of every Mona interaction is Strong Customer Authentication. This isn’t just about passwords or SMS codes—it’s about cryptographic proof that the user is who they claim to be and that they genuinely intend to perform the action.

​
🔐 Cryptographic Signatures

  • Every payment and collection consent is cryptographically signed
  • Uses on-device credentials like passkeys, biometrics, or secure private keys
  • Cannot be replicated, intercepted, or faked by malicious actors
  • Provides non-repudiation: mathematical proof of user intent

​
🛡️ What Gets Authenticated

  • Payment Authorization: Every transaction requires cryptographic consent
  • Collection Consent: Recurring payment permissions are cryptographically signed
  • Account Linking: Bank account connections use secure authentication
  • Sensitive Updates: Any account changes require re-authentication

​
✨ SDK Abstraction

The SDKs handle all the cryptographic complexity:

  • Automatic Key Management: Generate, store, and manage cryptographic keys
  • Secure Signing: Handle all cryptographic operations transparently
  • Cross-Platform: Same security level across Web, iOS, Android, Flutter
  • Fallback Handling: Graceful degradation when hardware security isn’t available
  • Compliance: Built-in PSD2, PCI DSS, and regulatory compliance

You get bank-level security without writing a single line of cryptographic code.

​
The Two-Key System

​
🔒 Private API Key (Backend Only)

  • Used for all server-side API calls
  • Never exposed to client applications
  • Authenticates requests to create transactions, collections, etc.
  • Format: x-api-key: your_private_key

​
🌐 Public Key (Client-Side)

  • Used to initialize SDKs in your apps/websites
  • Safe to include in client-side code
  • Loads your merchant branding and configuration
  • Format: mona_pub_xxxxx

​
The Integration Flow

Every Mona integration follows this secure pattern:

​
Step 1: Backend Creates Resource

Your server uses the private API key to create a resource and get an ID:

Examples:

  • Checkout: Create transaction → Get transactionId
  • Collections: Create collection → Get collectionId
  • Identification: Create verification → Get verificationId

​
Step 2: Client Uses Resource

Your app/website uses the public key + resource ID to initialize the SDK:

​
Practical Examples

​
Checkout Flow

// 1. Backend: Create transaction
POST /pay/create
Headers: x-api-key: your_private_key
Body: { amount: 5000, phone: "1234567890" }
Response: { transactionId: "txn_abc123", url: "..." }

// 2. Client: Initialize SDK
PayWithMona.initialize({ merchantKey: 'mona_pub_xyz' });
<PayWithMona 
  transactionId="txn_abc123"
  // ... other props
/>

​
Collections Flow

// 1. Backend: Create collection
POST /collections
Headers: x-api-key: your_private_key
Body: { 
  maximumAmount: "600",
  schedule: { type: "SCHEDULED", frequency: "MONTHLY" }
}
Response: { id: "col_def456" }

// 2. Client: Initialize SDK
useCollections({
  onSuccess: () => console.log("Collection setup successful!")
});
// Then call: initiate("col_def456")

​
Getting Your Keys

During onboarding, the Mona team will provide:

  1. Private API Key: For server-side API calls

    • Sandbox: mona_sk_sandbox_xxxxx
    • Production: mona_sk_prod_xxxxx

  2. Public Key: For client-side SDK initialization

    • Sandbox: mona_pub_sandbox_xxxxx
    • Production: mona_pub_prod_xxxxx

​
Next Steps

  1. Choose Your Component: Checkout or Collections
  2. Implement Backend: Use the API reference to create resources
  3. Integrate SDK: Follow platform-specific guides for your app
  4. Test End-to-End: Verify the full flow in sandbox environment