Card Creation Flow — Developer Guide & Onboarding

Overview

This guide describes the Card Creation flow for the Kobble Card API. It is intended for developers integrating with Kobble so they can onboard and implement card issuance without additional support. All critical operational and integration details are covered here.

Related documentation:

Authorization — how to obtain an access token

Base URLs:

Development: https://dev.apikobble.net/

Staging: https://staging.apikobble.net/

Prerequisites

Before calling Create Card, the following must exist and satisfy the conditions below. They must be created in order.

#	Prerequisite	Description	How to obtain
1	Enduser	The person or company that will “hold” the wallet and card. For card creation, the enduser must be of type person (not company), with `first_name`, `last_name`, `email`, and `phone_number`.	`POST /api/endusers` with `person` payload. Store the returned `id`.
2	Wallet	An ACTIVE wallet linked to that enduser via `holder_id`. The wallet must not already have an `external_id` (i.e. it must not already be linked to a card/entity).	`POST /api/wallets` with `holder_id` = enduser `id`, plus `asset`, `asset_class`, `partner_product`. Store the returned `id`.
3	Program ID	A valid, ACTIVE card program. The program’s `metadata` must conform to the card product (e.g. `MetadataKobbleDebit1`: `parent_account_id`, `product_id`; optional `group_id`).	Create/configure program via Kobble (or `POST /api/programs` if exposed). Store the program `id`.

Prerequisite details

Enduser (person):

Must belong to the same client (owner) as the one making the Card API request.

Must have person data (not only company). Card creation uses person.first_name, person.last_name, person.email, person.phone_number for the card product and 3DS enrolment.

Wallet:

holder_id must be the enduser id.

status must be ACTIVE.

external_id must be null. If the wallet already has an external_id, it is considered linked to another entity; card creation will fail with Invalid wallet with existing entity association.

Program:

Must exist and be ACTIVE.

For Kobble Debit 1–style programs, metadata must include at least:

parent_account_id (string)

product_id (string)

group_id (optional, array of strings)

Step-by-step flow for creating a card

Obtain an access token
Use your client credentials and the Authorization flow. Send this token as Authorization: Bearer {access_token} on every Card API request.

Create an enduser (person)
POST /api/endusers with a JSON body containing person (e.g. first_name, last_name, email, phone_number).
→ Response includes id. This is the enduser id.

Create a wallet
POST /api/wallets with:

holder_id: the enduser id from step 2

asset, asset_class, partner_product as required by your product
→ Response includes id. This is the wallet id.

Create the card
POST /api/cards with:

Headers: Authorization: Bearer {access_token}, idempotency-key: {unique-key}, x-client-id: {client-id}

Body: { "wallet_id": "<wallet-id>", "program_id": "<program-id>" }
→ Response is the created Card resource (e.g. id, wallet_id, program_id, status, external_id, last_four_digit, expiry, etc.).

Optional: activate or manage the card
Use Update Card Status (PATCH /api/cards/:id/status) or other Card API endpoints as needed.

Sequence diagram

The following diagram shows the client-side call sequence: the order in which your application calls Kobble endpoints to create a card. It is intended for developers integrating with the Kobble API and does not describe Kobble’s internal systems.

Example call chain

1. Create enduser (person)

Example response: { "id": "550e8400-e29b-41d4-a716-446655440001", ... }
→ Use this id as holder_id when creating the wallet.

2. Create wallet

Example response:

{ "id": "660e8400-e29b-41d4-a716-446655440002", "holder_id": "550e8400-...", "status": "ACTIVE", "external_id": null, ... }

→ Use this id as wallet_id when creating the card.

3. Create card

Example response (201 Created):

{
  "id": "990e8400-e29b-41d4-a716-446655440005",
  "wallet_id": "660e8400-e29b-41d4-a716-446655440002",
  "program_id": "880e8400-e29b-41d4-a716-446655440004",
  "status": "INACTIVE",
  "external_id": "12345",
  "last_four_digit": "4242",
  "expiry": "2027-12-31T23:59:59.000Z",
  "type": "VIRTUAL",
  "m_pan": "...",
  "owner": "<client-id>",
  "created_at": "...",
  "updated_at": "..."
}

Request and response reference (Create Card)

Item	Value
Method	`POST`
Path	`/api/cards`
Headers	`Authorization: Bearer {access_token}`, `x-client-id: {client-id}`, `idempotency-key: {unique-key}`, `Content-Type: application/json`
Body	`wallet_id` (UUID), `program_id` (UUID)
Success	`201 Created` — body is the created Card object
Idempotency	Same `idempotency-key` within a time window returns the same created card and does not create a duplicate. Always send a unique key per logical “create” request (e.g. UUID).

Validation and error behaviour

The service validates in this order; the first failure returns the corresponding error:

Order	Check	Error (typical message / scope)
1	Program exists and is valid	Invalid program id (User)
2	Program metadata valid (e.g. MetadataKobbleDebit1)	Invalid metadata (User)
3	Wallet exists, status ACTIVE, owner match	Invalid or dormant wallet (User)
4	Wallet has no `external_id`	Invalid wallet with existing entity association (User)
5	Enduser exists for `wallet.holder_id`	Invalid enduser associated with wallet (User)
6	Enduser belongs to requesting client (owner)	Enduser does not belong to requesting client (User)
7	Enduser has `person` (not only company)	Unsupported enduser entity type (User)
8	Card provider (e.g. Paymentology) succeeds	Unable to create card (Runtime) or provider error

Standard HTTP status codes apply (e.g. 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error). Use the response body and headers as defined in the Cards API and your contract.

Idempotency

Header: idempotency-key (required for POST /api/cards).

Use a unique value per logical “create card” operation (e.g. UUID).

If the same key is sent again within the configured idempotency window, the API returns the same created card without creating a second one.

This avoids duplicate cards when retrying after timeouts or network errors.

Outcome

With this guide, developers can:

Understand the prerequisites (enduser → wallet → program-id) and create them in the correct order.

Follow the step-by-step flow and the sequence diagram to see how the Card API interacts with Programs, Wallets, Endusers, and the card provider.

Use the example call chain to implement and test card creation.

Handle validation and errors and use idempotency correctly.

For exact request/response schemas, error codes, and environment-specific behaviour, use the Cards API documentation.

Card Creation Flow — Developer Guide & Onboarding

Overview#

Prerequisites#

Prerequisite details#

Step-by-step flow for creating a card#

Sequence diagram#

Example call chain#

1. Create enduser (person)#

2. Create wallet#

3. Create card#

Request and response reference (Create Card)#

Validation and error behaviour#

Idempotency#

Outcome#