Create a new wallet

Create a new wallet with the specified attributes.

Provisioning is asynchronous for partner-backed products: KOBBLE_AUD_2, KOBBLE_AUD_3 and KOBBLE_FX_1 wallets are returned PENDING and flip to ACTIVE (with bank details attached where the product issues them) once the partner provisions the account — signalled by a wallet-update webhook. Only KOBBLE_AUD_1 (ledger-only) is created ACTIVE immediately.

KOBBLE_FX_1 specifics: one FX wallet per holder per currency (a duplicate is rejected with 400; a PERMANENTLY_CLOSED one may be re-provisioned), and the wallet holder must meet the FX identity requirements — an incomplete holder is rejected with 422 and a machine-readable missing list of dotted enduser field paths (plus structured stakeholder requirements for companies): complete the enduser (PATCH /customers/v1/endusers/{id} and its stakeholders), then retry. The requirements are: persons — person.birthday and address (line1/city/postal_code/country); companies — registration details (registration_number/registration_type/legal_form/country_of_registration), registered address, and at least one stakeholder with role REPRESENTATIVE that has a phone_number.

Wallet creation may also be gated on the holder's verification when the client's verification program gates WALLET_CREATE: an unverified holder is rejected until their verification is APPROVED.

Not idempotent. This endpoint does not honour Idempotency-Key. Sending the header is not an error and has no effect: the request executes every time, and a retry creates a second record. Deduplication is the caller's responsibility.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Wallet created. KOBBLE_AUD_1 wallets are created ACTIVE synchronously. KOBBLE_AUD_2 wallets are created PENDING and move to ACTIVE (with bank details attached) or PERMANENTLY_CLOSED via asynchronous partner provisioning.

Bodyapplication/json

Example

{
    "id": "73557536-d005-4488-9d0c-aabe48705595",
    "external_id": "11111",
    "created_at": "2025-01-14T16:56:58.947Z",
    "updated_at": "2025-01-14T16:56:58.947Z",
    "holder_id": "db13f0b1-dbb8-4476-9e31-fb93bcb3ec33",
    "asset": "AUD",
    "asset_class": "CURRENCY",
    "status": "ACTIVE",
    "partner_product": "KOBBLE_AUD_1",
    "total_amount": 0,
    "amount": 0,
    "reserved_amount": 0,
    "account_number": null,
    "bank_code_type": null,
    "bank_code": null,
    "owner": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden