Confirmed behavioral inconsistencies that have not yet been fixed, with guidance for avoiding them now.
Known Issues
This page documents behavior we have confirmed is undesirable but have not yet changed. None raises an explicit error; without this documentation, you would discover it in production and waste time questioning your integration.
Each item explains what to do now. Code following that guidance will not need changing after our fix.
K-001 · Card Application Status Differs Between Two Endpoints
Symptoms
POST /v1/cards/applications returns status: "pending" at creation; querying the same application with GET /v1/cards/applications/{id} returns status: "pending_merchant_funds"。
Creation uses a reduced set of three states, whereas retrieval exposes the full internal set of 20.
Why It Matters
A status mapping built from the creation response will not recognize pending_merchant_funds. An order queued for insufficient merchant prepaid funds then enters your default branch, and most implementations use default to treat unknown states as failures.
What to Do Now
Treat pending_merchant_funds as pending, and handle all unknown in-progress states as still processing: continue polling, and hardcode only the 5 terminal states. See State Machines and Values.
Planned Fix: standardize on the reduced representation, including for retrieval (three in-progress values plus terminal states).
K-002 · form_factor, Not product_id, Determines the Form Factor
Symptoms
POST /v1/cards/applications determines the form factor solely from the body's form_factor: physical means a physical card. Every other value—including capitalized Physical and omission—is treated as virtual. There is no spelling validation or error response.
The product row selected by product_id also has a form factor, which we read when resolving the product but do not use. Consequently:
| Input | Actual result |
|---|---|
A physical-card product's product_id, without form_factor | Virtual card |
A virtual-card product's product_id + form_factor: "physical" | Physical-card flow |
form_factor: "Physical" (capitalized) | Virtual card |
Why It Matters
You may believe you ordered a physical card but receive a virtual one—and the ledger still reconciles because shipping is charged only for physical cards; the virtual-card flow charges none, so both sides remain consistent. This is usually discovered when a member asks when their card will arrive.
What to Do Now
Send both product_id and form_factor, and ensure they agree. Use a lowercase constant for form_factor; do not construct it dynamically or pass through user input. After placing the order, retrieve its details and verify the returned form_factor before informing the member.
Planned Fix: when product_id is supplied, use the product row's form factor; return 400 for conflicting values or an unrecognized form_factor.
K-003 · Omitting client_key Generates a Random Value
Symptoms
If client_key is omitted from POST /v1/cards/applications, this permanent, database-backed business idempotency key is generated randomly.
Why It Matters
The x-idempotency-key request header has a 24-hour window. After 24 hours, resending the same body is blocked by neither key: a second card really will be issued, and the issuing fee will be charged again.
What to Do Now
Supply client_key yourself, using your business record's primary key. It is the only permanent idempotency key.
Planned Fix: retain the default random generation, which is safer than a fixed default, but echo the effective client_key in the creation response so you can verify it.
K-004 · Some Endpoints Return an Empty failure_code, Not null
Symptoms
When a specific failure reason is unavailable, failure_code is "".
What to Do Now
Use a falsy check (if (!failure_code)), not === null. Apply this rule to all optional string fields in responses.
Resolved Issues (Archived So You Can Retire Workarounds)
| Date | Previous issue | Current behavior |
|---|---|---|
| 2026-08-14 | The retired internal-transfer recipient-type endpoint was captured by /v1/transfers/{id}; the first step of the transfer flow never worked | Fixed; a route-shadowing guard prevents recurrence |
| 2026-08-14 | The authentication guide instructed callers to send x-zise-merchant, but nothing reads it | Removed from the guide, Postman collection, and three sample tools |
| 2026-08-14 | Card issuance, transfers, wealth, and QR Pay lacked the data needed for confirmation screens | Five read-only endpoints; see the corresponding guides |
| 2026-08-14 | Merchants could not retrieve the individual remittance account agreement, despite submission recording acceptance | GET /v1/remit/vp/agreement |
| 2026-08-14 | A stalled card application could only be left to fail | cancel-preview + cancel |
| 2026-08-14 | Locked CVV access permanently prevented viewing card credentials | POST /v1/cards/{id}/cvv/unblock |
| 2026-08-14 | Rejection exposed no explanation | GET /v1/kyc includes reject_reason / l2_reject_reason |
| 2026-08-14 | A name or document change required recreating the member, leaving funds and cards on the old account | POST /v1/kyc/profile-sessions |
| 2026-08-14 | No way to change a member's email | POST /v1/members/{id}/email-sessions (hosted page; two verification codes) |
| 2026-08-14 | Members created through OpenAPI had no member number, although uid is the default transfer recipient type | Assigned at account creation |
| 2026-08-14 | Card supplements had no end-user submission flow (submit_url was always empty) | POST /v1/cards/applications/{id}/supplement-sessions obtains a hosted-page link; details now use submit_via |
| 2026-08-14 | OpenAPI had no shipping-address endpoints, so no physical cards could be issued | Five /v1/shipping-addresses endpoints (new scopes addresses:read / addresses:write) |
| 2026-08-14 | QR Pay corridors requiring payer information could not be submitted through OpenAPI | Both quotes and payments accept payer |
| 2026-08-14 | Enabling step-up authentication on an exchange direction made execution through OpenAPI permanently impossible | step_up_required includes hosted_url; verify, then resend with x-step-up |
| 2026-08-14 | Transfer and wealth require_step_up settings were not enforced in OpenAPI, making the security guarantee ineffective | Both enforced through a two-stage hosted flow |
| 2026-08-14 | QR Pay had no second confirmation | Every payment requires step-up authentication, equivalent to the member app's payment ticket |
| 2026-08-13 | No public L2 submission path | POST /v1/kyc/l2/sessions, using the same hosted-page pattern as L1 |
| 2026-08-13 | GET /v1/kyc/requirements listed five businesses, omitting QR Pay, withdrawals, and transfers | Expanded to nine; QR Pay also exposes kyc_trigger_amount |
| 2026-08-13 | REJECTED appeared as none, indistinguishable from never applied | Added rejected to status |
| 2026-08-13 | A supplement list spanning L1/L2 omitted the level | Response includes level |
Reporting a New Issue
Contact us with the response's request_id, which identifies the exact call. Once confirmed, the issue will be added here with guidance on what to do now.