External Services Integration

External Services Integration

Project: {{PROJECT_NAME}}Drop Version: {{VERSION}}0.1.0 Date: {{DATE}}2026-02-23 Author: {{AUTHOR}}Platform Architect (AI) Status: Draft | In Review | Approved Reviewers: {{REVIEWERS}}Alem Bašić (CEO)

Document History

1. Integration InventoryOverview

Drop integrates with the following external services. Service mode is controlled by NEXT_PUBLIC_SERVICE_MODE env var (mock | production).

Key rule: Sumsub is the ONLY connected external service with real API calls. All other services except BankID and Slack are currently mocked.

2. BankID OIDC — Norwegian eID

2.1 Purpose

BankID is Drop's sole authentication mechanism. All users must authenticate with Norwegian BankID (eID) before accessing any features. This satisfies PSD2 Strong Customer Authentication (SCA) requirements.

2.2 Integration Details

2.3 Environment Variables

2.4 Mock Mode (BANKID_MOCK=true)

In development and staging, BANKID_MOCK=true enables a simulated BankID flow:

• Skips the full OIDC redirect
• Auto-generates a mock pid and authenticates a test user
• No network calls to BankID

2.5 Error Handling

3. Sumsub — KYC / Identity Verification

3.1 Purpose

Sumsub provides KYC (Know Your Customer) identity verification. This is the only production-ready external service with real API calls.

Verification checks:

• Document authenticity (passport, ID card, driver's license, residence permit)
• Liveness check (selfie is a real person)
• Face match (selfie matches document photo)
• Sanctions check (not on international sanctions lists)
• PEP check (not a politically exposed person)

3.2 Integration Architecture

User app (web/mobile)
  │
  ├── 1. GET /api/kyc/initiate → server calls Sumsub createApplicant + getAccessToken
  │                               returns { token } for WebSDK
  │
  ├── 2. Frontend loads Sumsub WebSDK with token
  │       User submits documents + selfie via Sumsub UI
  │
  └── 3. Sumsub webhook → POST /api/kyc/webhook
          Server updates user.kyc_status = 'approved' | 'rejected'

3.3 Key Functions

3.4 Applicant Status Flow

init → pending → queued → completed → (reviewAnswer: GREEN=approved / RED=rejected / RETRY)

3.5 Environment Variables

3.6 Mock Mode

When NEXT_PUBLIC_SERVICE_MODE=mock:

• 90% approval rate, 10% rejection
• 3-second simulated delay
• Risk score: 15 (approved) or 85 (rejected)
• Rejected label: DOCUMENT_UNREADABLE, type: RETRY

3.7 Error Handling

4. Open Banking — AISP + PISP (Provider TBD)

4.1 Purpose

• AISP (Account Information): Read user's bank balance from their Norwegian bank account
• PISP (Payment Initiation): Initiate transfers directly from user's bank account

This is Drop's core PSD2 architecture — users' funds never move into Drop's control.

4.2 Current State

Criticality

4.3 definitions:

Planned

Integration
• Critical:Architecture

User outageinitiates causespayment
  complete│
  feature├── failure1. forAISP: endRefresh usersbalance 
High:from Servicebank outage→ degradesupdate corebank_accounts.balance
  functionality
├── 
Medium:2. ServicePISP: outageInitiate affectspayment non-criticalat features
provider 
Low:→ Monitoring/internalreturns toolspayment_id
  —├── no3. User bank sends consent redirect if needed
  ├── 4. Provider webhook: payment settled → update transaction.status
  └── 5. Notify user
impact



2. Per-Service Integration

2.14.4 StripeRequired Environment Variables (Payments)Future)

4.5 Supported Banks (Target)

Norwegian banks supporting PSD2 (via Open Banking provider):

• DNB
• Nordea
• Handelsbanken
• SpareBank 1
• Sbanken / DNB (merged)

5. Slack — Operational Alerting

5.1 Purpose

Slack receives operational alerts from Drop's internal alerting system (src/lib/alerts.ts).

Channel: #drop-ops on alai-talk.slack.com

5.2 Alert Types

5.3 Integration Details

Key

5.4 endpointsEnvironment used:

Variables

Request example:

const paymentIntent = await stripe.paymentIntents.create({
  amount: 1000, // in cents
  currency: 'nok',
  customer: customer.stripeId,
  metadata: { orderId, userId },
  automatic_payment_methods: { enabled: true },
});

Error handling:

try {
  await stripe.paymentIntents.create(params);
} catch (err) {
  if (err instanceof Stripe.errors.StripeCardError) {
    throw new PaymentDeclinedException(err.message);
  }
  if (err instanceof Stripe.errors.StripeRateLimitError) {
    throw new ServiceTemporarilyUnavailableException('Payment service rate limited');
  }
  // Log unexpected errors to Sentry
  this.sentry.captureException(err);
  throw new PaymentServiceException('Unexpected payment error');
}

Retry policy: Stripe SDK handles retries on network errors automatically. Business-level failures (card declined) are NOT retried.

Circuit breaker: {{Yes — breaker trips after 5 consecutive failures, opens for 30s}}

Fallback: No fallback for payments — fail clearly with user-facing error message.

Webhooks consumed:

Rate

5.5 limits:Alert 100Format

🚨 requests/s,Drop 100Production writeAlert requests/s— perCritical

secretTitle: key.Error Cost:spike Perdetected
transactionMessage: (see8 Finance:errors Stripein billingthe dashboard).
last 60 seconds

Time: 2026-02-23 14:30 UTC

6. BetterStack — External Uptime Monitoring

2.6.1 Purpose

BetterStack provides external uptime monitoring independent of Drop's infrastructure — detects total infrastructure failures that internal health checks miss.

6.2 SendGridMonitors (Email)Configured

Key

6.3 operations:

Alert

Operation	Template	Trigger
Welcome email	d-XXXX	User registration
Password reset	d-XXXX	Forgot password flow
Order confirmation	d-XXXX	Order placed
Invoice	d-XXXX	Invoice generated

Request example:

Escalation

awaitMinute sgMail.send({0:   to:DOWN user.email,→ from:Slack {#drop-ops
email:Minute '[email protected]',5:   name:Still '{{APP_NAME}}'down },→ templateId:Email 'd-XXXXXXXXXXXXXXXXXXXXXX',[email protected]
dynamicTemplateData:Minute {15:  firstName:Still user.name.split('down ')[0],→ orderNumber:SMS order.number,+47 orderTotal:40 formatCurrency(order.total),47 },42 });51 (requires paid plan)

6.4 Status Page

ErrorPublic handling:status page: https://drop-status.betteruptime.com

Setup guide: trydocs/infrastructure/BETTERSTACK-SETUP.md
{

await
7. sgMail.send(message);Deprecated }Services
catch
Swan Open Banking (err) {
  if (err.code === 429) {
    // Queue for retry
    await this.emailQueue.add('retry_email', message, { delay: 60000 });
  } else {
    this.logger.error('SendGrid error', { code: err.code, message: err.message });
    // Don't throw — email failure is non-critical for most flows
  }
}

Retry policy:Status: 3 retries via BullMQ queue with 60s, 300s, 900s backoff. Fallback: {{Postmark as backup SMTP | Log and alert teamDEPRECATED — no fallback}}longer the planned Open Banking provider. Mock code exists at services/mock-swan.ts but will be removed.

const command = new PutObjectCommand({
  Bucket: process.env.S3_UPLOADS_BUCKET,
  Key: `${userId}/${ulid()}.${extension}`,
  ContentType: mimeType,
  ContentLength: fileSize,
});

const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 900 });

// TODO:Called Addonce representative request example

// TODO: Define error handling strategy

// services/stripe.service.ts — abstraction over Stripe SDK
@Injectable()
export class StripeService {
  // Exposes only operations theon app actuallystartup
needsawait // Hides Stripe-specific implementation details
  // Makes testing easier (injectable, mockable)
  async createPaymentIntent(amount: number, currency: string): Promise<PaymentIntent> { ... }
}

// __mocks__/@sendgrid/mail.ts
const sendMock = jest.fn().mockResolvedValue([{ statusCode: 202 }]);
export default { send: sendMock, setApiKey: jest.fn() };

// In tests import— sgMailreset fromall '@sendgrid/mail';mock expect(sgMail.send).toHaveBeenCalledWith(expect.objectContaining({state
templateId: 'd-XXXXX',
})resetMockServices();