Simpaisa API Migration Roadmap

Owner	Classification	Review Date	Status
Architecture Practice	Internal	April 2027	Active

Simpaisa API Migration Roadmap

Version: 1.0.0-draft
Date: 2026-04-03
Owner: CDO / Architecture
Status: Proposed — nothing formally decided; all phases are subject to revision
Applicability: All Simpaisa API products — Pay-Ins, Pay-Outs (Disbursements), Remittances, Cards

Note: This document is a prototype and showcase of what is possible with an AI SDLC and Claude-driven architecture process. The engineering organisation will be restructured as required to support an agentic AI SDLC-first approach. Breaking change tolerance, merchant counts per product, and final gateway selection are TBD — the roadmap is designed for flexibility.

---

Table of Contents

1. Executive Summary

2. Migration Principles

3. Target Architecture

4. KrakenD Gateway Strategy

5. Migration Phases

   • Phase 0: Foundation (Gateway + Standards)

   • Phase 1: Pay-Outs /v3/

   • Phase 2: Remittances /v3/

   • Phase 3: Cards /v3/

   • Phase 4: Pay-Ins /v3/

   • Phase 5: Sunset Legacy APIs

6. Per-Phase Deliverables Matrix

7. Risk Register

8. Merchant Migration Strategy

9. Versioning & Deprecation Policy

10. Success Metrics

11. Dependencies

12. Appendix: Current vs Target API Mapping

---

1. Executive Summary

Simpaisa's API surface has grown organically across four product lines, resulting in:

• 7 different base URLs across 5 domains

• 3 different authentication mechanisms (JSESSIONID + custom headers, RSA + mTLS, RSA + headers, RSA + mTLS + AES)

• 3 different error response formats (flat JSON, {"response":{...}} wrapped, unknown for Cards)

• No idempotency on payment initiation — the single most critical gap for a payment platform

• No webhook signature verification — merchants cannot verify webhook authenticity

A merchant integrating both Pay-Ins and Pay-Outs today must build two entirely different API clients. This fragmentation increases integration time, support burden, and the probability of payment errors.

The Migration

This roadmap defines the path from the current fragmented state to a unified /v3/ API surface behind a single domain (api.simpaisa.com), using:

• KrakenD as the API gateway (95% decided)

• RSA-SHA256 signing as the single authentication mechanism across all products

• A single error schema and consistent HTTP status codes

• Idempotency keys on all state-changing endpoints

• OpenAPI 3.1 as the single source of truth for every endpoint

• HMAC-SHA256 webhook signing for all outbound notifications

The migration follows a strangler fig pattern — legacy APIs continue to run in parallel while /v3/ endpoints are built, tested, and adopted. No big-bang cutover.

Phasing Rationale

Phase	Product	Rationale
0	Foundation	Deploy gateway, route existing traffic, add cross-cutting concerns. No merchant changes.
1	Pay-Outs	Cleanest existing API. Already has RSA signing and mTLS. Lowest migration risk.
2	Remittances	Similar to Pay-Outs. Opportunity to migrate off commerceplex.com and fix spelling errors.
3	Cards	Documentation gaps must be filled first. PCI DSS constraints require careful handling.
4	Pay-Ins	Most complex. Requires auth mechanism change (JSESSIONID to RSA-SHA256). Longest parallel run.
5	Sunset	Remove legacy endpoints after deprecation windows elapse.

---

2. Migration Principles

2.1 No Big-Bang Cutover

Every phase deploys /v3/ endpoints alongside existing APIs. Merchants migrate at their own pace within the deprecation window. Legacy endpoints are never removed until usage drops to zero or the deprecation window expires.

2.2 Strangler Fig Pattern

New /v3/ endpoints are built as thin facades or new services. The gateway routes traffic to either legacy or /v3/ backends based on the URL prefix. Over time, /v3/ handles all traffic and legacy backends are decommissioned.

2.3 Backward Compatibility During Transition

• Legacy endpoints continue to function unchanged throughout the parallel run period

• No changes to legacy request/response formats

• No changes to legacy authentication mechanisms

• Sunset headers added to legacy responses to signal deprecation timeline

2.4 Merchant-First

• Migration guides published before any /v3/ endpoint goes live

• Sandbox environment available for all /v3/ endpoints before production

• DevEx API portal is the single source of merchant-facing documentation

• SDKs and code samples shipped for each /v3/ product

• Active outreach to high-volume merchants, with dedicated migration support

2.5 Gateway-First

KrakenD is deployed before any API changes. All existing traffic flows through the gateway first, enabling cross-cutting concerns (rate limiting, logging, error transformation) to be added without touching backend services.

2.6 Spec-First

OpenAPI 3.1 specifications are written and approved before any implementation begins. Contract tests run against the spec. SDKs generate from the spec. Documentation generates from the spec. The spec is the source of truth.

2.7 Reversibility

Every phase has a rollback plan. Gateway routing can revert to legacy backends within minutes. /v3/ endpoints can be removed without affecting legacy traffic.

---

3. Target Architecture

3.1 Unified API Surface

Attribute	Target State
Production domain	api.simpaisa.com
Sandbox domain	sandbox.simpaisa.com
URL pattern	/v3/{product}/{merchantId}/{resource}[/{action}]
Authentication	RSA-SHA256 request signing (all products)
Transport security	TLS 1.2+ mandatory; mTLS for Cards (PCI DSS)
Request format	Flat JSON (no wrapping)
Response format	Flat JSON with standard envelope
Error format	Single schema: {"error": {"code": "...", "message": "...", "details": [...]}}
HTTP status codes	Proper codes (200, 201, 400, 401, 403, 404, 409, 422, 429, 500, 502, 503)
Idempotency	Idempotency-Key header on all state-changing endpoints
Webhooks	HMAC-SHA256 signed, with X-Simpaisa-Signature header
Versioning	Path-based (/v3/); no header-based versioning
Spec format	OpenAPI 3.1 YAML

