FinBank Connect: Documentation for a Secure Payments API

Simulated project — RESTful banking API for EU FinTech platforms

A full documentation suite for a fictional payments API, built as if for a real EU-based FinTech: developer-facing API docs, plus the compliance and accessibility thinking that financial services documentation actually requires.

What FinBank Connect does: lets FinTech platforms securely connect with banks, initiate payments, retrieve balances, and manage KYC workflows via API. It serves developers integrating banking functionality, compliance officers checking GDPR and PSD2 readiness, and product managers overseeing onboarding.

Contents

1. My role

2. The problems I had to solve

3. Process

4. What I'd validate

5. Documentation sample: quick-start guide

6. Sample: UX microcopy for financial edge cases

My role

Sole writer. Created the documentation suite from scratch, led content strategy across developer and end-user audiences, and worked through what accessibility-compliant, PSD2-aware documentation actually requires rather than treating compliance as a checkbox at the end.

The problems I had to solve

Legal-to-human translation: PSD2, GDPR, and KYC requirements are written for regulators, not developers. Every compliance requirement in the docs had to be translated into something a developer could act on without a legal background.

Multi-audience navigation: a developer, a compliance officer, and a PM reading the same doc need different things from it. I solved this by segmenting content by task rather than by audience label, so the developer quick-start and the compliance overview don't compete for the same page.

Security-aware writing: every workflow needed to model secure defaults in the copy itself, not just describe them, since documentation that shows an insecure example teaches an insecure pattern regardless of what the surrounding text says.

Process

• Reviewed how Stripe, Plaid, and Revolut structure their API docs before writing anything

• Read the PSD2/RTS source material directly rather than working from a summary, to catch nuance that gets lost in translation

• Designed for screen-reader compatibility and avoided red/green-only status indicators, since color-blind-safe status communication isn't optional in financial services

• Wrote inclusive microcopy for financial edge cases specifically, "Unverified User" and "Failed KYC Check" needed to be clear without being alarming

What I'd validate

• Time from reading the quick-start guide to a developer's first successful sandbox payment

• Whether compliance officers can answer "is this PSD2-compliant" from the docs alone, without a follow-up call to engineering

• Support ticket volume for KYC-rejection and payment-failure flows, since confusing error copy in a financial product creates real anxiety, not just friction

Documentation sample: quick-start guide

"Integrate Secure Payment Flow in 10 Minutes" — audience: developers integrating the API for the first time.

1. Get your API keys and authenticate

POST /oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

POST /oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

POST /oauth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

// Response
{
  "access_token": "eyJ...xyz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

// Response
{
  "access_token": "eyJ...xyz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

// Response
{
  "access_token": "eyJ...xyz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

2. Choose your environment

Use the sandbox base URL (sandbox.finbankconnect.io) while testing. Nothing initiated here touches real funds. Switch to api.finbankconnect.io only once you're ready for production traffic.

3. Sample use case: send €200 to a verified user

// POST /payments
{
  "amount": 200.00,
  "currency": "EUR",
  "recipient_id": "usr_verified_882",
  "reference": "Invoice #4471"
}

// POST /payments
{
  "amount": 200.00,
  "currency": "EUR",
  "recipient_id": "usr_verified_882",
  "reference": "Invoice #4471"
}

// POST /payments
{
  "amount": 200.00,
  "currency": "EUR",
  "recipient_id": "usr_verified_882",
  "reference": "Invoice #4471"
}

4. Common errors and fixes

Sample: UX microcopy for financial edge cases

• Payment success: "Transfer complete. Your funds are on the way."

• KYC rejection: "Verification failed. Please check that your photo ID is clear and legible."

• Onboarding: "Welcome to FinBank Connect. Let's get your account set up in 3 quick steps."

Key takeaway

Clarity beats completeness. The most useful financial documentation isn't the most exhaustive, it's the version that tells a developer, a compliance officer, and a nervous end user exactly what they need to know, in language built for each of them.