{"openapi":"3.0.3","info":{"title":"Pintopay Onpremise B2B API","version":"v2","description":"B2B card issuance API. All requests use NaCl box encryption. Schemas describe the decrypted payload structure.","contact":{}},"paths":{"/api/v2/system/health":{"post":{"operationId":"post~v2_system_bp.system_health","summary":"System health","tags":["System"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SystemHealthResponse"}]}}},"description":"Service is healthy."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload or decryption failed."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid or project not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemHealthRequest"}}}},"description":"Health check endpoint. POST + encrypted variant of GET /api/health for corpapi compatibility."}},"/api/v2/system/time":{"post":{"operationId":"post~v2_system_bp.system_time","summary":"System time","tags":["System"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SystemTimeResponse"}]}}},"description":"Current server timestamp."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload or decryption failed."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid or project not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemTimeRequest"}}}},"description":"Returns the current server timestamp in microseconds. No request_timestamp required - call this first to synchronize the client clock."}},"/api/v2/project/balance":{"post":{"operationId":"post~v2_project_bp.project_balance","summary":"Get project balance","tags":["Project"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProjectBalanceResponse"}]}}},"description":"Project balance."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Project not found","error_slug":"project_not_found"}}},"description":"Project not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectBalanceRequest"}}}},"description":"Returns the project's available USDT balance."}},"/api/v2/project/txs":{"post":{"operationId":"post~v2_project_bp.project_txs","summary":"Get project master-account operations","tags":["Project"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProjectTxsResponse"}]}}},"description":"Project master-account operations."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Project not found","error_slug":"project_not_found"}}},"description":"Project not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectTxsRequest"}}}},"description":"Returns project master-account history: incoming topups and spends for card issue/topup/withdraw flows. Use it to reconcile project balance movements."}},"/api/v2/project/wallet/trc20":{"post":{"operationId":"post~v2_project_bp.project_wallet_trc20","summary":"Get TRC20 deposit address","tags":["Project"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ProjectWalletTrc20Response"}]}}},"description":"TRC20 deposit address."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Project TRC20 wallet not configured","error_slug":"wallet_not_found"}}},"description":"Project or TRC20 wallet not configured."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectWalletTrc20Request"}}}},"description":"Returns the project's USDT TRC20 deposit wallet address."}},"/api/v2/users/find":{"post":{"operationId":"post~v2_users_bp.find_users","summary":"Find users","tags":["Users"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FindUsersResponse"}]}}},"description":"Paginated user list."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindUsersRequest"}}}},"description":"Returns a paginated list of project users. Supports explicit filters: `external_user_id(s)`, `user_id(s)`, `created_from`, `created_to`. Sort supports: `user_id`, `external_user_id`, `created_at`, `updated_at`."}},"/api/v2/users/create":{"post":{"operationId":"post~v2_users_bp.create_user","summary":"Create user","tags":["Users"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateUserResponse"}]}}},"description":"User created successfully."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"external_user_id cannot be empty","error_slug":"validation_error"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Project not found","error_slug":"project_not_found"}}},"description":"Project not found."},"409":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"User already exists","error_slug":"user_already_exists"}}},"description":"User with this external_user_id already exists."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}}},"description":"Creates a new project user identified by `external_user_id`."}},"/api/v2/users/get":{"post":{"operationId":"post~v2_users_bp.get_user","summary":"Get user","tags":["Users"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetUserResponse"}]}}},"description":"User found."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"external_user_id cannot be empty","error_slug":"validation_error"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"User not found","error_slug":"user_not_found"}}},"description":"User not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetUserRequest"}}}},"description":"Returns a project user by `external_user_id`."}},"/api/v2/cardholders/find":{"post":{"operationId":"post~v2_cardholders_bp.find_cardholders","summary":"Find cardholders","tags":["Cardholders"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FindCardholdersResponse"}]}}},"description":"Paginated cardholder list."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindCardholdersRequest"}}}},"description":"Returns a paginated list of cardholders within the project. Supports explicit filters: `cardholder_id(s)`, `external_user_id(s)`, `user_id(s)`, `subprovider_code(s)`, `product_code(s)`, `registration_status(es)`, `kyc_status(es)`. Sort supports: `cardholder_id`, `user_id`, `subprovider_code`, `product_code`, `registration_status`, `kyc_status`, `created_at`, `updated_at`, `registered_at`, `activated_at`."}},"/api/v2/cardholders/create":{"post":{"operationId":"post~v2_cardholders_bp.create_cardholder","summary":"Create cardholder","tags":["Cardholders"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateCardholderResponse"}]}}},"description":"Cardholder created successfully."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Unexpected KYC fields: field1, field2","error_slug":"kyc_unexpected_fields"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Subprovider not found","error_slug":"subprovider_not_found"}}},"description":"User not found (after auto-create attempt)."},"409":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Cardholder already exists","error_slug":"cardholder_already_exists"}}},"description":"Cardholder already exists for this user and subprovider."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardholderRequest"}}}},"description":"Saves KYC data for a user under the given subprovider. May require card product code depending on subprovider configuration. Required before issuing a card. If the user does not exist yet, it is created automatically."}},"/api/v2/cardholders/get":{"post":{"operationId":"post~v2_cardholders_bp.get_cardholder","summary":"Get cardholder","tags":["Cardholders"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetCardholderResponse"}]}}},"description":"Cardholder found."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"subprovider_code or subprovider_id is required when external_user_id is provided","error_slug":"validation_error"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"CardHolder not found","error_slug":"cardholder_not_found"}}},"description":"Neither cardholder_id nor external_user_id provided."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCardholderRequest"}}}},"description":"Returns a cardholder by `cardholder_id`, or by `external_user_id` + (`subprovider_code` preferred, `subprovider_id` legacy)."}},"/api/v2/cards/txs":{"post":{"operationId":"post~v2_cards_bp.card_txs","summary":"Card transactions","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CardTxsResponse"}]}}},"description":"Normalized card transactions."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardTxsRequest"}}}},"description":"Returns normalized card transactions. Items use the same shape as card_transaction webhooks and can be correlated by transaction_id."}},"/api/v2/cards/find":{"post":{"operationId":"post~v2_cards_bp.find_cards","summary":"Find cards","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FindCardsResponse"}]}}},"description":"Paginated card list."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindCardsRequest"}}}},"description":"Returns a paginated list of cards within the project. Supports explicit filters: `card_id(s)`, `external_user_id(s)`, `user_id(s)`, `status(es)`, `product_code(s)`. Sort supports: `card_id`, `user_id`, `status`, `product_code`, `created_at`, `updated_at`, `issued_at`, `activated_at`, `frozen_at`, `closed_at`."}},"/api/v2/cards/get":{"post":{"operationId":"post~v2_cards_bp.get_card","summary":"Get card","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetCardResponse"}]}}},"description":"Card data."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCardRequest"}}}},"description":"Returns a single card by `card_id` for the given user."}},"/api/v2/cards/3ds/confirm":{"post":{"operationId":"post~v2_cards_bp.confirm_card_3ds","summary":"Confirm OOB 3DS","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ConfirmCard3dsResponse"}]}}},"description":"3DS challenge confirmed."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Securement ID is invalid","error_slug":"securement_id_invalid"}}},"description":"Invalid securement_id or unsupported provider/method."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmCard3dsRequest"}}}},"description":"Confirms or declines an out-of-band 3DS challenge previously received via webhook. Use `securement_id` from the `card_3ds` webhook payload."}},"/api/v2/cards/create":{"post":{"operationId":"post~v2_cards_bp.create_card","summary":"Create card","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateCardResponse"}]}}},"description":"Card issuance started."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"KYC data is required for card issuance","error_slug":"kyc_required"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Product not found","error_slug":"product_not_found"}}},"description":"User not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardRequest"}}}},"description":"Issues a new card for a user. Requires `Idempotency-Key` header. KYC must be submitted via cardholders/create first. Returns immediately — poll orders/check for completion."}},"/api/v2/cards/balance":{"post":{"operationId":"post~v2_cards_bp.card_balance","summary":"Card balance","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CardBalanceResponse"}]}}},"description":"Card balance."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardBalanceRequest"}}}},"description":"Returns the card balance: available and pending amounts."}},"/api/v2/cards/details":{"post":{"operationId":"post~v2_cards_bp.card_details","summary":"Card details","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CardDetailsResponse"}]}}},"description":"Sensitive card credentials."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Plaintext card details are not available for this card","error_slug":"card_details_plaintext_unavailable"}}},"description":"Provider does not expose plaintext card details for this card."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardDetailsRequest"}}}},"description":"Returns plaintext card credentials (PAN/holder/expiry/CVV) as JSON. If the provider cannot expose plaintext, responds 422 with slug `card_details_plaintext_unavailable`."}},"/api/v2/cards/freeze":{"post":{"operationId":"post~v2_cards_bp.freeze_card","summary":"Freeze card","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FreezeCardResponse"}]}}},"description":"Card frozen."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid card status transition","error_slug":"invalid_status_transition"}}},"description":"Invalid status transition (e.g. card already frozen or closed)."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeCardRequest"}}}},"description":"Freezes a card, preventing all transactions. Card must be `active`."}},"/api/v2/cards/products":{"post":{"operationId":"post~v2_cards_bp.card_products","summary":"List card products","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CardProductsResponse"}]}}},"description":"Available card products."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardProductsRequest"}}}},"description":"Returns available card products. Use `product_code` from this response in cards/create."}},"/api/v2/cards/unfreeze":{"post":{"operationId":"post~v2_cards_bp.unfreeze_card","summary":"Unfreeze card","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UnfreezeCardResponse"}]}}},"description":"Card unfrozen."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User or card not found."},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid card status transition","error_slug":"invalid_status_transition"}}},"description":"Invalid status transition (e.g. card is not frozen)."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnfreezeCardRequest"}}}},"description":"Unfreezes a card, restoring normal operation. Card must be `frozen`."}},"/api/v2/cards/withdraw":{"post":{"operationId":"post~v2_cards_bp.withdraw_card","summary":"Withdraw card balance","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WithdrawCardResponse"}]}}},"description":"Withdraw completed."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Operation in progress for this idempotency key","error_slug":"idempotency_conflict"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User not found."},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card withdraw is not supported for this provider","error_slug":"provider_withdraw_not_supported"}}},"description":"Card cannot be withdrawn from in its current status."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawCardRequest"}}}},"description":"Withdraws funds from a card back to the project master account. Requires `Idempotency-Key` header. Only USDT is supported."}},"/api/v2/cards/topup":{"post":{"operationId":"post~v2_cards_bp.topup_card","summary":"Topup card","tags":["Cards"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/TopupCardResponse"}]}}},"description":"Topup initiated."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Operation in progress for this idempotency key","error_slug":"idempotency_conflict"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Insufficient project balance","error_slug":"insufficient_funds"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card not found","error_slug":"card_not_found"}}},"description":"User not found."},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Card is not active","error_slug":"card_not_active"}}},"description":"Card is not in active status (cannot topup)."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupCardRequest"}}}},"description":"Tops up a card from the project balance. Requires `Idempotency-Key` header. Only USDT is supported. Deducts from project balance before calling the provider."}},"/api/v2/orders/check":{"post":{"operationId":"post~v2_orders_bp.check_order","summary":"Check order","tags":["Orders"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CheckOrderResponse"}]}}},"description":"Order status."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Order not found","error_slug":"order_not_found"}}},"description":"Order not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckOrderRequest"}}}},"description":"Returns the current status of an order by `order_id`. A newly created order may take up to 30s to appear."}},"/api/v2/wh/subscriptions":{"post":{"operationId":"post~v2_webhooks_bp.wh_subscriptions","summary":"List subscriptions","tags":["Webhooks"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListSubscriptionsResponse"}]}}},"description":"Webhook subscriptions."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSubscriptionsRequest"}}}},"description":"Returns all webhook subscriptions for the authenticated project."}},"/api/v2/wh/unsubscribe":{"post":{"operationId":"post~v2_webhooks_bp.wh_unsubscribe","summary":"Unsubscribe webhook","tags":["Webhooks"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UnsubscribeWebhookResponse"}]}}},"description":"Subscription deactivated."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Invalid encrypted payload format","error_slug":"decryption_failed"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Subscription not found","error_slug":"subscription_not_found"}}},"description":"Subscription not found."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsubscribeWebhookRequest"}}}},"description":"Deactivates a webhook subscription by `subscription_id`. No further events will be delivered."}},"/api/v2/wh/subscribe":{"post":{"operationId":"post~v2_webhooks_bp.wh_subscribe","summary":"Subscribe webhook","tags":["Webhooks"],"parameters":[{"name":"API-KEY","schema":{"type":"string"},"description":"Project API key.","required":true,"in":"header"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubscribeWebhookResponse"}]}}},"description":"Subscription created."},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"webhook_url must use HTTPS","error_slug":"invalid_webhook_url"}}},"description":"Bad request: invalid payload, missing or expired encrypted payload, timestamp error, or duplicate request."},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"API key not found","error_slug":"api_key_not_found"}}},"description":"API-KEY header missing."},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"You do not have access to this API.","error_slug":"api_key_invalid"}}},"description":"API key invalid, project not found, or API secret decryption failed."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiError"}]},"example":{"success":false,"error":"Internal server error","error_slug":"internal_error"}}},"description":"Internal server error or unhandled auth error."}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeWebhookRequest"}}}},"description":"Subscribes to event notifications. The server will POST events to `webhook_url` (HTTPS only)."}},"/simulate/cards/refund":{"post":{"operationId":"post~Simulation.simulate_refund","summary":"Simulate refund","tags":["Simulation"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success","title":"Success"},"transaction":{"type":"object","description":"Created transaction record (provider_item). Common fields: `recordNo`, `occurTime`, `merchantName`, `amount`, `currency`, `status`, `type`, `transaction_id`. Clear adds `clearedAt`, `transactionAmount`, `transactionCurrency`. Refund adds `originalTransactionId`. Reversal adds `reversedAt`, `transactionAmount`.","title":"Transaction","additionalProperties":{}}}}}},"description":"Refund created"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transactionId":{"type":"string","description":"recordNo of the original transaction to refund","title":"Transactionid"},"transactionAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Refund amount; defaults to original amount","title":"Transactionamount","nullable":true},"billAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Billing refund amount","title":"Billamount","nullable":true}}}}}},"description":"Simulate a refund against a settled (cleared) transaction. Returns the specified amount back to the card balance.\n\nNotes:\n- `transactionId` is the `recordNo` of the original transaction\n- Partial refunds supported via `transactionAmount`/`billAmount`"}},"/simulate/cards/reversal":{"post":{"operationId":"post~Simulation.simulate_reversal","summary":"Simulate reversal","tags":["Simulation"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success","title":"Success"},"transaction":{"type":"object","description":"Created transaction record (provider_item). Common fields: `recordNo`, `occurTime`, `merchantName`, `amount`, `currency`, `status`, `type`, `transaction_id`. Clear adds `clearedAt`, `transactionAmount`, `transactionCurrency`. Refund adds `originalTransactionId`. Reversal adds `reversedAt`, `transactionAmount`.","title":"Transaction","additionalProperties":{}}}}}},"description":"Reversal completed"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transactionId":{"type":"string","description":"recordNo of the pending auth to reverse","title":"Transactionid"},"transactionAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Reversal amount; defaults to full auth amount","title":"Transactionamount","nullable":true},"billAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Billing reversal amount","title":"Billamount","nullable":true}}}}}},"description":"Simulate a reversal of a pending authorization. Cancels the hold and releases the amount back to available balance.\n\nNotes:\n- `transactionId` is the `recordNo` of the pending auth to cancel\n- Partial reversals supported via `transactionAmount`/`billAmount`"}},"/simulate/cards/3ds":{"post":{"operationId":"post~Simulation.simulate_3ds","summary":"Simulate 3D Secure","tags":["Simulation"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success","title":"Success"},"transaction":{"type":"object","description":"Created transaction record (provider_item). Common fields: `recordNo`, `occurTime`, `merchantName`, `amount`, `currency`, `status`, `type`, `transaction_id`. Clear adds `clearedAt`, `transactionAmount`, `transactionCurrency`. Refund adds `originalTransactionId`. Reversal adds `reversedAt`, `transactionAmount`.","title":"Transaction","additionalProperties":{}}}}}},"description":"3DS challenge created"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Internal card ObjectId","title":"Card Id","nullable":true},"bankCardId":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Provider-assigned card ID (alternative to card_id)","title":"Bankcardid","nullable":true},"transactionAmount":{"type":"string","description":"Transaction amount as decimal string","title":"Transactionamount"},"transactionCurrency":{"type":"string","default":"USD","description":"Transaction currency (ISO 4217)","title":"Transactioncurrency"}}}}}},"description":"Simulate a 3D Secure verification challenge. Emits a card_otp webhook for the card without creating a financial transaction or changing balance.\n\nNotes:\n- Look up by `card_id` (internal ObjectId) or `bankCardId` (provider card ID)"}},"/simulate/cards/auth":{"post":{"operationId":"post~Simulation.simulate_auth","summary":"Simulate authorization","tags":["Simulation"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success","title":"Success"},"transaction":{"type":"object","description":"Created transaction record (provider_item). Common fields: `recordNo`, `occurTime`, `merchantName`, `amount`, `currency`, `status`, `type`, `transaction_id`. Clear adds `clearedAt`, `transactionAmount`, `transactionCurrency`. Refund adds `originalTransactionId`. Reversal adds `reversedAt`, `transactionAmount`.","title":"Transaction","additionalProperties":{}}}}}},"description":"Authorization created"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Internal card ObjectId","title":"Card Id","nullable":true},"bankCardId":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Provider-assigned card ID (alternative to card_id)","title":"Bankcardid","nullable":true},"transactionAmount":{"type":"string","description":"Authorization amount as decimal string","title":"Transactionamount"},"transactionCurrency":{"type":"string","default":"USD","description":"Transaction currency (ISO 4217)","title":"Transactioncurrency"},"billAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Billing amount; defaults to transactionAmount if omitted","title":"Billamount","nullable":true}}}}}},"description":"Simulate a card authorization hold. Places a pending hold on the card balance for the specified amount, creating a transaction record.\n\nNotes:\n- Look up by `card_id` (internal ObjectId) or `bankCardId` (provider card ID)\n- `billAmount` defaults to `transactionAmount` if omitted"}},"/simulate/cards/clear":{"post":{"operationId":"post~Simulation.simulate_clear","summary":"Simulate clearing","tags":["Simulation"],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success","title":"Success"},"transaction":{"type":"object","description":"Created transaction record (provider_item). Common fields: `recordNo`, `occurTime`, `merchantName`, `amount`, `currency`, `status`, `type`, `transaction_id`. Clear adds `clearedAt`, `transactionAmount`, `transactionCurrency`. Refund adds `originalTransactionId`. Reversal adds `reversedAt`, `transactionAmount`.","title":"Transaction","additionalProperties":{}}}}}},"description":"Clearing settled"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"transactionId":{"type":"string","description":"recordNo of the original auth transaction to settle","title":"Transactionid"},"billAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Settlement amount; defaults to original auth amount","title":"Billamount","nullable":true},"transactionAmount":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Clearing amount; defaults to original auth amount","title":"Transactionamount","nullable":true},"transactionCurrency":{"type":"string","anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Transaction currency (ISO 4217)","title":"Transactioncurrency","nullable":true}}}}}},"description":"Simulate clearing (settlement) of a pending authorization. Finalizes the held amount, settling the transaction on the card.\n\nNotes:\n- `transactionId` is the `recordNo` from the original auth transaction\n- `billAmount` can differ from the original auth amount (partial clear)"}}},"tags":[{"name":"Project","description":"Project balance and deposit wallet."},{"name":"Users","description":"Project user management."},{"name":"Cardholders","description":"Cardholder KYC and management."},{"name":"Cards","description":"Card issuance, details, and lifecycle."},{"name":"Orders","description":"Order tracking."},{"name":"Webhooks","description":"Webhook subscriptions and delivery."},{"name":"System","description":"Service health and time sync."},{"name":"Simulation","description":"Sandbox card transaction simulation."}],"servers":[],"security":[{"ApiKeyAuth":[]}],"components":{"schemas":{"ApiError":{"description":"Standard error response - matches corpapi {success, error, error_slug}.","example":{"error":"Project not found","error_slug":"project_not_found","success":false},"properties":{"success":{"default":false,"description":"Always false on error","title":"Success","type":"boolean"},"error":{"description":"Human-readable error message","title":"Error","type":"string"},"error_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Machine-readable error code","title":"Error Slug"}},"required":["error"],"title":"ErrorResponse","type":"object"},"ProjectBalanceResponse":{"description":"Response for POST /api/v2/project/balance.","example":{"available":"1234.56","currency":"usdt","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"available":{"description":"Available balance as decimal string","title":"Available","type":"string"},"currency":{"description":"Balance currency, always 'usdt'","title":"Currency","type":"string"}},"required":["success","available","currency"],"title":"ProjectBalanceResponse","type":"object"},"ProjectWalletTrc20Response":{"description":"Response for POST /api/v2/project/wallet/trc20.","example":{"success":true,"usdt_trc20":"TPL66VK1uZ7bV5GAgYQ61J5p5H7Eo9u5ob"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"usdt_trc20":{"description":"USDT TRC20 deposit address","title":"Usdt Trc20","type":"string"}},"required":["success","usdt_trc20"],"title":"ProjectWalletTrc20Response","type":"object"},"ProjectTxsResponse":{"$defs":{"ProjectTxItem":{"description":"Project master-account operation.","properties":{"operation_id":{"description":"Source operation identifier","title":"Operation Id","type":"string"},"operation_type":{"description":"Master-account operation direction","enum":["topup","spend"],"title":"Operation Type","type":"string"},"source":{"description":"Source collection used to build the read projection","enum":["txs","cards_topup_orders"],"title":"Source","type":"string"},"tx_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Tx Type"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"amount":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Absolute amount as decimal string","title":"Amount"},"balance_delta":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Signed balance delta","title":"Balance Delta"},"currency":{"default":"usdt","title":"Currency","type":"string"},"balance_before":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Balance Before"},"balance_after":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Balance After"},"card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Card Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Id"},"order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Order Id"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Idempotency Key"},"tx_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Tx At"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"}},"required":["operation_id","operation_type","source"],"title":"ProjectTxItem","type":"object"}},"description":"Response for POST /api/v2/project/txs.","example":{"items":[{"amount":"50.00","balance_after":"50.00","balance_before":"100.00","balance_delta":"-50.00","card_id":"64f1a2b3c4d5e6f7a8b9c0d7","created_at":"2025-01-16T08:30:00","currency":"usdt","idempotency_key":"idem-key","operation_id":"64f1a2b3c4d5e6f7a8b9c0d8","operation_type":"spend","order_id":"64f1a2b3c4d5e6f7a8b9c0d8","source":"cards_topup_orders","status":"new","tx_at":"2025-01-16T08:30:00","tx_type":"card_topup","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"}],"limit":50,"skip":0,"success":true,"total":1},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Master-account operations","items":{"$ref":"#/components/schemas/ProjectTxItem"},"title":"Items","type":"array"},"total":{"description":"Total operations before pagination","title":"Total","type":"integer"},"skip":{"description":"Number of items skipped","title":"Skip","type":"integer"},"limit":{"description":"Page size used","title":"Limit","type":"integer"}},"required":["success","items","total","skip","limit"],"title":"ProjectTxsResponse","type":"object"},"ProjectBalanceRequest":{"description":"POST /api/v2/project/balance - empty body is valid.","example":{},"properties":{},"title":"ProjectBalanceRequest","type":"object"},"ProjectWalletTrc20Request":{"description":"POST /api/v2/project/wallet/trc20 - empty body is valid.","example":{},"properties":{},"title":"ProjectWalletTrc20Request","type":"object"},"ProjectTxsRequest":{"description":"POST /api/v2/project/txs","properties":{"limit":{"default":50,"maximum":500,"minimum":1,"title":"Limit","type":"integer"},"skip":{"default":0,"minimum":0,"title":"Skip","type":"integer"},"fromTimestamp":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Fromtimestamp"},"endTimestamp":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Endtimestamp"}},"title":"ProjectTxsRequest","type":"object"},"CardProductsResponse":{"$defs":{"CardProductItem":{"description":"Single card product in cards/products response.","example":{"card_brand":"visa","card_type":"virtual","currency":"usd","features":["virtual","instant"],"holder_requirement":"ACTUAL","initial_card_balance_amount":"10.00","limits":{"max_topup":"5000.00","min_topup":"10.00"},"name":"Virtual USD Card","pricing":{"issue_price":"5.00"},"product_code":"VIRTUAL_USD","product_id":"64f1a2b3c4d5e6f7a8b9c0d5","status":"active","subprovider_code":"sp_q5r8tz","subprovider_id":"64f1a2b3c4d5e6f7a8b9c0d4"},"properties":{"product_id":{"description":"Internal product ObjectId","title":"Product Id","type":"string"},"product_code":{"description":"Product code used in cards/create","title":"Product Code","type":"string"},"subprovider_id":{"description":"Internal subprovider ObjectId","title":"Subprovider Id","type":"string"},"subprovider_code":{"description":"Subprovider code for cardholders/create","title":"Subprovider Code","type":"string"},"name":{"description":"Human-readable product name","title":"Name","type":"string"},"card_brand":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Card brand (visa, mastercard)","title":"Card Brand"},"card_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Card type (virtual, physical)","title":"Card Type"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Card billing currency","title":"Currency"},"holder_requirement":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Cardholder data requirement","title":"Holder Requirement"},"pricing":{"description":"Pricing config (issue_price, topup_fee, etc.)","title":"Pricing","type":"object"},"limits":{"description":"Topup/spend limits","title":"Limits","type":"object"},"initial_card_balance_amount":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"integer"}],"default":0,"description":"Initial card balance funded by provider-side card creation amount","title":"Initial Card Balance Amount"},"features":{"description":"Product feature flags","items":{"type":"string"},"title":"Features","type":"array"},"status":{"description":"Product status (active, inactive)","title":"Status","type":"string"}},"required":["product_id","product_code","subprovider_id","subprovider_code","name","pricing","limits","features","status"],"title":"CardProductItem","type":"object"}},"description":"Response for POST /api/v2/cards/products.","example":{"items":[{"card_brand":"visa","card_type":"virtual","currency":"usd","features":["virtual","instant"],"holder_requirement":"ACTUAL","initial_card_balance_amount":"10.00","limits":{"max_topup":"5000.00","min_topup":"10.00"},"name":"Virtual USD Card","pricing":{"issue_price":"5.00"},"product_code":"VIRTUAL_USD","product_id":"64f1a2b3c4d5e6f7a8b9c0d5","status":"active","subprovider_code":"sp_q5r8tz","subprovider_id":"64f1a2b3c4d5e6f7a8b9c0d4"}],"success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Available card products","items":{"$ref":"#/components/schemas/CardProductItem"},"title":"Items","type":"array"}},"required":["success","items"],"title":"CardProductsResponse","type":"object"},"CreateCardResponse":{"description":"Response for POST /api/v2/cards/create.","example":{"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","order_id":"64f1a2b3c4d5e6f7a8b9c0d6","status":"processing","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"order_id":{"description":"B2B order ObjectId tracking this issuance","title":"Order Id","type":"string"},"card_id":{"description":"Issued card ObjectId","title":"Card Id","type":"string"},"status":{"description":"Initial card status, always 'processing'","title":"Status","type":"string"}},"required":["success","order_id","card_id","status"],"title":"CreateCardResponse","type":"object"},"GetCardResponse":{"$defs":{"CardBalanceItem":{"description":"Balance block nested inside cards/balance and cards/get responses.","properties":{"available":{"description":"Available balance as decimal string","title":"Available","type":"string"},"pending":{"description":"Pending balance as decimal string","title":"Pending","type":"string"},"cached_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"UTC timestamp of last balance sync","title":"Cached At"}},"required":["available","pending"],"title":"CardBalanceItem","type":"object"}},"description":"Response for POST /api/v2/cards/get.","example":{"activated_at":"2025-01-15T10:41:00","balance":null,"card_currency":"usd","card_id":"64f1a2b3c4d5e6f7a8b9c0d7","card_number_masked":"4111 **** **** 1111","closed_at":null,"created_at":"2025-01-15T10:40:00","external_user_id":"user_42","frozen_at":null,"issued_at":"2025-01-15T10:40:00","label":null,"product_code":"VIRTUAL_USD","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","status":"active","success":true,"updated_at":"2025-01-15T10:41:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"card_id":{"description":"Internal card ObjectId","title":"Card Id","type":"string"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Project Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Id"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External User Id"},"product_code":{"description":"Card product code","title":"Product Code","type":"string"},"card_number_masked":{"description":"Masked PAN","title":"Card Number Masked","type":"string"},"status":{"description":"Card status","title":"Status","type":"string"},"card_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Card Currency"},"balance":{"anyOf":[{"$ref":"#/components/schemas/CardBalanceItem"},{"type":"null"}],"default":null},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Label"},"issued_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Issued At"},"activated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Activated At"},"frozen_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Frozen At"},"closed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Closed At"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["success","card_id","product_code","card_number_masked","status"],"title":"GetCardResponse","type":"object"},"FindCardsResponse":{"$defs":{"CardBalanceItem":{"description":"Balance block nested inside cards/balance and cards/get responses.","properties":{"available":{"description":"Available balance as decimal string","title":"Available","type":"string"},"pending":{"description":"Pending balance as decimal string","title":"Pending","type":"string"},"cached_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"UTC timestamp of last balance sync","title":"Cached At"}},"required":["available","pending"],"title":"CardBalanceItem","type":"object"},"CardItem":{"description":"Single card object in cards/get and cards/find items.","example":{"activated_at":"2025-01-15T10:41:00","balance":null,"card_currency":"usd","card_id":"64f1a2b3c4d5e6f7a8b9c0d7","card_number_masked":"4111 **** **** 1111","closed_at":null,"created_at":"2025-01-15T10:40:00","external_user_id":"user_42","frozen_at":null,"issued_at":"2025-01-15T10:40:00","label":null,"product_code":"VIRTUAL_USD","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","status":"active","updated_at":"2025-01-15T10:41:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"card_id":{"description":"Internal card ObjectId","title":"Card Id","type":"string"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Project Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Id"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External User Id"},"product_code":{"description":"Card product code","title":"Product Code","type":"string"},"card_number_masked":{"description":"Masked PAN (e.g. 4111 **** **** 1111)","title":"Card Number Masked","type":"string"},"status":{"description":"Card status (active, frozen, closed, failed, processing)","title":"Status","type":"string"},"card_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Card Currency"},"balance":{"anyOf":[{"$ref":"#/components/schemas/CardBalanceItem"},{"type":"null"}],"default":null},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Label"},"issued_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Issued At"},"activated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Activated At"},"frozen_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Frozen At"},"closed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Closed At"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["card_id","product_code","card_number_masked","status"],"title":"CardItem","type":"object"}},"description":"Response for POST /api/v2/cards/find.","example":{"items":[],"limit":100,"skip":0,"success":true,"total":0},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Matched cards","items":{"$ref":"#/components/schemas/CardItem"},"title":"Items","type":"array"},"total":{"description":"Total matching cards (before skip/limit)","title":"Total","type":"integer"},"skip":{"description":"Number of items skipped","title":"Skip","type":"integer"},"limit":{"description":"Page size used","title":"Limit","type":"integer"}},"required":["success","items","total","skip","limit"],"title":"FindCardsResponse","type":"object"},"CardDetailsResponse":{"$defs":{"CardCommonDetails":{"description":"Plaintext card credentials.","properties":{"number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Full card PAN","title":"Number"},"holder":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Cardholder name as printed on the card","title":"Holder"},"cvv":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"CVV/CVC code","title":"Cvv"},"expiry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Expiry date (MM/YY)","title":"Expiry"}},"title":"CardCommonDetails","type":"object"}},"description":"Response for POST /api/v2/cards/details.","example":{"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","common_details":{"cvv":"123","expiry":"12/27","holder":"JOHN DOE","number":"4111111111111111"},"status":"active","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"status":{"description":"Card status","title":"Status","type":"string"},"common_details":{"anyOf":[{"$ref":"#/components/schemas/CardCommonDetails"},{"type":"null"}],"default":null,"description":"Plaintext card credentials"}},"required":["success","card_id","status"],"title":"CardDetailsResponse","type":"object"},"CardBalanceResponse":{"$defs":{"CardBalanceItem":{"description":"Balance block nested inside cards/balance and cards/get responses.","properties":{"available":{"description":"Available balance as decimal string","title":"Available","type":"string"},"pending":{"description":"Pending balance as decimal string","title":"Pending","type":"string"},"cached_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"UTC timestamp of last balance sync","title":"Cached At"}},"required":["available","pending"],"title":"CardBalanceItem","type":"object"}},"description":"Response for POST /api/v2/cards/balance.","example":{"balance":{"available":"145.00","cached_at":"2025-01-16T08:00:00","pending":"0.00"},"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"balance":{"$ref":"#/components/schemas/CardBalanceItem","description":"Card balance data"}},"required":["success","card_id","balance"],"title":"CardBalanceResponse","type":"object"},"CardTxsResponse":{"$defs":{"CardTransactionItem":{"description":"Normalized card transaction returned by cards/txs and webhooks.","properties":{"type":{"const":"card_transaction","description":"Event object type","title":"Type","type":"string"},"transaction_id":{"description":"Provider-visible transaction identifier used to correlate /cards/txs and card_transaction webhooks","title":"Transaction Id","type":"string"},"tx_type":{"description":"Provider-derived transaction event type","title":"Tx Type","type":"string"},"card_id":{"description":"Card identifier","title":"Card Id","type":"string"},"tx_at":{"description":"Transaction time","format":"date-time","title":"Tx At","type":"string"},"card_tx_data":{"$ref":"#/components/schemas/CardTxDataItem","description":"Normalized transaction data"}},"required":["type","transaction_id","tx_type","card_id","tx_at","card_tx_data"],"title":"CardTransactionItem","type":"object"},"CardTxDataItem":{"description":"Normalized card transaction fields.","properties":{"auth_type":{"description":"Authorization type, usually 'purchase'","title":"Auth Type","type":"string"},"status":{"description":"Normalized transaction status","enum":["pending","approved","declined","other"],"title":"Status","type":"string"},"type":{"description":"Normalized transaction type","enum":["auth","reversal","fee","refund","other"],"title":"Type","type":"string"},"card_label":{"default":"","description":"Card label or last digits","title":"Card Label","type":"string"},"merchant":{"$ref":"#/components/schemas/CardTxMerchantItem","description":"Merchant information"},"fee_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Fee Amount"},"fee_currency":{"default":"","title":"Fee Currency","type":"string"},"card_currency":{"default":"","title":"Card Currency","type":"string"},"card_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Card Amount"},"merchant_currency":{"default":"","title":"Merchant Currency","type":"string"},"merchant_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Merchant Amount"},"failure_reason":{"default":"","title":"Failure Reason","type":"string"}},"required":["auth_type","status","type","merchant"],"title":"CardTxDataItem","type":"object"},"CardTxMerchantItem":{"description":"Merchant block in normalized card transaction payload.","properties":{"name":{"description":"Merchant name","title":"Name","type":"string"},"mcc":{"default":"","description":"Merchant category code","title":"Mcc","type":"string"}},"required":["name"],"title":"CardTxMerchantItem","type":"object"}},"description":"Response for POST /api/v2/cards/txs.\n\nNormalized response. Items share the same shape as card_transaction webhooks.","example":{"items":[{"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","card_tx_data":{"auth_type":"purchase","card_amount":29.99,"card_currency":"usd","card_label":"1234","failure_reason":"","fee_amount":0.25,"fee_currency":"usd","merchant":{"mcc":"5999","name":"Amazon"},"merchant_amount":29.99,"merchant_currency":"usd","status":"approved","type":"auth"},"transaction_id":"TXN-001","tx_at":"2025-01-16T08:30:00+00:00","tx_type":"transaction_created_auth_approved","type":"card_transaction"}],"success":true,"total":1},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Normalized card transactions","items":{"$ref":"#/components/schemas/CardTransactionItem"},"title":"Items","type":"array"},"total":{"description":"Total transactions returned","title":"Total","type":"integer"}},"required":["success","items","total"],"title":"CardTxsResponse","type":"object"},"TopupCardResponse":{"description":"Response for POST /api/v2/cards/topup.","example":{"amount":"50.00","card_id":"64f1a2b3c4d5e6f7a8b9c0d7","order_id":"64f1a2b3c4d5e6f7a8b9c0d8","status":"new","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"order_id":{"description":"Topup order ObjectId","title":"Order Id","type":"string"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"amount":{"description":"Topup amount as decimal string","title":"Amount","type":"string"},"status":{"description":"Initial order status, always 'new'","title":"Status","type":"string"}},"required":["success","order_id","card_id","amount","status"],"title":"TopupCardResponse","type":"object"},"WithdrawCardResponse":{"description":"Response for POST /api/v2/cards/withdraw.","example":{"amount":"50.00","balance_after":"150.00","balance_before":"100.00","card_id":"64f1a2b3c4d5e6f7a8b9c0d7","currency":"usdt","order_id":"64f1a2b3c4d5e6f7a8b9c0d8","provider_status":"SUCCESS","provider_trade_id":"1234567890","status":"completed","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"order_id":{"description":"Master account topup order ObjectId","title":"Order Id","type":"string"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"amount":{"description":"Withdraw amount as decimal string","title":"Amount","type":"string"},"currency":{"description":"Balance currency, always 'usdt'","title":"Currency","type":"string"},"status":{"description":"Order status, always 'completed' on success","title":"Status","type":"string"},"balance_before":{"description":"Project balance before credit","title":"Balance Before","type":"string"},"balance_after":{"description":"Project balance after credit","title":"Balance After","type":"string"},"provider_trade_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Provider trade ID","title":"Provider Trade Id"},"provider_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Provider trade status","title":"Provider Status"}},"required":["success","order_id","card_id","amount","currency","status","balance_before","balance_after"],"title":"WithdrawCardResponse","type":"object"},"FreezeCardResponse":{"description":"Response for POST /api/v2/cards/freeze.","example":{"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","status":"frozen","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"status":{"description":"New card status, 'frozen'","title":"Status","type":"string"}},"required":["success","card_id","status"],"title":"FreezeCardResponse","type":"object"},"UnfreezeCardResponse":{"description":"Response for POST /api/v2/cards/unfreeze.","example":{"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","status":"active","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"status":{"description":"New card status, 'active'","title":"Status","type":"string"}},"required":["success","card_id","status"],"title":"UnfreezeCardResponse","type":"object"},"ConfirmCard3dsResponse":{"description":"Response for POST /api/v2/cards/3ds/confirm.","example":{"card_id":"64f1a2b3c4d5e6f7a8b9c0d7","confirm":"ACCEPTED","method":"OOB","reason":null,"securement_id":"71859228876451840","status":"SUCCESS","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"card_id":{"description":"Card ObjectId","title":"Card Id","type":"string"},"securement_id":{"description":"Provider 3DS securement ID","title":"Securement Id","type":"string"},"method":{"description":"3DS method returned by provider","title":"Method","type":"string"},"confirm":{"description":"Final confirmation sent to provider","title":"Confirm","type":"string"},"status":{"description":"Provider verification status","title":"Status","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Failure reason if provider returned one","title":"Reason"}},"required":["success","card_id","securement_id","method","confirm","status"],"title":"ConfirmCard3dsResponse","type":"object"},"CardProductsRequest":{"description":"POST /api/v2/cards/products - empty body is valid.","properties":{},"title":"CardProductsRequest","type":"object"},"CreateCardRequest":{"description":"POST /api/v2/cards/create - requires Idempotency-Key header\n\nProvide either `product_code` (preferred) or `product_id` (legacy)\nKYC data is submitted via POST /api/v2/cardholders/create","properties":{"product_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Product code from cards/products response. Required if product_id is not set.","title":"Product Code"},"product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Deprecated. Legacy product ObjectId. Required if product_code is not set.","title":"Product Id"},"external_user_id":{"title":"External User Id","type":"string"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Idempotency key.","title":"Idempotency Key"},"kyc_data":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"description":"Deprecated. Ignored. KYC data is submitted via cardholders/create.","title":"Kyc Data"}},"required":["external_user_id"],"title":"CreateCardRequest","type":"object"},"GetCardRequest":{"description":"POST /api/v2/cards/get","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"}},"required":["card_id","external_user_id"],"title":"GetCardRequest","type":"object"},"FindCardsRequest":{"additionalProperties":false,"description":"POST /api/v2/cards/find","example":{"card_ids":["69e8db508da6f5aae0f29c2d"],"external_user_ids":["YgIKrsHv+DH0RVEWCl0Zv3w"],"limit":100,"product_codes":["sp_q5r8tz_mc_virtual_usd"],"skip":0,"sort":{"created_at":-1},"statuses":["active"],"user_ids":["69a18efef8f7d061e68ce5b0"]},"properties":{"card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single card identifier.","title":"Card Id"},"card_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple card identifiers.","title":"Card Ids"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single external user identifier.","title":"External User Id"},"external_user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple external user identifiers.","title":"External User Ids"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single internal user_id.","title":"User Id"},"user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple internal user_id values.","title":"User Ids"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single card status.","title":"Status"},"statuses":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple card statuses.","title":"Statuses"},"product_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single card product code.","title":"Product Code"},"product_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple card product codes.","title":"Product Codes"},"skip":{"default":0,"minimum":0,"title":"Skip","type":"integer"},"limit":{"default":100,"maximum":5000,"minimum":1,"title":"Limit","type":"integer"},"sort":{"anyOf":[{"additionalProperties":{"enum":[1,-1],"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"title":"Sort"}},"title":"FindCardsRequest","type":"object"},"CardDetailsRequest":{"description":"POST /api/v2/cards/details","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"}},"required":["card_id","external_user_id"],"title":"CardDetailsRequest","type":"object"},"CardBalanceRequest":{"description":"POST /api/v2/cards/balance","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"}},"required":["card_id","external_user_id"],"title":"CardBalanceRequest","type":"object"},"CardTxsRequest":{"description":"POST /api/v2/cards/txs","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slug"},"limit":{"default":50,"maximum":500,"minimum":1,"title":"Limit","type":"integer"},"skip":{"default":0,"minimum":0,"title":"Skip","type":"integer"},"pageSize":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pagesize"},"pageNum":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Pagenum"},"fromTimestamp":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Fromtimestamp"},"endTimestamp":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"title":"Endtimestamp"}},"required":["card_id","external_user_id"],"title":"CardTxsRequest","type":"object"},"TopupCardRequest":{"description":"POST /api/v2/cards/topup - requires Idempotency-Key (header or body).","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"},"amount":{"title":"Amount","type":"string"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Currency"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Idempotency Key"}},"required":["card_id","external_user_id","amount"],"title":"TopupCardRequest","type":"object"},"WithdrawCardRequest":{"description":"POST /api/v2/cards/withdraw - requires Idempotency-Key (header or body).","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"},"amount":{"title":"Amount","type":"string"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Currency"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Idempotency Key"}},"required":["card_id","external_user_id","amount"],"title":"WithdrawCardRequest","type":"object"},"FreezeCardRequest":{"description":"POST /api/v2/cards/freeze","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"},"reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason Code"}},"required":["card_id","external_user_id"],"title":"FreezeCardRequest","type":"object"},"UnfreezeCardRequest":{"description":"POST /api/v2/cards/unfreeze","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"},"reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason Code"}},"required":["card_id","external_user_id"],"title":"UnfreezeCardRequest","type":"object"},"ConfirmCard3dsRequest":{"description":"POST /api/v2/cards/3ds/confirm","properties":{"card_id":{"title":"Card Id","type":"string"},"external_user_id":{"title":"External User Id","type":"string"},"securement_id":{"title":"Securement Id","type":"string"},"confirm":{"enum":["ACCEPTED","DECLINED"],"title":"Confirm","type":"string"}},"required":["card_id","external_user_id","securement_id","confirm"],"title":"ConfirmCard3dsRequest","type":"object"},"CreateCardholderResponse":{"description":"Response for POST /api/v2/cardholders/create.","example":{"cardholder_id":"64f1a2b3c4d5e6f7a8b9c0d3","kyc_status":"approved","registration_status":"active","success":true,"user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"user_id":{"description":"Internal user ObjectId","title":"User Id","type":"string"},"cardholder_id":{"description":"Created cardholder ObjectId","title":"Cardholder Id","type":"string"},"registration_status":{"description":"Cardholder registration status","title":"Registration Status","type":"string"},"kyc_status":{"description":"KYC verification status","title":"Kyc Status","type":"string"}},"required":["success","user_id","cardholder_id","registration_status","kyc_status"],"title":"CreateCardholderResponse","type":"object"},"GetCardholderResponse":{"description":"Response for POST /api/v2/cardholders/get.","example":{"activated_at":"2025-01-15T10:35:00","cardholder_id":"64f1a2b3c4d5e6f7a8b9c0d3","created_at":"2025-01-15T10:30:00","kyc_level":"full","kyc_status":"approved","product_code":"VIRTUAL_USD","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","registered_at":"2025-01-15T10:31:00","registration_status":"active","subprovider_code":"mercury","subprovider_id":"64f1a2b3c4d5e6f7a8b9c0d4","success":true,"updated_at":"2025-01-15T10:35:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"cardholder_id":{"description":"Internal cardholder ObjectId","title":"Cardholder Id","type":"string"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Project Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Id"},"subprovider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Subprovider Id"},"subprovider_code":{"description":"Subprovider code (e.g. 'mercury')","title":"Subprovider Code","type":"string"},"product_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Card product code used for this cardholder","title":"Product Code"},"registration_status":{"description":"Cardholder registration status","title":"Registration Status","type":"string"},"kyc_status":{"description":"KYC verification status","title":"Kyc Status","type":"string"},"kyc_level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Kyc Level"},"kyc_rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Kyc Rejection Reason"},"kyc_rejection_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Kyc Rejection Slug"},"registered_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Registered At"},"activated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Activated At"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["success","cardholder_id","subprovider_code","registration_status","kyc_status"],"title":"GetCardholderResponse","type":"object"},"FindCardholdersResponse":{"$defs":{"CardholderResponse":{"description":"Single cardholder object returned by cardholders/get and cardholders/find items.","example":{"activated_at":"2025-01-15T10:35:00","cardholder_id":"64f1a2b3c4d5e6f7a8b9c0d3","created_at":"2025-01-15T10:30:00","kyc_level":"full","kyc_status":"approved","product_code":"VIRTUAL_USD","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","registered_at":"2025-01-15T10:31:00","registration_status":"active","subprovider_code":"mercury","subprovider_id":"64f1a2b3c4d5e6f7a8b9c0d4","updated_at":"2025-01-15T10:35:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"cardholder_id":{"description":"Internal cardholder ObjectId","title":"Cardholder Id","type":"string"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Project ObjectId","title":"Project Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Internal user ObjectId","title":"User Id"},"subprovider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Subprovider ObjectId","title":"Subprovider Id"},"subprovider_code":{"description":"Subprovider code (e.g. 'mercury')","title":"Subprovider Code","type":"string"},"product_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Card product code used for this cardholder","title":"Product Code"},"registration_status":{"description":"Cardholder registration status","title":"Registration Status","type":"string"},"kyc_status":{"description":"KYC verification status","title":"Kyc Status","type":"string"},"kyc_level":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"KYC level if available","title":"Kyc Level"},"kyc_rejection_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Human-readable provider rejection reason","title":"Kyc Rejection Reason"},"kyc_rejection_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Machine-readable provider rejection code","title":"Kyc Rejection Slug"},"registered_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"UTC registration timestamp","title":"Registered At"},"activated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"UTC activation timestamp","title":"Activated At"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"UTC creation timestamp","title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"UTC last-update timestamp","title":"Updated At"}},"required":["cardholder_id","subprovider_code","registration_status","kyc_status"],"title":"CardholderResponse","type":"object"}},"description":"Response for POST /api/v2/cardholders/find.","example":{"items":[{"activated_at":"2025-01-15T10:35:00","cardholder_id":"64f1a2b3c4d5e6f7a8b9c0d3","created_at":"2025-01-15T10:30:00","kyc_level":"full","kyc_status":"approved","product_code":"VIRTUAL_USD","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","registered_at":"2025-01-15T10:31:00","registration_status":"active","subprovider_code":"mercury","subprovider_id":"64f1a2b3c4d5e6f7a8b9c0d4","updated_at":"2025-01-15T10:35:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"}],"limit":100,"skip":0,"success":true,"total":1},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Matched cardholders","items":{"$ref":"#/components/schemas/CardholderResponse"},"title":"Items","type":"array"},"total":{"description":"Total matching cardholders (before skip/limit)","title":"Total","type":"integer"},"skip":{"description":"Number of items skipped","title":"Skip","type":"integer"},"limit":{"description":"Page size used","title":"Limit","type":"integer"}},"required":["success","items","total","skip","limit"],"title":"FindCardholdersResponse","type":"object"},"CreateCardholderRequest":{"description":"POST /api/v2/cardholders/create\n\n`product_code` is conditionally required based on subprovider settings.\nProvide either `subprovider_code` (preferred) or `subprovider_id` (legacy).","properties":{"external_user_id":{"title":"External User Id","type":"string"},"product_code":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}],"default":null,"description":"Product code from cards/products response. Required only when enabled for the selected subprovider.","title":"Product Code"},"subprovider_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Subprovider code ('sp_q5r8tz'). Get from cards/products response. Required if subprovider_id is not set.","title":"Subprovider Code"},"subprovider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Deprecated. Legacy subprovider ObjectId. Required if subprovider_code is not set.","title":"Subprovider Id"},"kyc_type":{"anyOf":[{"enum":["provided","mocked"],"type":"string"},{"type":"null"}],"default":null,"description":"Cardholder KYC mode. 'provided' expects client KYC payload, 'mocked' generates provider-facing mock data server-side.","title":"Kyc Type"},"kyc_data":{"description":"KYC data schema for OpenAPI documentation.\n\nRuntime validation is handled in the command handler. Extended fields\n(gender, credential_*, address_*) are required only when the resolved\ncard product has holder_requirement = ACTUAL.","properties":{"first_name":{"description":"First name (1-50 chars, letters only)","title":"First Name","type":"string"},"last_name":{"description":"Last name (1-50 chars, letters only)","title":"Last Name","type":"string"},"birth_date":{"description":"Date of birth (YYYY-MM-DD), age 18-120","title":"Birth Date","type":"string"},"email":{"description":"Email address (max 254 chars)","title":"Email","type":"string"},"phone_number_full":{"description":"Phone in international format (+79991234567)","title":"Phone Number Full","type":"string"},"country_iso":{"description":"ISO 3166-1 alpha-2 country code (e.g. 'us', 'ru')","title":"Country Iso","type":"string"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"One of MALE, FEMALE, UNSPECIFIED. Required for holder_requirement=ACTUAL.","title":"Gender"},"credential_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Identity document type: PASSPORT, IDENTITY_CARD or DRIVER_LICENSE. Required for holder_requirement=ACTUAL.","title":"Credential Type"},"credential_country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Document country (ISO 3166-1 alpha-2 or alpha-3). Required for ACTUAL.","title":"Credential Country"},"credential_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Document number (1-64 chars, A-Za-z0-9 _-/<>.&#). Required for ACTUAL.","title":"Credential Code"},"credential_issue":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Document issuance date — millisecond timestamp.","title":"Credential Issue"},"credential_expiry":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Document expiry date — millisecond timestamp.","title":"Credential Expiry"},"credential_obverse":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Front photo of the document, base64-encoded JPEG/PNG, max 2MB. Forwarded to provider; NOT persisted by us.","title":"Credential Obverse"},"credential_reverse":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Back photo of the document, base64-encoded JPEG/PNG, max 2MB. Forwarded to provider; NOT persisted by us.","title":"Credential Reverse"},"credential_handheld":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Selfie holding the document, base64-encoded JPEG/PNG, max 2MB. Forwarded to provider; NOT persisted by us.","title":"Credential Handheld"},"address_region":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"State/province/region. Required for holder_requirement=ACTUAL.","title":"Address Region"},"address_city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"City/town. Required for holder_requirement=ACTUAL.","title":"Address City"},"address_postcode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ZIP/postal code. Optional even for ACTUAL.","title":"Address Postcode"},"address_line":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Street address line. Required for holder_requirement=ACTUAL.","title":"Address Line"}},"required":["first_name","last_name","birth_date","email","phone_number_full","country_iso"],"title":"KYCDataDTO","type":"object"}},"required":["external_user_id"],"title":"CreateCardholderRequest","type":"object"},"GetCardholderRequest":{"description":"POST /api/v2/cardholders/get\n\nSupports direct lookup by `cardholder_id` or user lookup by\n`external_user_id` plus either `subprovider_code` (preferred) or\n`subprovider_id` (legacy).","properties":{"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External User Id"},"subprovider_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Preferred subprovider code ('sp_q5r8tz').","title":"Subprovider Code"},"subprovider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Deprecated legacy subprovider ObjectId.","title":"Subprovider Id"},"product_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional product code to select a product-scoped cardholder.","title":"Product Code"},"cardholder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cardholder Id"}},"title":"GetCardholderRequest","type":"object"},"FindCardholdersRequest":{"additionalProperties":false,"description":"POST /api/v2/cardholders/find","example":{"cardholder_ids":["64f1a2b3c4d5e6f7a8b9c0d3"],"external_user_ids":["user_42","user_43"],"kyc_statuses":["approved"],"limit":100,"product_codes":["VIRTUAL_USD"],"registration_statuses":["active"],"skip":0,"sort":{"created_at":-1},"subprovider_codes":["mercury"],"user_ids":["64f1a2b3c4d5e6f7a8b9c0d1"]},"properties":{"cardholder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single internal cardholder_id.","title":"Cardholder Id"},"cardholder_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple internal cardholder_id values.","title":"Cardholder Ids"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single external user identifier.","title":"External User Id"},"external_user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple external user identifiers.","title":"External User Ids"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single internal user_id.","title":"User Id"},"user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple internal user_id values.","title":"User Ids"},"subprovider_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single subprovider code.","title":"Subprovider Code"},"subprovider_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple subprovider codes.","title":"Subprovider Codes"},"product_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single card product code.","title":"Product Code"},"product_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple card product codes.","title":"Product Codes"},"registration_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single cardholder registration status.","title":"Registration Status"},"registration_statuses":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple cardholder registration statuses.","title":"Registration Statuses"},"kyc_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single cardholder KYC status.","title":"Kyc Status"},"kyc_statuses":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple cardholder KYC statuses.","title":"Kyc Statuses"},"skip":{"default":0,"minimum":0,"title":"Skip","type":"integer"},"limit":{"default":100,"maximum":5000,"minimum":1,"title":"Limit","type":"integer"},"sort":{"anyOf":[{"additionalProperties":{"enum":[1,-1],"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"title":"Sort"}},"title":"FindCardholdersRequest","type":"object"},"CheckOrderResponse":{"description":"Response for POST /api/v2/orders/check.","example":{"balance_after":"145.00","balance_before":"150.00","card_id":"64f1a2b3c4d5e6f7a8b9c0d7","completed_at":"2025-01-15T10:41:00","created_at":"2025-01-15T10:40:00","data":{},"failed_at":null,"last_error":null,"last_error_slug":null,"order_id":"64f1a2b3c4d5e6f7a8b9c0d6","order_type":"card_issue","status":"completed","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"order_id":{"description":"Order ObjectId","title":"Order Id","type":"string"},"order_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Order type (card_issue, card_topup, card_status_change, master_account_topup)","title":"Order Type"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Order status (new, activating, processing, completed, failed)","title":"Status"},"card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Related card ObjectId if applicable","title":"Card Id"},"balance_before":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Project balance before this order","title":"Balance Before"},"balance_after":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Project balance after this order","title":"Balance After"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Last error message if status=failed","title":"Last Error"},"last_error_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Machine-readable error code","title":"Last Error Slug"},"data":{"description":"Order-specific data payload","title":"Data","type":"object"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"completed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Completed At"},"failed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Failed At"}},"required":["success","order_id","data"],"title":"CheckOrderResponse","type":"object"},"CheckOrderRequest":{"description":"POST /api/v2/orders/check","properties":{"order_id":{"title":"Order Id","type":"string"}},"required":["order_id"],"title":"CheckOrderRequest","type":"object"},"SystemTimeResponse":{"description":"Response for POST /api/v2/system/time.","example":{"success":true,"timestamp":1742212800000000},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"timestamp":{"description":"Current server time in microseconds","title":"Timestamp","type":"integer"}},"required":["success","timestamp"],"title":"SystemTimeResponse","type":"object"},"SystemHealthResponse":{"description":"Response for POST /api/v2/system/health.","example":{"status":"ok","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"status":{"description":"Service status, always 'ok'","title":"Status","type":"string"}},"required":["success","status"],"title":"SystemHealthResponse","type":"object"},"SystemTimeRequest":{"description":"POST /api/v2/system/time - empty body, no request_timestamp required.","example":{},"properties":{},"title":"SystemTimeRequest","type":"object"},"SystemHealthRequest":{"description":"POST /api/v2/system/health - empty body.","example":{},"properties":{},"title":"SystemHealthRequest","type":"object"},"CreateUserResponse":{"$defs":{"DepositAddressesResponse":{"description":"Deposit wallet addresses for a user.","properties":{"usdt_trc20":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"USDT TRC20 deposit address","title":"Usdt Trc20"},"usdt_ton":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"USDT TON deposit address","title":"Usdt Ton"}},"title":"DepositAddressesResponse","type":"object"}},"description":"Response for POST /api/v2/users/create.","example":{"created_at":"2025-01-15T10:30:00","custom_fields":null,"deposit_addresses":null,"external_user_id":"user_42","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","success":true,"updated_at":"2025-01-15T10:30:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"user_id":{"description":"Internal user ObjectId","title":"User Id","type":"string"},"project_id":{"description":"Project ObjectId this user belongs to","title":"Project Id","type":"string"},"external_user_id":{"description":"Caller-assigned user identifier","title":"External User Id","type":"string"},"custom_fields":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"title":"Custom Fields"},"deposit_addresses":{"anyOf":[{"$ref":"#/components/schemas/DepositAddressesResponse"},{"type":"null"}],"default":null},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["success","user_id","project_id","external_user_id"],"title":"CreateUserResponse","type":"object"},"GetUserResponse":{"$defs":{"DepositAddressesResponse":{"description":"Deposit wallet addresses for a user.","properties":{"usdt_trc20":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"USDT TRC20 deposit address","title":"Usdt Trc20"},"usdt_ton":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"USDT TON deposit address","title":"Usdt Ton"}},"title":"DepositAddressesResponse","type":"object"}},"description":"Response for POST /api/v2/users/get.","example":{"created_at":"2025-01-15T10:30:00","custom_fields":null,"deposit_addresses":{"usdt_ton":null,"usdt_trc20":"TPL66VK1uZ7bV5GAgYQ61J5p5H7Eo9u5ob"},"external_user_id":"user_42","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","success":true,"updated_at":"2025-01-16T08:00:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"user_id":{"description":"Internal user ObjectId","title":"User Id","type":"string"},"project_id":{"description":"Project ObjectId this user belongs to","title":"Project Id","type":"string"},"external_user_id":{"description":"Caller-assigned user identifier","title":"External User Id","type":"string"},"custom_fields":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"title":"Custom Fields"},"deposit_addresses":{"anyOf":[{"$ref":"#/components/schemas/DepositAddressesResponse"},{"type":"null"}],"default":null},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["success","user_id","project_id","external_user_id"],"title":"GetUserResponse","type":"object"},"FindUsersResponse":{"$defs":{"DepositAddressesResponse":{"description":"Deposit wallet addresses for a user.","properties":{"usdt_trc20":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"USDT TRC20 deposit address","title":"Usdt Trc20"},"usdt_ton":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"USDT TON deposit address","title":"Usdt Ton"}},"title":"DepositAddressesResponse","type":"object"},"UserResponse":{"description":"Single user object returned by users/create and users/get.","example":{"created_at":"2025-01-15T10:30:00","custom_fields":null,"deposit_addresses":null,"external_user_id":"user_42","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","updated_at":"2025-01-15T10:30:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"},"properties":{"user_id":{"description":"Internal user ObjectId","title":"User Id","type":"string"},"project_id":{"description":"Project ObjectId this user belongs to","title":"Project Id","type":"string"},"external_user_id":{"description":"Caller-assigned user identifier","title":"External User Id","type":"string"},"custom_fields":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"description":"Arbitrary caller-defined fields","title":"Custom Fields"},"deposit_addresses":{"anyOf":[{"$ref":"#/components/schemas/DepositAddressesResponse"},{"type":"null"}],"default":null,"description":"Assigned deposit wallets"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"UTC creation timestamp","title":"Created At"},"updated_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"UTC last-update timestamp","title":"Updated At"}},"required":["user_id","project_id","external_user_id"],"title":"UserResponse","type":"object"}},"description":"Response for POST /api/v2/users/find.","example":{"items":[{"created_at":"2025-01-15T10:30:00","custom_fields":null,"deposit_addresses":null,"external_user_id":"user_42","project_id":"64f1a2b3c4d5e6f7a8b9c0d2","updated_at":"2025-01-16T08:00:00","user_id":"64f1a2b3c4d5e6f7a8b9c0d1"}],"limit":100,"skip":0,"success":true,"total":1},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Matched users","items":{"$ref":"#/components/schemas/UserResponse"},"title":"Items","type":"array"},"total":{"description":"Total matching users (before skip/limit)","title":"Total","type":"integer"},"skip":{"description":"Number of items skipped","title":"Skip","type":"integer"},"limit":{"description":"Page size used","title":"Limit","type":"integer"}},"required":["success","items","total","skip","limit"],"title":"FindUsersResponse","type":"object"},"CreateUserRequest":{"$defs":{"UserDataDTO":{"description":"Optional user metadata block - corpapi sends this in users/create.","properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Phone"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"}},"title":"UserDataDTO","type":"object"},"UserGeoDTO":{"description":"Optional geo block from corpapi users/create.","properties":{"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Country"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"City"}},"title":"UserGeoDTO","type":"object"}},"description":"POST /api/v2/users/create\n\nAccepts both `user_id` (corpapi legacy) and `external_user_id`.","properties":{"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External User Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Id"},"user_data":{"anyOf":[{"$ref":"#/components/schemas/UserDataDTO"},{"type":"null"}],"default":null},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ip Address"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Agent"},"geo":{"anyOf":[{"$ref":"#/components/schemas/UserGeoDTO"},{"type":"null"}],"default":null},"custom_fields":{"anyOf":[{"type":"object"},{"type":"null"}],"default":null,"title":"Custom Fields"}},"title":"CreateUserRequest","type":"object"},"GetUserRequest":{"description":"POST /api/v2/users/get\n\nAccepts both `user_id` (corpapi legacy) and `external_user_id`.","properties":{"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"External User Id"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"User Id"}},"title":"GetUserRequest","type":"object"},"FindUsersRequest":{"additionalProperties":false,"description":"POST /api/v2/users/find","example":{"created_from":"2025-01-01T00:00:00","created_to":"2025-12-31T23:59:59","external_user_ids":["user_42","user_43"],"limit":100,"skip":0,"sort":{"created_at":-1},"user_ids":["64f1a2b3c4d5e6f7a8b9c0d1"]},"properties":{"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single external user identifier.","title":"External User Id"},"external_user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple external user identifiers.","title":"External User Ids"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Single internal user_id.","title":"User Id"},"user_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Multiple internal user_id values.","title":"User Ids"},"created_from":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"Lower bound (inclusive) for created_at.","title":"Created From"},"created_to":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"Upper bound (inclusive) for created_at.","title":"Created To"},"skip":{"default":0,"minimum":0,"title":"Skip","type":"integer"},"limit":{"default":100,"maximum":5000,"minimum":1,"title":"Limit","type":"integer"},"sort":{"anyOf":[{"additionalProperties":{"enum":[1,-1],"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"title":"Sort"}},"title":"FindUsersRequest","type":"object"},"SubscribeWebhookResponse":{"description":"Response for POST /api/v2/wh/subscribe.","example":{"is_active":true,"subscription_id":"64f1a2b3c4d5e6f7a8b9c0d9","success":true,"title":"My webhook"},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"subscription_id":{"description":"Created subscription ObjectId","title":"Subscription Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Subscription label","title":"Title"},"is_active":{"description":"Subscription active status, always true on create","title":"Is Active","type":"boolean"}},"required":["success","subscription_id","is_active"],"title":"SubscribeWebhookResponse","type":"object"},"UnsubscribeWebhookResponse":{"description":"Response for POST /api/v2/wh/unsubscribe.","example":{"is_active":false,"subscription_id":"64f1a2b3c4d5e6f7a8b9c0d9","success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"subscription_id":{"description":"Deactivated subscription ObjectId","title":"Subscription Id","type":"string"},"is_active":{"description":"Always false after unsubscribe","title":"Is Active","type":"boolean"}},"required":["success","subscription_id","is_active"],"title":"UnsubscribeWebhookResponse","type":"object"},"ListSubscriptionsResponse":{"$defs":{"WebhookSubscriptionItem":{"description":"Single subscription in wh/subscriptions response.","properties":{"id":{"description":"Subscription ObjectId","title":"Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Subscription label","title":"Title"},"webhook_url":{"description":"Target HTTPS URL","title":"Webhook Url","type":"string"},"is_active":{"description":"Whether subscription is active","title":"Is Active","type":"boolean"},"created_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"title":"Created At"}},"required":["id","webhook_url","is_active"],"title":"WebhookSubscriptionItem","type":"object"}},"description":"Response for POST /api/v2/wh/subscriptions.","example":{"items":[{"created_at":"2025-01-15T10:00:00","id":"64f1a2b3c4d5e6f7a8b9c0d9","is_active":true,"title":"My webhook","webhook_url":"https://example.com/webhook"}],"success":true},"properties":{"success":{"description":"Always true on success","title":"Success","type":"boolean"},"items":{"description":"Project webhook subscriptions","items":{"$ref":"#/components/schemas/WebhookSubscriptionItem"},"title":"Items","type":"array"}},"required":["success","items"],"title":"ListSubscriptionsResponse","type":"object"},"SubscribeWebhookRequest":{"description":"POST /api/v2/wh/subscribe","properties":{"webhook_url":{"title":"Webhook Url","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"}},"required":["webhook_url"],"title":"SubscribeWebhookRequest","type":"object"},"UnsubscribeWebhookRequest":{"description":"POST /api/v2/wh/unsubscribe","properties":{"subscription_id":{"title":"Subscription Id","type":"string"}},"required":["subscription_id"],"title":"UnsubscribeWebhookRequest","type":"object"},"ListSubscriptionsRequest":{"description":"POST /api/v2/wh/subscriptions - empty body is valid.","properties":{},"title":"ListSubscriptionsRequest","type":"object"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"API-KEY","in":"header"}}}}