> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinvoyage.io/llms.txt
> Use this file to discover all available pages before exploring further.
# CoinVoyage SDK and API changelog — release notes
> Integration-facing CoinVoyage SDK and API changes, ordered newest-first. Includes breaking changes, new features, and user-visible fixes.
Integration-facing changes to the CoinVoyage SDK, API, and platform behavior are documented here. Internal implementation details are omitted unless they change what you configure, call, receive, or need to handle in production. Releases follow [Semantic Versioning](https://semver.org/): major versions for breaking changes, minor for new backward-compatible functionality, and patch for bug fixes.
`2.0.0` marks the v2 migration release. If you are upgrading from v1, see the [Migration Guide](/v2/resources/migration-v1-to-v2) for step-by-step upgrade instructions.
***
## 2.5.0 - 2026-05-27
**Added**
* **KYC helpers**: `ApiClient.createKYCLink()` creates an identity-verification link for an organization, and `ApiClient.getKYCStatus()` retrieves the current KYC and terms-of-service status.
**Changed**
* **Signed organization methods**: `ApiClient.listPayOrders()`, `ApiClient.listWithdrawals()`, and `ApiClient.createWithdrawal()` now require `apiSecret` as an argument. Server integrations that call these methods must pass the API secret from server-side code.
***
## 2.4.6 - 2026-05-27
**Added**
* **PayKit Headless (Preview)**: Added `@coin-voyage/paykit-headless` for server and agent runtimes that need to satisfy CoinVoyage x402 `PAYMENT-REQUIRED` challenges. Sui x402 signing is supported through this package.
* **Order status WebSocket hook**: Added `useOrderStatusWS()` for React integrations that need live backend PayOrder events outside the default PayButton UI.
* **Backend API access**: Added `useBackendApi()` for advanced PayKit integrations that need direct access to the configured API client.
* **ApiClient helpers**: Added `currencySearch()`, `portfolio()`, `listPayOrders()`, `listBankAccounts()`, `getBankAccount()`, `addBankAccount()`, `listWithdrawals()`, and `createWithdrawal()`.
* **Organization-wide WebSocket subscriptions**: `ApiClient.subscribeOrderStatus()` can now subscribe to all organization PayOrder events when called with a server-generated authorization signature for `GET /ws`.
**Changed**
* **Quote filters**: `PayOrderQuoteParams` now accepts `chain_ids` instead of a single `chain_id`.
* **Swap requests**: Swap requests now support `payment_rail` and nested `crypto` input options, including `source_currency`, `sender_address`, and `slippage_bps`.
* **Route quote field**: Route quote responses use `quote_id`.
* **Payment details**: Payment details now use the shared `PaymentDataBase` shape for rail-specific payment instruction data.
**Fixed**
* **PayButton order creation errors**: Backend order-creation failures are now surfaced to consumers.
* **PayButton lifecycle callbacks**: Payment lifecycle callbacks continue working across multiple orders for the same button.
* **`resetOnSuccess` behavior**: Successful payments reset payment state when configured.
* **EVM transaction errors**: User-facing EVM transaction errors are clearer.
* **Desktop WalletConnect**: Desktop WalletConnect routes through the QR flow correctly.
***
## 2.4.1 — 2026-04-08
**Added**
* **`PARTIAL_PAYMENT` status**: A new terminal state for PayOrders that receive an insufficient amount. Use this status to detect and handle partial-payment outcomes in your order fulfillment logic.
* **`PayOrderPartialPaymentEvent`**: A new event type so you can explicitly handle partial-payment outcomes in your event flows.
***
## 2.4.0 — 2026-04-04
**Added**
* **Stripe on-ramp integration**: Full Stripe fiat-to-crypto on-ramp support, including geo-blocking for restricted regions.
* **`PaymentSteps` model**: Tracks granular payment progress across stages such as on-ramp, swap, and delivery.
* **Payment methods endpoint**: `GET /pay-orders/{payorder_id}/payment-methods` returns available payment methods for a given PayOrder.
* **Organization settings in PayOrder responses**: `Organization.settings` is now a JSON field and is returned in `GET /pay-orders` and `GET /pay-orders/{payorder_id}` responses.
* **`hosted_url` field**: Added to `GET /pay-orders` and `GET /pay-orders/{payorder_id}` responses so you can link customers directly to the hosted pay page.
**Changed**
* **Webhook payload coverage**: `payorder_error` and `payorder_refunded` events now include the full `payment_data` object.
* **PayKit payment handling**: The widget now consumes `payment_data.steps`, supports organization settings, and exposes location-aware payment method options.
* **SDK request and response models**: Added `metadata` support to `ClaimFeesRequest` and `SwapQuoteRequest`, updated order event types and `ClaimFeeResponse`, and expanded `ApiClient` to accept `Opts`.
* **EVM prefunding flow**: Improved prefunding across CCTP, Direct, Relay, and Uniswap providers with better gas estimation, prefund calculation, and error handling.
**Fixed**
* **Webhook subscription filtering**: Webhook deliveries now correctly respect each subscriber's registered event types.
* **Payment state persistence**: Improved handling of `payment_data` so the correct exchange state is always persisted throughout the payment flow.
* **Refund PayOrder client flow**: Fixed `createRefundPayOrder` handling in `ApiClient`.
* **WalletConnect desktop routing**: Desktop WalletConnect flows now route through the QR flow correctly.
**Removed**
* **Deprecated `RequestData` / `request` field**: Removed from `PayOrderResponse`.
* **Legacy transaction hash aliases**: Removed `SourceTransactionHash` and `DestinationTransactionHash` alias fields.
***
## 2.0.0 — 2026-01-28
This release contains breaking changes. See the [Migration Guide](/v2/resources/migration-v1-to-v2) before upgrading.
**Added**
* **List Pay Orders endpoint**: `GET /pay-orders` retrieves all pay orders for your organization with pagination and status filtering.
* **Quote breakdown transparency**: Quotes now expose detailed fee breakdowns including `base`, `fees`, `gas`, and `total`.
* **Multi-provider execution tracking**: `payment.execution` tracks execution status across multiple providers.
* **`ApiClient` constructor options**: Added `sessionId` and `version` options.
* **Dedicated PayOrder helpers**: `createDepositPayOrder()` and `createSalePayOrder()` provide clearer intent for each payment flow.
**Changed**
* **API base URL**: Updated to `https://api.coinvoyage.io/v2/`.
* **Response structure**: Flat fields moved into nested `payment` and `fulfillment` objects.
* **BigInt handling**: `raw_amount` fields now return strings instead of numbers to prevent precision loss.
* **Authorization signature**: `generateAuthorizationSignature()` now uses HMAC-SHA256 and requires `method` and `path`.
* **Sale and refund authorization**: `createSalePayOrder()` and `createRefundPayOrder()` now accept `apiSecret` directly instead of a pre-generated signature.
* **Webhook event naming**: Webhook subscriptions use uppercase `ORDER_*` identifiers; delivered payloads use lowercase `payorder_*` values in the `type` field.
**Removed**
* **Process endpoint**: `/pay-orders/{payorder_id}/process` has been removed. Payment processing now happens automatically when funds are detected.
**Deprecated**
* **Top-level response fields**: `source_currency`, `source_amount`, `destination_currency`, `destination_amount`, `deposit_address`, `receiving_address`, `refund_address`, and `expires_at` are deprecated at the top level. Use the corresponding nested fields in `payment` and `fulfillment` instead.
***
## 0.1.25 — 2025-11-04
**Added**
* **Phantom wallet (EVM)**: Users can now connect an EVM wallet through the Phantom browser extension.
***
## 0.1.24 — 2025-10-29
**Added**
* **German localization**: Display the PayKit modal in German by specifying the `de-DE` language in your widget configuration.
**Changed**
* **`ApiClient` responses**: All `ApiClient` methods now return `APIResponse` for a consistent response shape.
***
## 0.1.23 — 2025-10-21
**Changed**
* **`WalletProvider` props**: Updated property names and nesting structure. Review your `WalletProvider` configuration if you pass custom props.
***
## 0.1.22 — 2025-10-17
**Added**
* **Stable Testnet support**: Added support for the Stable Testnet network so you can test integrations without using mainnet funds.