3.2 Target URL Examples

# Pay-Ins
POST   /v3/payins/{merchantId}/transactions
POST   /v3/payins/{merchantId}/transactions/{txnId}/verify
POST   /v3/payins/{merchantId}/transactions/{txnId}/refund
GET    /v3/payins/{merchantId}/transactions/{txnId}

# Pay-Outs
POST   /v3/disbursements/{merchantId}/transactions
GET    /v3/disbursements/{merchantId}/transactions/{txnId}
GET    /v3/disbursements/{merchantId}/balance

# Remittances
POST   /v3/remittances/{merchantId}/quotes
POST   /v3/remittances/{merchantId}/transfers
GET    /v3/remittances/{merchantId}/transfers/{txnId}
GET    /v3/remittances/{merchantId}/beneficiaries
POST   /v3/remittances/{merchantId}/beneficiaries/validate

# Cards
POST   /v3/cards/{merchantId}/payments
POST   /v3/cards/{merchantId}/payments/{txnId}/capture
POST   /v3/cards/{merchantId}/payments/{txnId}/void
POST   /v3/cards/{merchantId}/payments/{txnId}/refund
GET    /v3/cards/{merchantId}/payments/{txnId}

3.3 Standard Error Response

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "The account has insufficient funds to complete this transaction.",
    "details": [
      {
        "field": "amount",
        "reason": "Requested 5000.00 PKR but available balance is 3200.00 PKR"
      }
    ],
    "traceId": "req_7f3a2b1c-9d4e-4f5a-8b6c-1e2d3f4a5b6c",
    "timestamp": "2026-04-03T14:30:00.000Z"
  }
}

3.4 Standard Authentication Flow

All /v3/ endpoints use RSA-SHA256 request signing:

1. Merchant generates RSA 2048-bit key pair

2. Merchant uploads public key to Simpaisa portal

3. For each request, merchant signs the canonical request string with their private key

4. Signature is sent in the X-Simpaisa-Signature header

5. Simpaisa verifies the signature using the merchant's registered public key

No session cookies. No session state. Every request is independently authenticated.

---

4. KrakenD Gateway Strategy

4.1 Why KrakenD

KrakenD is a stateless, high-performance API gateway built in Go. It is the proposed gateway (95% decided) for Simpaisa's unified API surface.

Capability	Benefit for Simpaisa
Stateless design	Horizontally scalable; no shared state between gateway nodes
Declarative configuration	Gateway config lives in version control alongside OpenAPI specs
Request/response transformation	Transform legacy response formats at the gateway level
Rate limiting	Unified rate limiting across all products
CORS handling	Single CORS configuration for api.simpaisa.com
Logging & metrics	Centralised request logging and Prometheus metrics
Circuit breaker	Protect downstream services from cascade failures
Request validation	Validate requests against OpenAPI schemas before they reach backends

4.2 Deployment Strategy

Phase 0 deployment (transparent proxy):

┌─────────────┐     ┌──────────┐     ┌──────────────────────────────────┐
│  Merchants  │────▶│ KrakenD  │────▶│  Existing backend services       │
│             │     │ Gateway  │     │  (wallets, disb, remit, payment) │
└─────────────┘     └──────────┘     └──────────────────────────────────┘
                         │
                    api.simpaisa.com

1. Deploy KrakenD behind api.simpaisa.com

2. Configure transparent proxy routes to each existing backend

3. Legacy domains (wallets.simpaisa.com, disb.simpaisa.com, etc.) continue to work via DNS CNAME or redirect

4. All new integrations point to api.simpaisa.com

5. Gateway adds cross-cutting concerns (rate limiting, request logging, error format normalisation)

Phase 1+ deployment (routing split):

┌─────────────┐     ┌──────────┐     ┌─────────────────────┐
│  Merchants  │────▶│ KrakenD  │──┬─▶│  /v3/ services      │
│             │     │ Gateway  │  │  │  (new implementations)│
└─────────────┘     └──────────┘  │  └─────────────────────┘
                         │        │  ┌─────────────────────┐
                    api.simpaisa  └─▶│  Legacy backends     │
                    .com             │  (existing services)  │
                                     └─────────────────────┘

4.3 Gateway-Level Transformations

The gateway can normalise legacy responses without changing backend code:

Transformation	Purpose
Error format mapping	Wrap legacy {"status":"0006","message":"..."} into standard error schema
Response unwrapping	Strip {"response":{...}} wrapper from Pay-Outs/Remittances responses
Header injection	Add Sunset headers to legacy endpoint responses
Rate limit headers	Add X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Request ID injection	Generate X-Request-Id for tracing if not provided by client
CORS headers	Unified CORS policy across all products

4.4 KrakenD Configuration Management

• Configuration stored in Git alongside OpenAPI specs

• Environment-specific overrides via KrakenD Flexible Configuration

• Changes deployed via CI/CD pipeline (no manual gateway config changes)

• Configuration validated in CI before deployment

---

5. Migration Phases

---

Phase 0: Foundation (Gateway + Standards)

Objective: Deploy KrakenD in front of all existing services. Route all traffic through the gateway. Add cross-cutting concerns. No merchant-facing API changes.

Entry Criteria

• KrakenD selected as gateway (final decision)
• API Standards document approved (ref: API-STANDARDS.md)
• Infrastructure team allocated
• DNS records for api.simpaisa.com and sandbox.simpaisa.com provisioned

Deliverables

