Skip to content

Generate a payment API client from an OpenAPI spec: types, SDKs, Postman and contract tests

How to generate a payment API client from an OpenAPI spec: TypeScript types, SDKs with OpenAPI Generator, Postman import and contract tests.

Published 3 min read

Hand-drawn illustration of an openapi.json file feeding a generator that outputs TypeScript, Python and a Postman collection, next to a person with hands in their pockets
On this page
  1. Where to get the OpenAPI spec
  2. What is in the spec
  3. Option 1: TypeScript types only
  4. Option 2: a full client SDK
  5. Option 3: import into Postman
  6. Contract tests: keep the client and the API in step
  7. What a generated client does not do for you
  8. Summary

An OpenAPI spec is a machine-readable description of an API: every endpoint, parameter, request body, response and error. From it you can generate an API client — typed models and methods in your own language — instead of hand-writing HTTP calls and copying field names out of the docs. For a payment API that matters more than usual: a misspelled field or a wrong enum value is a failed payment, not a typo.

This guide shows how to generate a client from KukoPay's OpenAPI spec: where to get it, what is in it, how to generate TypeScript types or a full SDK, how to use it in Postman, and how to keep a generated client honest with contract tests.

Where to get the OpenAPI spec

The full OpenAPI 3.1 description of the merchant API is public:

curl https://api.kukopay.com/v1/openapi.json -o kukopay.v1.json

It is generated from the server code itself, so its enums (order, refund and dispute statuses, event types, balance transaction types), error codes and limits always match what the live API does. When something is added, the spec changes with it.

What is in the spec

  • One server, https://api.kukopay.com/v1, for sandbox and live alike — the API key decides the environment, so there is no second base URL to configure. See sandbox vs live mode.
  • One security scheme: the API key in the X-Api-Key header.
  • An Idempotency-Key header on write requests — see what is an idempotency key.
  • Stable operation ids — createOrder, retrieveOrder, listOrders, createRefund, listBalanceTransactions, createWebhookEndpoint and so on — grouped by tags (Orders, Refunds, Disputes, Balance, PaymentLinks, Webhooks, Events, Logs). Generators turn them into method names.
  • Schemas for every object and for the error envelope, including the error code catalogue — see payment API error handling.

Option 1: TypeScript types only

If you already have an HTTP client and just want the compiler to check your requests and responses, generate types:

npx openapi-typescript https://api.kukopay.com/v1/openapi.json -o src/kukopay.d.ts

You get the request and response shapes of every operation, with enums as string unions — so status === "payed" fails to compile.

Option 2: a full client SDK

To generate methods as well as models, use OpenAPI Generator and choose your language:

npx @openapitools/openapi-generator-cli generate \
  -i https://api.kukopay.com/v1/openapi.json \
  -g python \
  -o ./kukopay-client

Swap -g python for typescript-fetch, go, java, php or another generator. The spec is OpenAPI 3.1; check that the generator and version you pick support 3.1 well enough for your language, and read the generated code once before depending on it.

Whatever generates it, configure the client the same way: the base URL https://api.kukopay.com/v1, the X-Api-Key header from your server's secret store, and an Idempotency-Key on writes you may retry.

Option 3: import into Postman

In Postman, Import the spec URL to get a collection with one request per operation. Set the X-Api-Key at collection level with a kuko_test_ key and you can create sandbox orders, refunds and webhook endpoints by hand — handy for exploring before you write code. Keep live keys out of shared workspaces.

Contract tests: keep the client and the API in step

A generated client is only as good as the spec it came from. Two habits keep it right:

  • Regenerate in CI. Fetch openapi.json, regenerate, and fail the build if the generated code changed without a commit — a new enum value or field shows up as a diff you review, not as a surprise in production.
  • Validate responses in your sandbox tests. Run your integration tests against the sandbox and validate each response against the spec's schema with your language's OpenAPI validator. A mismatch points at your mapping code, not at a payment.

What a generated client does not do for you

  • Webhooks. Verifying X-KukoPay-Signature and deduplicating events is code you write — see how to verify webhook signatures.
  • Retries and rate limits. Decide what to retry by error type, and honour Retry-After on 429 — see API rate limits.
  • Pagination. Loop on has_more with starting_after — see cursor-based pagination.
  • Logging request_id. Keep it from every response; it is what support asks for.

Summary

  • An OpenAPI spec lets you generate an API client instead of hand-writing HTTP calls;
  • KukoPay's OpenAPI 3.1 spec is public at https://api.kukopay.com/v1/openapi.json and generated from the server code, so enums and error codes match the live API;
  • generate TypeScript types with openapi-typescript, a full SDK with OpenAPI Generator, or import it into Postman;
  • one base URL serves sandbox and live, authenticated with X-Api-Key; add Idempotency-Key on writes;
  • regenerate in CI, validate sandbox responses against the spec, and still write webhook verification, retries and pagination yourself.

Try it in the sandbox

Create a merchant account and request a test key. The sandbox needs no business verification.