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.
On this page
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.jsonIt 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-Keyheader. - An
Idempotency-Keyheader on write requests — see what is an idempotency key. - Stable operation ids —
createOrder,retrieveOrder,listOrders,createRefund,listBalanceTransactions,createWebhookEndpointand 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.tsYou 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-clientSwap -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-Signatureand 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-Afteron429— see API rate limits. - Pagination. Loop on
has_morewithstarting_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.jsonand 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; addIdempotency-Keyon 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.