#	Deliverable	Description
0.1	KrakenD deployment	Production and sandbox KrakenD clusters on AWS (ECS or EKS)
0.2	Transparent proxy routes	All existing backend URLs proxied through api.simpaisa.com
0.3	DNS migration plan	CNAME or redirect strategy for legacy domains
0.4	Unified rate limiting	Rate limiting applied at gateway level across all products
0.5	Error format normalisation	Gateway transforms legacy error formats into standard schema for /v3/ routes
0.6	Request logging	Centralised structured logging for all API requests
0.7	Metrics & dashboards	Prometheus metrics, Grafana dashboards for latency, error rates, throughput
0.8	Health endpoints	/health and /ready endpoints on the gateway
0.9	CI/CD pipeline	Automated deployment of gateway configuration changes
0.10	Load testing	Verify gateway adds <5ms P95 latency overhead

Exit Criteria

• All existing API traffic routes through KrakenD with zero downtime
• Latency overhead is <5ms at P95
• Rate limiting is active and configurable per merchant/product
• Centralised logging captures all requests with trace IDs
• Dashboards show real-time traffic, error rates, and latency per product
• Legacy domains continue to function (CNAME or redirect)

Rollback Plan

• DNS records revert to point directly at existing backend ALBs

• Rollback time: <5 minutes (DNS TTL permitting)

• No merchant-facing changes to roll back

---

Phase 1: Pay-Outs /v3/

Objective: Deliver the first /v3/ API product. Pay-Outs is chosen because it has the cleanest existing API (RSA signing, mTLS, structured request/response) and therefore the lowest migration risk.

Entry Criteria

• Phase 0 complete — all traffic flows through KrakenD
• OpenAPI 3.1 spec for Pay-Outs written and reviewed
• DevEx API portal operational with Pay-Outs /v3/ documentation
• Sandbox environment available for /v3/ Pay-Outs endpoints

Deliverables

#	Deliverable	Description
1.1	OpenAPI 3.1 spec	payout-api.yaml — complete spec for all Pay-Out endpoints
1.2	/v3/ endpoints	POST /v3/disbursements/{merchantId}/transactions

