Skip to content

SDK Generation Pipeline Standard

Version: 1.0 Last Updated: 2026-04-03 Owner: Platform Team Status: Active

Purpose

Define the automated pipeline for generating, testing, and publishing client SDKs from Simpaisa's OpenAPI specifications. SDKs reduce integration time, enforce correct auth implementation, and ensure merchants use up-to-date API contracts.

Source Specifications

All SDKs are generated from OpenAPI 3.1 spec files, maintained as the single source of truth:

Spec File Product Repository
payin-api.yaml Pay-Ins simpaisa/payin-svc
payout-api.yaml Pay-Outs simpaisa/payout-svc
remittance-api.yaml Remittances simpaisa/remittance-svc
cards-api.yaml Cards simpaisa/cards-svc

Specs are co-located with their service code. Changes to the spec trigger the SDK generation pipeline via Bitbucket Pipelines.

Generator

  • Tool: openapi-generator-cli (latest stable)
  • Configuration: Per-language config files in simpaisa/sdk-generator repository
  • Customisation: Mustache templates for auth helpers, retry logic, and naming conventions

Target Languages & Package Names

Language Package Name Registry
Java com.simpaisa:payin-sdk Maven Central
Python simpaisa-payin-sdk PyPI
Node.js/TypeScript @simpaisa/payin-sdk npm
PHP simpaisa/payin-sdk Packagist
C# Simpaisa.PayIn.Sdk NuGet

Each product has its own SDK package. Pattern: {org}/{product}-sdk per registry convention. Replace payin with payout, remittance, or cards for other products.

SDK Versioning

  • SDK versions track the API version: 3.x.y for /v3/ APIs.
  • Major: API version change (v3 → v4).
  • Minor: New endpoints or optional fields added (backward compatible).
  • Patch: Bug fixes in SDK logic, documentation updates.
  • Git tags trigger releases: payin-sdk-v3.2.1.

CI/CD Pipeline

Spec change merged to main
  → Spectral lint (OpenAPI validation)
  → Breaking change detection (oasdiff)
  → Generate SDKs (all 5 languages × 4 products)
  → Compile/build each SDK
  → Run generated tests + custom integration tests against sandbox
  → Publish to package registries (on release tag)
  → Update DevEx portal code samples

Pipeline Stages

1. Lint (Spectral) - Validates spec against Simpaisa's custom ruleset: simpaisa-api-ruleset.yaml - Enforced rules: consistent naming, required operationId, response schema for all status codes, traceId in error responses - Blocks pipeline on any error-level violation

2. Breaking Change Detection - Uses oasdiff to compare current spec against previously released spec - Breaking changes (removed fields, changed types, removed endpoints) block the pipeline - Non-breaking changes (new optional fields, new endpoints) produce warnings

3. Generate - Runs openapi-generator-cli generate for each language - Custom templates inject: RSA signing helper, idempotency key generation, retry logic, webhook signature verification

4. Test - Compile/build validation for each language - Integration tests run against sandbox.simpaisa.com - Tests cover: auth flow, transaction creation, status query, webhook verification, error handling

5. Publish - Triggered by Git tag only (not on every merge) - Publishes to respective package registries - Requires pipeline approval from Platform Team lead

SDK Features

Every generated SDK MUST include:

Authentication Helper

  • RSA-SHA256 request signing
  • Automatic X-Simpaisa-Signature header generation
  • Key loading from file path or environment variable

Idempotency

  • Automatic Idempotency-Key generation (UUIDv4) when not provided by caller
  • Idempotency key storage for retry scenarios

Retry with Exponential Backoff

  • Retries on 429, 502, 503, 504 only
  • Never retry 400, 401, 403, 409, 422 (client errors are not transient)
  • Backoff: 1s, 2s, 4s, 8s (max 3 retries, configurable)
  • Jitter: +/- 20% randomisation

Webhook Signature Verification

  • verifyWebhook(payload, signature, publicKey) method
  • Compares X-Simpaisa-Webhook-Signature against computed HMAC-SHA256
  • Timestamp validation: reject webhooks older than 5 minutes (replay protection)

Typed Models

  • All request/response objects are strongly typed
  • Enum types for: transaction states, currencies, error codes
  • Nullable fields explicitly marked

Code Samples

  • Extracted from SDK integration tests (real, runnable code)
  • Published to DevEx portal under each endpoint's documentation
  • Languages: all 5 SDK languages
  • Scenarios: initiate payment, check status, handle webhook, handle errors

Repository Structure

simpaisa/sdk-generator/
├── config/
│   ├── java.yaml
│   ├── python.yaml
│   ├── typescript.yaml
│   ├── php.yaml
│   └── csharp.yaml
├── templates/          # Mustache template overrides
│   ├── auth/
│   ├── retry/
│   └── webhook/
├── tests/
│   └── integration/    # Sandbox integration tests
├── spectral/
│   └── simpaisa-api-ruleset.yaml
└── bitbucket-pipelines.yml

Generated SDK Repositories

Each product/language combination publishes to its own Bitbucket repository:

simpaisa/payin-sdk-java
simpaisa/payin-sdk-python
simpaisa/payin-sdk-typescript
simpaisa/payin-sdk-php
simpaisa/payin-sdk-csharp

Generated code is committed to these repositories by the pipeline (not hand-edited). Custom logic lives in the templates, not in generated output.

Quality Gates

  • Generated SDKs MUST compile without warnings
  • Integration tests MUST pass against sandbox before publish
  • Code coverage on custom (non-generated) logic: minimum 80%
  • No credentials or secrets in generated code (auth uses runtime configuration)