Essentials

What holds for every endpoint. Read it once before you build; the reference pages assume it.

Authentication#

Send your key as a header on every request. Two forms are accepted and resolve to the same key; if you send both, X-API-Key wins. The bearer form is matched case insensitively.

X-API-Key: ktap_live_EXAMPLE0_REPLACE_WITH_YOUR_OWN_KEY_NOT_A_REAL_ONE

Each endpoint requires exactly one scope. A key without it gets 403 naming the scope, never a partial result. Scopes are set when we issue the key and cannot be changed through the API.

A 401 means the key is missing, unknown, revoked or the account is suspended, and all four return an identical body so probing cannot enumerate keys. Neither 401 nor 403 carries rate limit headers, because both are decided before the limiter runs. An unmatched path returns 404 before authentication, so a URL typo looks the same whatever your key is.

Requests and responses#

Every path in the reference is relative to https://virtual.ktap.io/api/partner/v1. HTTPS only. A successful response wraps its payload in data; a failure returns error and code at the top level and no data.

{
  "data": {
    "id": "7Kd2mQ4rTz9XbW1sYh6vN0pLcE3fJa8u",
    "status": "ACTIVE"
  }
}

• Send Content-Type: application/json on any request with a body, and make the body a JSON object. An array, a string or a bare number is rejected with 400.
• Unknown fields are ignored rather than rejected, so a forward-compatible client can send extra keys safely.
• Money is sent and returned as a JSON number in US dollars, never in cents. Amounts you send take at most two decimal places and are rejected, never rounded, above that.
• Parse every amount as an exact decimal: a float rounded to cents will not reconcile. Webhook amounts are passed through unrounded, and the fee on card.authorized routinely carries more than two decimals. Rows from GET /cards/{id}/transactions are the exception: the card processor reports them to the cent.
• Timestamps are ISO 8601 UTC. Webhook and API timestamps carry a Z suffix; the one exception in FORMAT is the datetime on a card transaction, which is also UTC but carries no offset and no Z, so append Z before parsing it.
• A path called with a method it does not implement returns 405 with an Allow header, decided before authentication.

Errors#

That is the whole enum. A code in this field is always ours: no card processor error code is ever passed through, and a 429 is always our own rather than an upstream one. UNAVAILABLE is the one code that carries three meanings, separated by status: 500 is unknown, 502 means the processor failed, and 503 means nothing happened.

X-RateLimit-Limit and X-RateLimit-Remaining are present on any response a handler returns, including most failures, and absent on 401, 403, 405, an unmatched-path 404, and most 500, 502 and 503. Read them defensively rather than assuming they are there.

Idempotency#

Three endpoints move money and all honour an Idempotency-Key header. Always send one on POST /cards, on a top-up and on an unload. POST /cards/{cardId}/close needs no key: it is idempotent on the card id. POST /funding needs no key either: it is idempotent on the transaction hash. Everywhere else the header is recorded in your request log and has no effect.

• One key per logical operation, not per attempt. Reuse the same key for every retry of the same intent.
• Format is [A-Za-z0-9_-], 1 to 128 characters. A UUID is a good default. Colons are rejected, because the key becomes a ledger reference and we derive completion markers by appending suffixes.
• Keys are scoped to your account, so they cannot collide with another partner's.
• A top-up or unload key is bound to the card it was first used on. Replaying it against a different card is refused rather than answered with a success about money that went elsewhere.
• Once the first call settles, a replay returns the original result including the original fee. Concurrent calls under one key are safe: exactly one executes and the others get 409 while it is in flight.

The four conflict cases#

All four return 409 ALREADY_PROCESSED and the correct action differs. Three carry distinct messages; the fourth reads like the first and reveals itself by refusing to clear.

If the same key keeps returning 409 for longer than a few minutes, stop and email dev@ktap.io with the key rather than working around it.

Pagination#

Five endpoints page, and they do not share an idiom. page is 1-based; offset is 0-based and counts rows.

• GET /cards, GET /ledger and GET /events return newest first; fleet pages of POST /cards/balances walk the fleet in creation order, oldest first. Card transactions follow the card processor's ordering, which is not guaranteed, so reconcile by walking explicit from_date and to_date windows rather than relying on order.
• Read total from a page that returned rows. On GET /ledger, GET /events and a fleet page of POST /cards/balances, a page past the end returns total 0 and total_pages 1 even though earlier pages hold data.
• limit=0 is treated as 1 rather than returning an empty page, and page=0 becomes page 1. The exception is POST /cards/balances, which rejects a limit under 1 with 400.
• GET /cards excludes closed cards, while cards.total on GET /me counts lifetime issuance, so the two disagree as soon as any card has been closed.
• POST /cards/balances pages your whole fleet when you omit card_ids, and is the endpoint to reach for instead of calling GET /cards/{cardId} per card. It reads from our balance model, so it answers instantly whatever the fleet size.

Rate limits#

• The default is 120 requests per minute, but read key.rate_limit_per_minute from GET /me rather than hardcoding it.
• The limit is per key, not per account, over a rolling 60-second window. Put a bulk job on its own key so it cannot starve your interactive traffic.
• A 429 RATE_LIMITED carries Retry-After: 60. That is a fixed upper bound rather than the moment your oldest request ages out, so you can often resume sooner. A 429 TOO_MANY_PENDING from POST /funding is not a rate limit and carries no Retry-After.
• A 429 is itself a request and counts against your window. Sleep before retrying: a tight loop keeps the window full and extends the block.
• There is no X-RateLimit-Reset. Treat a missing rate limit header as unknown rather than as zero.

Changes and compatibility#

Under v1 we will not remove a field or an endpoint, repurpose the meaning of an existing field, make an optional request field required, change the envelope, or return a new error code from an existing endpoint. A new endpoint can introduce codes of its own, and those are returned only by that endpoint: ALREADY_SUBMITTED, ALREADY_CREDITED and TOO_MANY_PENDING come only from POST /funding. Apart from one exception, an exhaustive switch on the codes an endpoint documents is therefore safe. The exception, made on 2026-09-28: POST /cards and PUT /cards/{cardId}/phone answer INVALID_NAME, INVALID_EMAIL, INVALID_PHONE and PHONE_COUNTRY_NOT_ALLOWED where they answered BAD_REQUEST, so the reason shows wherever the code does. The status is still 400.

What can change without notice: the error message string, new fields on existing responses, and new values in any enum other than code, including card statuses, transaction statuses, decline reasons and funding reasons. Two rules keep a client working across releases: ignore unknown fields, and give every enum a default branch. Your rates change only by agreement with you; read them from GET /fees rather than hardcoding them.

The OpenAPI 3.1 document is served unauthenticated at `/api/partner/v1/openapi.json` and cached for five minutes. Every page here is also available as Markdown by appending .md to its URL, and the whole site as one file at `/llms-full.txt`, which is the thing to hand an agent.

Before you go live#

There is no sandbox, so going live is a checklist rather than a switch. Build against real cards you control: issue a few, fund them with small amounts, exercise the paths you care about, then close them. Tag them with a recognisable partner_ref so you can find them again. You cannot simulate a purchase, a decline or a 3-D Secure challenge.

Watch cards.total against cards.limit on GET /me: the allowance is for life and closing a card does not return capacity. When it runs out, POST /cards returns 409 QUOTA and no amount of retrying helps. For anything in production, email dev@ktap.io with the key prefix, the card id, the idempotency key and the time in UTC.