| | GET /v3/disbursements/{merchantId}/transactions/{txnId}
| | GET /v3/disbursements/{merchantId}/balance
| | POST /v3/disbursements/{merchantId}/transactions/{txnId}/cancel
1.3| URL standardisation| Consistent /v3/disbursements/{merchantId}/{resource} pattern
1.4| Error format| Standard error schema on all /v3/ endpoints
1.5| HTTP status codes| Proper status codes (201 on creation, 400 on validation, etc.)
1.6| Idempotency| Idempotency-Key header required on all state-changing endpoints
1.7| Response unwrapping| Flat JSON responses (no {"response":{...}} wrapper)
1.8| Webhook HMAC signing| All Pay-Out webhooks signed with HMAC-SHA256
1.9| Contract tests| Schemathesis or Dredd tests running in CI against the OpenAPI spec
1.10| Migration guide| Side-by-side old/new examples for every endpoint
1.11| SDK updates| Updated SDK/code samples for Pay-Outs /v3/ (Java, Node.js, Python, PHP)
1.12| Gateway routing| KrakenD routes /v3/disbursements/* to new service; legacy routes untouched

Key Changes from Current API

Aspect	Current (Pay-Outs)	Target (/v3/)
Base URL	disb.simpaisa.com	api.simpaisa.com/v3/disbursements
Auth	RSA + mTLS	RSA-SHA256 signing (mTLS optional)
merchantId	In URL path	In URL path (no change)
Request format	{"request": {...}} wrapped	Flat JSON
Response format	{"response": {...}} wrapped	Flat JSON
Error format	{"response":{"status":"0054","message":"..."}}	Standard error schema
Idempotency	None	Idempotency-Key header required
Versioning	None	/v3/ path prefix
Webhooks	Unsigned	HMAC-SHA256 signed

Exit Criteria

• All /v3/ Pay-Out endpoints pass contract tests against OpenAPI spec
• Sandbox environment fully functional with test merchants
• At least one merchant successfully processing on /v3/ in production
• Webhook HMAC signing verified by at least one merchant
• Idempotency verified with duplicate request testing
• Legacy Pay-Out endpoints continue to function unchanged
• Migration guide and SDK samples published on DevEx portal
• Error rates on /v3/ endpoints ≤ legacy error rates
• P95 latency on /v3/ endpoints ≤ legacy latency + 10ms

Rollback Plan

• Gateway routes for /v3/disbursements/* removed from KrakenD config

• Legacy disb.simpaisa.com routes unaffected

• Merchants on /v3/ instructed to revert to legacy endpoints

• Rollback time: <10 minutes (gateway config redeployment)

---

Phase 2: Remittances /v3/

Objective: Migrate Remittances to /v3/ on api.simpaisa.com, eliminating the commerceplex.com domain dependency. Fix known issues (header spelling, missing webhook events, undocumented FX lifecycle).

Entry Criteria

• Phase 1 complete — Pay-Outs /v3/ live with at least one merchant migrated
• Lessons learned from Phase 1 incorporated
• OpenAPI 3.1 spec for Remittances written and reviewed
• FX quote lifecycle fully documented (validity, expiry, precision, refresh)

Deliverables

#	Deliverable	Description
2.1	OpenAPI 3.1 spec	remittance-api.yaml — complete spec for all Remittance endpoints
2.2	/v3/ endpoints	POST /v3/remittances/{merchantId}/quotes

| | POST /v3/remittances/{merchantId}/transfers
| | GET /v3/remittances/{merchantId}/transfers/{txnId}
| | GET /v3/remittances/{merchantId}/beneficiaries
| | POST /v3/remittances/{merchantId}/beneficiaries/validate
2.3| Domain migration| All traffic moves from remit.commerceplex.com to api.simpaisa.com
2.4| Header fix| Fix remitance → remittance spelling in all headers
2.5| FX documentation| Documented quote validity period, expiry behaviour, precision rules, refresh mechanism
2.6| Missing webhooks| Add webhook events: Published, In Process, In Review, Stuck, AML Review
2.7| Webhook HMAC signing| All Remittance webhooks signed with HMAC-SHA256
2.8| Idempotency| Idempotency-Key on transfer initiation and quote creation
2.9| Error format| Standard error schema on all /v3/ endpoints
2.10| Response unwrapping| Flat JSON responses (no {"response":{...}} wrapper)
2.11| Contract tests| Running in CI against OpenAPI spec
2.12| Migration guide| Side-by-side old/new examples; domain change highlighted
2.13| SDK updates| Updated SDK/code samples for Remittances /v3/

Key Changes from Current API

Aspect	Current (Remittances)	Target (/v3/)
Base URL	remit.commerceplex.com	api.simpaisa.com/v3/remittances
Auth	RSA + custom headers	RSA-SHA256 signing
Header spelling	remitance (typo)	remittance (corrected)
merchantId	In URL path	In URL path (no change)
Request format	{"request": {...}} wrapped	Flat JSON
Response format	{"response": {...}} wrapped	Flat JSON
Error format	{"response":{"status":"0000","message":"..."}}	Standard error schema
Versioning	version:3.0 header	/v3/ path prefix
Webhooks	Partial coverage, unsigned	Full lifecycle events, HMAC-SHA256 signed
FX quotes	Undocumented expiry/precision	Documented validity, expiry, precision

Exit Criteria

• All /v3/ Remittance endpoints pass contract tests
• remit.commerceplex.com traffic fully migrated to api.simpaisa.com
• At least one remittance partner successfully processing on /v3/
• All new webhook events firing correctly
• FX quote lifecycle documented and tested (expiry, refresh, precision)
• Header spelling corrected with backward-compatible alias during transition
• Legacy Remittance endpoints continue to function during parallel run

Rollback Plan

• Gateway routes for /v3/remittances/* removed from KrakenD config

• DNS for remit.commerceplex.com continues to resolve to legacy backend

• commerceplex.com domain maintained until all merchants migrated

• Rollback time: <10 minutes

---

Phase 3: Cards /v3/

Objective: Create the first comprehensive API specification for Cards and deliver /v3/ endpoints. Cards has the sparsest documentation of any product — the OpenAPI spec is the primary deliverable.

Entry Criteria

• Phase 2 complete — Remittances /v3/ live
• Full Cards API reverse-engineered and documented (current state is "Unknown" for most attributes)
• PCI DSS compliance requirements reviewed and incorporated
• OpenAPI 3.1 spec for Cards written and reviewed

Deliverables

#	Deliverable	Description
3.1	API discovery	Full audit of existing Cards endpoints, request/response formats, auth flows
3.2	OpenAPI 3.1 spec	cards-api.yaml — complete spec (currently no comprehensive spec exists)
3.3	/v3/ endpoints	POST /v3/cards/{merchantId}/payments

| | POST /v3/cards/{merchantId}/payments/{txnId}/capture
| | POST /v3/cards/{merchantId}/payments/{txnId}/void
| | POST /v3/cards/{merchantId}/payments/{txnId}/refund
| | GET /v3/cards/{merchantId}/payments/{txnId}
| | POST /v3/cards/{merchantId}/payments/{txnId}/finalise
3.4| Auth: maintain mTLS| mTLS retained for PCI DSS compliance; RSA-SHA256 added as additional signing layer
3.5| AES encryption| Maintain AES encryption for sensitive card data fields (PCI DSS requirement)
3.6| URL standardisation| Consistent /v3/cards/{merchantId}/{resource} pattern
3.7| Error format| Standard error schema on all /v3/ endpoints
3.8| Idempotency| Idempotency-Key on payment initiation, capture, void, refund
3.9| Webhook HMAC signing| All Cards webhooks signed with HMAC-SHA256
3.10| Contract tests| Running in CI against OpenAPI spec
3.11| Migration guide| Detailed guide covering auth changes and endpoint mapping
3.12| PCI DSS documentation| Compliance mapping document showing how /v3/ maintains PCI DSS requirements

PCI DSS Constraints

Cards migration has additional constraints due to PCI DSS:

• mTLS is mandatory — cannot be removed, only supplemented

• AES encryption on card number, CVV, and expiry fields must be maintained

• Tokenisation should replace raw card data transmission where possible

• Audit logging must capture all card operations with full traceability

• Key rotation procedures must be documented and tested

Exit Criteria

• Complete OpenAPI 3.1 spec for all Cards endpoints (the biggest deliverable)
• All /v3/ Cards endpoints pass contract tests
• mTLS and AES encryption verified by PCI DSS auditor or internal security review
• At least one merchant successfully processing on /v3/ Cards
• Webhook HMAC signing verified
• Legacy Cards endpoints continue to function

Rollback Plan

• Gateway routes for /v3/cards/* removed from KrakenD config

• Legacy payment.simpaisa.com routes unaffected

• PCI DSS audit scope remains unchanged (legacy + /v3/ during parallel run)

• Rollback time: <10 minutes

---

Phase 4: Pay-Ins /v3/

Objective: Migrate Pay-Ins — the highest-risk product — from JSESSIONID session-based auth to RSA-SHA256 signing. This is the most complex migration because it requires a fundamental authentication mechanism change for all Pay-In merchants.

Entry Criteria

• Phases 1-3 complete — three products successfully migrated
• Migration tooling proven and refined through previous phases
• RSA-SHA256 signing libraries/samples available in all major languages
• Extended parallel run period budgeted (12 months minimum for auth change)
• OpenAPI 3.1 spec for Pay-Ins written and reviewed
• Merchant communication plan approved (auth change is the biggest breaking change)

Deliverables

#	Deliverable	Description
4.1	OpenAPI 3.1 spec	payin-api.yaml — complete spec for all Pay-In endpoints
4.2	/v3/ endpoints	POST /v3/payins/{merchantId}/transactions (wallet, IBFT, card, hosted)

| | POST /v3/payins/{merchantId}/transactions/{txnId}/verify
| | POST /v3/payins/{merchantId}/transactions/{txnId}/refund
| | GET /v3/payins/{merchantId}/transactions/{txnId}
| | GET /v3/payins/{merchantId}/transactions/{txnId}/status
4.3| Auth migration| Eliminate JSESSIONID; implement RSA-SHA256 signing
4.4| Signing libraries| RSA-SHA256 signing libraries for Java, Node.js, Python, PHP, C#
4.5| OTP expiry fix| Reduce OTP expiry from 30 minutes to 5 minutes
4.6| Idempotency| Idempotency-Key on transaction initiation — critical to prevent duplicate payments
4.7| merchantId in URL| Move merchantId from request body to URL path
4.8| Error format| Standard error schema (replace {"status":"0006","message":"..."})
4.9| HTTP status codes| Proper codes (replace blanket 200 with appropriate 4xx/5xx)
4.10| Webhook HMAC signing| All Pay-In webhooks signed with HMAC-SHA256
4.11| Contract tests| Running in CI against OpenAPI spec
4.12| Migration guide| Comprehensive guide with auth migration walkthrough, key generation, signing examples
4.13| SDK updates| Full SDKs for Pay-Ins /v3/ with signing built in
4.14| Merchant onboarding| Key pair generation tool in merchant portal; self-service public key upload

Key Changes from Current API

Aspect	Current (Pay-Ins)	Target (/v3/)
Base URL	wallets.simpaisa.com (+ 4 others)	api.simpaisa.com/v3/payins
Auth	JSESSIONID + custom headers	RSA-SHA256 signing (fundamental change)
merchantId	In request body	In URL path
Request format	Flat JSON	Flat JSON (no change)
Response format	Flat JSON	Flat JSON (no change)
Error format	{"status":"0006","message":"..."}	Standard error schema
Idempotency	Request-Id on verify only	Idempotency-Key on all state-changing endpoints
Versioning	/v2/ + version:3.0 header	/v3/ path prefix only
OTP expiry	30 minutes	5 minutes
Webhooks	Unsigned	HMAC-SHA256 signed

Why Pay-Ins Is Last

1. Auth mechanism change — JSESSIONID to RSA-SHA256 is the most disruptive change in this roadmap. Every Pay-In merchant must generate key pairs, upload public keys, and rewrite their auth code.

2. Highest merchant count — Pay-Ins likely has the most integrations; more merchants to migrate means higher risk.

3. Duplicate payment risk — Adding idempotency to payment initiation is critical but must be done carefully. Getting this wrong creates more problems than it solves.

4. Lessons learned — By Phase 4, the team will have migrated three products. Tooling, documentation templates, and migration playbooks will be battle-tested.

Exit Criteria

• All /v3/ Pay-In endpoints pass contract tests
• RSA-SHA256 signing working for all merchant language stacks (Java, Node.js, Python, PHP, C#)
• At least 50% of Pay-In merchants migrated to /v3/ (or threshold TBD)
• Idempotency verified with extensive duplicate request testing
• OTP expiry reduced to 5 minutes with no increase in user drop-off
• Legacy Pay-In endpoints continue to function during 12-month parallel run
• Zero duplicate payments attributable to migration

Rollback Plan

• Gateway routes for /v3/payins/* removed from KrakenD config

• Legacy wallets.simpaisa.com routes unaffected

• Merchants who have migrated can revert to legacy auth (JSESSIONID credentials retained during parallel run)

• Signing keys remain valid — no data loss on rollback

• Rollback time: <10 minutes (gateway config), but merchant reversion may take days

---

Phase 5: Sunset Legacy APIs

Objective: Decommission all legacy API endpoints after deprecation windows expire. Remove legacy backend services where /v3/ fully replaces them.

Entry Criteria

• All four /v3/ products live and stable in production
• Merchant migration targets met for each product (thresholds TBD)
• Deprecation windows elapsed (6 months minimum; 12 months for Pay-Ins auth change)
• Remaining legacy traffic identified and merchants contacted

Deliverables

#	Deliverable	Description
5.1	Sunset headers	Sunset: <date> header on all legacy endpoint responses
5.2	Usage tracking	Dashboard showing per-merchant legacy API usage
5.3	Active outreach	Direct contact with every merchant still on legacy endpoints
5.4	Migration assistance	Dedicated support for remaining merchants (code review, signing library help)
5.5	410 Gone responses	Legacy endpoints return 410 Gone after deprecation window
5.6	DNS cleanup	Decommission legacy domains (wallets.simpaisa.com, disb.simpaisa.com, remit.commerceplex.com, payment.simpaisa.com)
5.7	Backend decommission	Remove legacy backend services where /v3/ fully replaces them
5.8	Cost reconciliation	Document infrastructure cost savings from decommissioned services

Sunset Timeline per Product

Product	/v3/ Launch	Deprecation Notice	Legacy 410 Gone	Total Window
Pay-Outs	Phase 1 complete	Phase 1 launch date	6 months after notice	6 months
Remittances	Phase 2 complete	Phase 2 launch date	6 months after notice	6 months
Cards	Phase 3 complete	Phase 3 launch date	6 months after notice	6 months
Pay-Ins	Phase 4 complete	Phase 4 launch date	12 months after notice	12 months

Pay-Ins gets a 12-month window because the auth mechanism change (JSESSIONID → RSA-SHA256) is a fundamental change per the deprecation policy in API-STANDARDS.md.

Exit Criteria

• Zero traffic on legacy endpoints (or only from merchants who have been notified and acknowledged)
• All legacy endpoints returning 410 Gone
• Legacy domains decommissioned or redirecting to api.simpaisa.com
• Legacy backend services decommissioned
• Infrastructure cost savings documented

Rollback Plan

• Legacy backends are not decommissioned until 30 days after 410 Gone is activated

• During this 30-day grace period, 410 can be reverted to proxy mode

• After decommission, rollback requires redeployment of legacy services (hours, not minutes)

---

6. Per-Phase Deliverables Matrix

Deliverable	Phase 0	Phase 1	Phase 2	Phase 3	Phase 4	Phase 5
OpenAPI 3.1 spec	—	Pay-Outs	Remittances	Cards	Pay-Ins	—
KrakenD gateway config	Deploy + proxy	/v3/ routes	/v3/ routes	/v3/ routes	/v3/ routes	Remove legacy routes
Backend service changes	None	Unwrap responses, standardise errors	Unwrap responses, add webhooks	Full spec discovery + implementation	Auth rewrite, idempotency	Decommission
Merchant documentation	—	Migration guide	Migration guide + domain change	Migration guide + PCI notes	Migration guide + auth walkthrough	Sunset notices
SDK/code samples	—	Pay-Outs SDK	Remittances SDK	Cards SDK	Pay-Ins SDK + signing libs	—
Contract tests	—	Pay-Outs	Remittances	Cards	Pay-Ins	—
Webhook changes	—	HMAC signing	HMAC + new events	HMAC signing	HMAC signing	—
Idempotency	—	Added	Added	Added	Added (critical)	—
Rate limiting	Gateway-level	Per-product tuning	Per-product tuning	Per-product tuning	Per-product tuning	—
Monitoring dashboards	Gateway metrics	/v3/ vs legacy comparison	/v3/ vs legacy comparison	/v3/ vs legacy comparison	/v3/ vs legacy comparison	Sunset tracking

---

7. Risk Register

Phase 0 Risks

Risk	Likelihood	Impact	Mitigation
Gateway adds unacceptable latency	Low	High	Load test before go-live; KrakenD is stateless and benchmarks <1ms overhead
Existing services break behind gateway	Medium	High	Transparent proxy mode first; canary rollout with traffic splitting
DNS migration causes downtime	Low	Critical	Blue-green DNS cutover; keep legacy domains active during transition
KrakenD not selected (5% chance)	Low	High	Architecture is gateway-agnostic; alternative: Kong, Envoy, or AWS API Gateway

Phase 1 Risks (Pay-Outs)

Risk	Likelihood	Impact	Mitigation
OpenAPI spec mismatches actual backend behaviour	Medium	Medium	Contract tests catch mismatches before merchant-facing launch
Merchant resistance to migration	Medium	Medium	DevEx portal, migration guides, dedicated support, extended parallel run
Idempotency implementation introduces bugs	Low	High	Thorough testing with duplicate requests; idempotency store with TTL
Response format change breaks merchant parsers	Low	Medium	/v3/ is a new URL — merchants opt in; legacy format unchanged

Phase 2 Risks (Remittances)

Risk	Likelihood	Impact	Mitigation
commerceplex.com domain ownership/DNS issues	Medium	High	Verify DNS control early; maintain domain during full transition period
FX quote lifecycle poorly understood	Medium	Medium	Reverse-engineer from production logs; validate with operations team
Header spelling fix breaks existing integrations	Low	Medium	Accept both spellings during parallel run; correct spelling on /v3/ only
Missing webhook events have incorrect trigger conditions	Medium	Medium	Map events to backend state machine; test with synthetic transactions

Phase 3 Risks (Cards)

Risk	Likelihood	Impact	Mitigation
Sparse documentation makes spec writing difficult	High	High	Reverse-engineer from code and production traffic; interview Cards team
PCI DSS compliance impact	Medium	Critical	Security review before any changes; maintain mTLS and AES throughout
Cards API has undiscovered edge cases	High	Medium	Extended sandbox testing period; canary rollout with low-volume merchants

Phase 4 Risks (Pay-Ins)

Risk	Likelihood	Impact	Mitigation
Auth mechanism change causes merchant drop-off	Medium	Critical	12-month window; signing libraries in all languages; dedicated migration support
Signing library bugs in specific language stacks	Medium	High	Extensive testing across all target languages; community review
Idempotency on payment initiation has edge cases	Medium	Critical	Conservative TTL; clear documentation of idempotency semantics; extensive testing
OTP expiry reduction increases user drop-off	Medium	Medium	A/B test before full rollout; monitor completion rates; configurable expiry
Duplicate payments during migration window	Low	Critical	Both old and new endpoints share the same payment processor; deduplication at processor level

Phase 5 Risks (Sunset)

Risk	Likelihood	Impact	Mitigation
Merchants still on legacy when sunset arrives	High	High	Active outreach starting month 1; usage dashboard; escalation to account managers
Legacy decommission breaks internal systems	Medium	Medium	Audit all internal consumers of legacy APIs before decommission
DNS decommission affects unrelated services	Low	High	Full DNS audit of all legacy domains before decommission

---

8. Merchant Migration Strategy

8.1 DevEx API Portal

The DevEx API portal is the single communication channel for merchant-facing documentation, migration guides, and API status.

Portal features for migration:

• Interactive API explorer (Swagger UI or Redocly) for each /v3/ product

• Side-by-side migration guides (old endpoint → new endpoint)

• Signing key management (generate, upload, rotate)

• Sandbox access with test credentials

• Webhook testing tools (send test webhooks, verify signatures)

• API changelog and deprecation timeline

• SDK downloads and code samples

8.2 Migration Guide Template

Each product migration guide follows the same structure:

1. What's changing — summary of differences between legacy and /v3/

2. What's not changing — reassurance about what stays the same

3. Step-by-step migration — ordered instructions

4. Authentication — how to set up RSA-SHA256 signing (with language-specific examples)

5. Endpoint mapping — every legacy endpoint mapped to its /v3/ equivalent

6. Request/response examples — complete examples for every endpoint (old and new side by side)

7. Error handling — new error format with mapping from old error codes

8. Webhook verification — how to verify HMAC-SHA256 signatures

9. Testing in sandbox — how to test the migration before going live

10. Go-live checklist — what to verify before switching production traffic

8.3 Sandbox Strategy

• sandbox.simpaisa.com mirrors all /v3/ endpoints

• Test merchants provisioned with sandbox-specific credentials

• Sandbox supports all payment channels with simulated responses

• Contract tests run against sandbox to ensure parity with production

• Merchants can test webhook delivery to their staging environments

8.4 Parallel Run Policy

Product	Minimum Parallel Run	Extended For
Pay-Outs	6 months	High-volume merchants needing more time
Remittances	6 months	Partners on commerceplex.com domain
Cards	6 months	PCI DSS re-certification timing
Pay-Ins	12 months	Auth mechanism change

During parallel run:

• Both legacy and /v3/ endpoints are fully supported

• Merchants can migrate at their own pace

• Usage dashboards track migration progress per merchant

• Active outreach at 3-month and 6-month marks (3, 6, 9, and 12 for Pay-Ins)

8.5 Deprecation Communication Timeline

Timing	Action
Day 0 (Phase launch)	Email all merchants; changelog entry; DevEx portal announcement
Day 0	Sunset: <date> header added to all legacy responses
Month 1	Follow-up email with migration guide link
Month 3	Active outreach to merchants with >10% of traffic still on legacy
Month 5 (or 11 for Pay-Ins)	Final warning: "Legacy endpoints will return 410 in 30 days"
Month 6 (or 12 for Pay-Ins)	Legacy endpoints return 410 Gone with redirect to /v3/ docs

---

9. Versioning & Deprecation Policy

Per API-STANDARDS.md section 5.3 and section 28:

9.1 Versioning

• Path-based versioning: /v3/ prefix on all new endpoints

• No header-based versioning (the legacy version: 3.0 header is deprecated)

• Major version increments only for breaking changes

• Minor/patch changes are backward-compatible within the same major version

9.2 Deprecation Windows

Change Type	Minimum Window	Notification
Endpoint removal	6 months	Email + changelog + Sunset header
Response format change	6 months	Email + changelog + Sunset header
Auth mechanism change	12 months	Email + changelog + Sunset header + dedicated migration support
New optional field	Immediate	Changelog only
New endpoint	Immediate	Changelog + portal announcement

9.3 Sunset Header

All deprecated endpoints include the Sunset header in every response:

Sunset: Sat, 01 Oct 2027 00:00:00 GMT
Deprecation: true
Link: <https://api.simpaisa.com/v3/disbursements>; rel="successor-version"

9.4 Error Response After Sunset

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": {
    "code": "API_VERSION_SUNSET",
    "message": "This API version has been retired. Please migrate to /v3/.",
    "details": [
      {
        "field": "migration_guide",
        "reason": "https://developer.simpaisa.com/migration/disbursements"
      }
    ]
  }
}

---

10. Success Metrics

10.1 Phase-Level Metrics

Metric	Phase 0	Phase 1	Phase 2	Phase 3	Phase 4	Phase 5
Gateway latency overhead (P95)	<5ms	<5ms	<5ms	<5ms	<5ms	N/A
Merchant migration %	N/A	≥80% within 6 months	≥80% within 6 months	≥80% within 6 months	≥80% within 12 months	100%
Contract test pass rate	N/A	100%	100%	100%	100%	N/A
Error rate (/v3/ vs legacy)	N/A	≤ legacy	≤ legacy	≤ legacy	≤ legacy	N/A
P95 latency (/v3/ vs legacy)	N/A	≤ legacy + 10ms	≤ legacy + 10ms	≤ legacy + 10ms	≤ legacy + 10ms	N/A
Idempotency duplicate rejection rate	N/A	Measured	Measured	Measured	Measured	N/A
Webhook delivery success rate	N/A	≥99.9%	≥99.9%	≥99.9%	≥99.9%	N/A
Legacy traffic remaining	100%	Decreasing	Decreasing	Decreasing	Decreasing	0%

10.2 Programme-Level Metrics

Metric	Target	Measurement
Total base URLs	2 (api + sandbox)	DNS record count
Auth mechanisms	1 (RSA-SHA256) + mTLS for Cards	Code audit
Error format variants	1	Contract test validation
Merchant integration time (new)	<2 days (from current ~1 week)	Merchant onboarding tracker
Support tickets per integration	<3 (from current ~10)	Support system metrics
API documentation coverage	100% of endpoints in OpenAPI	Spec linting
SDK language coverage	5 languages (Java, Node.js, Python, PHP, C#)	Release count
Infrastructure cost (API layer)	Reduced after legacy decommission	AWS billing

---

11. Dependencies

11.1 Dependency Graph

KrakenD Decision (Final)
  └─▶ Phase 0: Foundation
        └─▶ Phase 1: Pay-Outs /v3/
              └─▶ Phase 2: Remittances /v3/
                    └─▶ Phase 3: Cards /v3/
                          └─▶ Phase 4: Pay-Ins /v3/
                                └─▶ Phase 5: Sunset

11.2 Cross-Cutting Dependencies

Dependency	Blocks	Notes
KrakenD final decision	Everything	95% decided; need final sign-off
DNS control forapi.simpaisa.com	Phase 0	Must be provisioned before gateway deployment
DNS control forsandbox.simpaisa.com	Phase 0	Must be provisioned before gateway deployment
DevEx API portal	Phases 1-4	Merchant migration guides require the portal
OpenAPI 3.1 specs	SDKs, contract tests, docs	Spec is source of truth; everything generates from it
RSA-SHA256 signing libraries	Phase 4 (Pay-Ins)	Must be available in 5 languages before Pay-Ins migration
Merchant key management in portal	Phase 4 (Pay-Ins)	Self-service key upload required for Pay-Ins auth migration
Cards API discovery	Phase 3	Cannot write OpenAPI spec without understanding current endpoints
commerceplex.comDNS control	Phase 2	Required for Remittances domain migration
PCI DSS auditor review	Phase 3	Cards changes must be validated for compliance
Merchant count per product	Phase 5 (sunset thresholds)	TBD — needed to set migration targets
Breaking change tolerance per product	All phases	TBD — affects parallel run duration and rollback planning

11.3 Team Dependencies

Team / Capability	Phases	Responsibility
Platform / Infrastructure	0	KrakenD deployment, DNS, CI/CD
Backend Engineering	1-4	/v3/ endpoint implementation, contract tests
Security	0, 3, 4	Gateway security review, PCI DSS compliance, signing library review
DevEx / Documentation	1-4	API portal, migration guides, SDK samples
Operations	0-5	Monitoring, alerting, incident response
Account Management	5	Merchant outreach for sunset
QA / Testing	1-4	Contract testing, integration testing, load testing

Note: The engineering team will be reorganised as required to support this roadmap. An agentic AI SDLC-first approach will be used, with Claude-driven development, testing, and documentation generation.

---

Appendix: Current vs Target API Mapping

Pay-Ins

Current Endpoint	Current URL	Target /v3/ Endpoint
Login / Session	POST wallets.simpaisa.com/v2/wallets/login	Eliminated — RSA-SHA256 signing replaces sessions
Initiate Transaction	POST wallets.simpaisa.com/v2/wallets/transaction/initiate	POST api.simpaisa.com/v3/payins/{merchantId}/transactions
Verify OTP	POST wallets.simpaisa.com/v2/wallets/transaction/verify	POST api.simpaisa.com/v3/payins/{merchantId}/transactions/{txnId}/verify
Transaction Status	GET wallets.simpaisa.com/v2/wallets/transaction/status	GET api.simpaisa.com/v3/payins/{merchantId}/transactions/{txnId}
Refund	POST wallets.simpaisa.com/v2/wallets/transaction/refund	POST api.simpaisa.com/v3/payins/{merchantId}/transactions/{txnId}/refund

Pay-Outs

Current Endpoint	Current URL	Target /v3/ Endpoint
Initiate Disbursement	POST disb.simpaisa.com/merchants/{id}/disbursements/initiate	POST api.simpaisa.com/v3/disbursements/{merchantId}/transactions
Transaction Status	GET disb.simpaisa.com/merchants/{id}/disbursements/status	GET api.simpaisa.com/v3/disbursements/{merchantId}/transactions/{txnId}
Balance Inquiry	GET disb.simpaisa.com/merchants/{id}/disbursements/balance	GET api.simpaisa.com/v3/disbursements/{merchantId}/balance
Cancel	POST disb.simpaisa.com/merchants/{id}/disbursements/cancel	POST api.simpaisa.com/v3/disbursements/{merchantId}/transactions/{txnId}/cancel

Remittances

Current Endpoint	Current URL	Target /v3/ Endpoint
Get Quote	POST remit.commerceplex.com/{id}/quote	POST api.simpaisa.com/v3/remittances/{merchantId}/quotes
Initiate Transfer	POST remit.commerceplex.com/{id}/transfer	POST api.simpaisa.com/v3/remittances/{merchantId}/transfers
Transfer Status	GET remit.commerceplex.com/{id}/transfer/status	GET api.simpaisa.com/v3/remittances/{merchantId}/transfers/{txnId}
Validate Beneficiary	POST remit.commerceplex.com/{id}/beneficiary/validate	POST api.simpaisa.com/v3/remittances/{merchantId}/beneficiaries/validate
List Beneficiaries	GET remit.commerceplex.com/{id}/beneficiaries	GET api.simpaisa.com/v3/remittances/{merchantId}/beneficiaries

Cards

Note: Current Cards endpoints are partially documented. The mapping below is based on known endpoints; Phase 3 includes a full API discovery exercise.

Current Endpoint	Current URL	Target /v3/ Endpoint
Payment (Auth)	POST payment.simpaisa.com/... (exact path TBD)	POST api.simpaisa.com/v3/cards/{merchantId}/payments
Capture	POST payment.simpaisa.com/... (exact path TBD)	POST api.simpaisa.com/v3/cards/{merchantId}/payments/{txnId}/capture
Void	POST payment.simpaisa.com/... (exact path TBD)	POST api.simpaisa.com/v3/cards/{merchantId}/payments/{txnId}/void
Refund	POST payment.simpaisa.com/... (exact path TBD)	POST api.simpaisa.com/v3/cards/{merchantId}/payments/{txnId}/refund
Inquiry	GET payment.simpaisa.com/... (exact path TBD)	GET api.simpaisa.com/v3/cards/{merchantId}/payments/{txnId}
Finalise	POST payment.simpaisa.com/... (exact path TBD)	POST api.simpaisa.com/v3/cards/{merchantId}/payments/{txnId}/finalise

Summary of Changes

Attribute	Current State	Target State
Base URLs	7 URLs across 5 domains	2 URLs: api.simpaisa.com, sandbox.simpaisa.com
Auth mechanisms	3+ (JSESSIONID, RSA+mTLS, RSA+headers, RSA+mTLS+AES)	1 (RSA-SHA256) + mTLS for Cards
Error formats	3+ variants	1 standard schema
URL patterns	3+ patterns	1 pattern: /v3/{product}/{merchantId}/{resource}[/{action}]
Request wrapping	Mixed (flat + {"request":{...}})	Flat JSON only
Response wrapping	Mixed (flat + {"response":{...}})	Flat JSON only
Idempotency	Partial (verify only)	All state-changing endpoints
Webhook signing	None	HMAC-SHA256 on all webhooks
API specs	Partial/missing	OpenAPI 3.1 for every endpoint
SDKs	None	5 languages

---

This document is a living artefact. It will be updated as decisions are finalised, merchant counts are determined, and phases are executed. All content is proposed and subject to revision.