> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Update conversion > Updates an existing conversion. Replaces the destination, name, and status in a single full-state PUT (matching the autoramp rule update contract). The source side is immutable — re-create the conversion if you need to change input asset, rail, or wallet. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json put /v1/accounts/{account_id}/conversions/{conversion_id} openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversions (rule-driven and one-shot fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Funds (deposits, withdrawals, addresses, transactions), Portfolio, Earn, Reports, Webhooks, and Ramp (hosted fiat-to-crypto on-ramp checkout). All requests must be authenticated. All monetary values are decimal strings; all timestamps are ISO 8601 UTC. List endpoints are cursor-paginated. Errors follow a uniform shape (see `*ErrorResponse` schemas). version: v1 contact: name: Payward Services API Support url: https://docs.payward.com email: api-support@payward.com servers: - url: https://api.services.payward.com description: Production security: - ApiKey: [] ApiNonce: [] ApiSign: [] tags: - name: Users description: >- Users and headless-user onboarding flows that the partner manages. - **Create User** provisions a user with full identity verification fields collected up front. - **Create Headless User** provisions a lightweight user when your licensing agreement allows you to manage KYC data outside Payward. - **Get User** retrieves the user's profile, verification status, and required actions. - **Update User** updates user profile fields and may re-trigger verification. Use the returned user `id` for calls that require the user's identifier. - name: Assets description: >- Catalog of assets available on the platform with retail-display metadata (logos, market data, descriptions). - name: Conversions description: >- Rule-driven and one-shot fiat ↔ crypto value movement, including conversion rules, deposits, and whitelisted wallets. - name: Earn description: >- Manage auto-earn preferences and retrieve allocation and reward information. - name: Funds description: >- Deposits, withdrawals, addresses, methods, and the consolidated funding-transactions ledger. - name: Portfolio description: End-user portfolio summary, history, and transaction views. - name: Price Trigger Swaps description: Limit-style orders that execute when a configured price trigger is met. - name: On-chain Swaps description: >- Wallet-funded onchain quote trading for xStock and USDC pairs. On-chain quotes settle on-chain through the Payward on-chain proxy contract. - name: Ramp description: >- Hosted fiat-to-crypto on-ramp checkout: country / fiat / payment-method / cryptocurrency-asset discovery, transaction limits and prospective quotes, and the hosted checkout URL. - name: Reports description: Settlement and reconciliation reports for the partner. - name: Swaps description: >- Direct partner-to-Payward swap quotes and executions (institutional FX-style trading). - name: Verifications description: Identity verification (KYC) submission and status for end users. - name: Webhooks description: Manage webhook subscriptions for asynchronous event delivery. paths: /v1/accounts/{account_id}/conversions/{conversion_id}: put: tags: - Conversions summary: Update conversion description: |- Updates an existing conversion. Replaces the destination, name, and status in a single full-state PUT (matching the autoramp rule update contract). The source side is immutable — re-create the conversion if you need to change input asset, rail, or wallet. operationId: updateConversion parameters: - in: path name: account_id required: true schema: description: >- Internet International Bank Account Number identifying the PWS account the conversion belongs to. type: string minLength: 14 maxLength: 42 style: simple example: AA23N84GGQN4WE6I - in: path name: conversion_id required: true schema: description: Conversion identifier. type: string format: uuid style: simple example: 550e8400-e29b-41d4-a716-446655440000 requestBody: content: application/json: schema: description: >- Request to update an existing conversion. Full-state replacement (matching the upstream contract): the supplied `to`, `name`, and `status` replace the conversion's current values. The source side (`from`) is immutable — re-create the conversion to change input asset, rail, or source type. type: object properties: name: description: >- New partner-facing label for the conversion. This is a full replacement: omit to clear the existing label, send the current label to keep it. type: string minLength: 1 maxLength: 128 to: description: >- New destination side. Required (no partial updates supported). type: object properties: symbol: description: Asset ticker symbol (e.g. "EUR", "USDC", "BTC"). type: string minLength: 1 maxLength: 16 type: description: >- Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither. type: string enum: - wallet - bank title: EndpointType wallet: description: >- Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests. type: object properties: via: description: >- Network identifier ("polygon", "ethereum", "bitcoin", ...). type: string minLength: 1 maxLength: 32 address: description: >- On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response. type: string minLength: 1 maxLength: 256 memo: description: >- Memo for chains that require one (e.g. XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound. type: string minLength: 1 maxLength: 64 tag: description: >- Destination tag for chains that require one (e.g. XRP). Passed through to the destination on off-ramp; populated on source responses. type: string minLength: 1 maxLength: 64 required: - via title: Wallet bank_account: description: >- Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests. type: object properties: via: description: >- Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected. type: string minLength: 1 maxLength: 32 bank: description: >- Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp. type: string maxLength: 256 iban: description: International Bank Account Number (SEPA, SWIFT). type: string minLength: 14 maxLength: 42 bic: description: Bank Identifier Code (SEPA, SWIFT). type: string minLength: 8 maxLength: 11 sort_code: description: UK sort code (FPS). type: string minLength: 6 maxLength: 8 account_number: description: >- Account number. Required for FPS destinations; may also be populated on source bank accounts. type: string minLength: 1 maxLength: 34 routing_number: description: >- Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations. type: string minLength: 1 maxLength: 32 swift: description: >- SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations. type: string minLength: 8 maxLength: 11 required: - via title: BankAccount required: - symbol - type title: ConversionEndpoint status: description: >- New lifecycle status. Must be `active` or `paused`; soft-delete via the delete endpoint when it lands. type: string enum: - active - paused required: - to - status examples: id-update-conversion-ok: summary: UpdateConversion returns the updated rule value: name: Renamed EUR autoramp to: symbol: USDC type: wallet wallet: via: polygon address: '0xabcdef1234567890abcdef1234567890abcdef12' status: paused id-update-conversion-rejects-symbol-change: summary: UpdateConversion rejects an attempt to change to.symbol value: to: symbol: USDT type: wallet wallet: via: polygon address: '0xabcdef1234567890abcdef1234567890abcdef12' status: active required: true responses: '200': description: Successful response content: application/json: schema: type: object properties: data: description: The updated conversion. type: object properties: id: description: Unique identifier for this conversion. type: string format: uuid name: description: Optional partner-facing label for the conversion. type: string from: description: >- Source side. On reads, `address`/`bank_account` are populated by the service from the autoramp-provisioned inbound (where partner deposits funds). On writes, those fields are ignored — partners only specify symbol, type, and via on the source side. type: object properties: symbol: description: Asset ticker symbol (e.g. "EUR", "USDC", "BTC"). type: string minLength: 1 maxLength: 16 type: description: >- Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither. type: string enum: - wallet - bank title: EndpointType wallet: description: >- Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests. type: object properties: via: description: >- Network identifier ("polygon", "ethereum", "bitcoin", ...). type: string minLength: 1 maxLength: 32 address: description: >- On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response. type: string minLength: 1 maxLength: 256 memo: description: >- Memo for chains that require one (e.g. XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound. type: string minLength: 1 maxLength: 64 tag: description: >- Destination tag for chains that require one (e.g. XRP). Passed through to the destination on off-ramp; populated on source responses. type: string minLength: 1 maxLength: 64 required: - via title: Wallet bank_account: description: >- Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests. type: object properties: via: description: >- Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected. type: string minLength: 1 maxLength: 32 bank: description: >- Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp. type: string maxLength: 256 iban: description: >- International Bank Account Number (SEPA, SWIFT). type: string minLength: 14 maxLength: 42 bic: description: Bank Identifier Code (SEPA, SWIFT). type: string minLength: 8 maxLength: 11 sort_code: description: UK sort code (FPS). type: string minLength: 6 maxLength: 8 account_number: description: >- Account number. Required for FPS destinations; may also be populated on source bank accounts. type: string minLength: 1 maxLength: 34 routing_number: description: >- Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations. type: string minLength: 1 maxLength: 32 swift: description: >- SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations. type: string minLength: 8 maxLength: 11 payee_name: description: >- Payee / account-holder name on the provisioned inbound (named account). Populated once the virtual account is provisioned — always on Get and List; the create response carries it only when the account was already provisioned at creation time. Rejected on a destination. type: string minLength: 1 maxLength: 140 bank_address: description: >- Bank / EMI address on the provisioned inbound. Populated once the virtual account is provisioned — always on Get and List; the create response carries it only when the account was already provisioned at creation time. Rejected on a destination. type: string minLength: 1 maxLength: 256 payee_address: description: >- Payee's registered postal address on the provisioned inbound (on-ramp source only) — distinct from `bank_address`, which is the bank / EMI address. Populated once the virtual account is provisioned — always on Get and List; the create response carries it only when the account was already provisioned at creation time. Rejected on a destination. type: string minLength: 1 maxLength: 256 required: - via title: BankAccount required: - type title: ConversionEndpoint to: description: >- Destination side. `address`/`bank_account` are partner-supplied. type: object properties: symbol: description: Asset ticker symbol (e.g. "EUR", "USDC", "BTC"). type: string minLength: 1 maxLength: 16 type: description: >- Kind of endpoint. `wallet` requires `wallet`; `bank` requires `bank_account`; `balance` requires neither. type: string enum: - wallet - bank title: EndpointType wallet: description: >- Crypto wallet routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a crypto inbound. Ignored on the `from` side of requests. type: object properties: via: description: >- Network identifier ("polygon", "ethereum", "bitcoin", ...). type: string minLength: 1 maxLength: 32 address: description: >- On-chain address. Required when `Wallet` is set on a destination endpoint; populated by the service when set on a source endpoint response. type: string minLength: 1 maxLength: 256 memo: description: >- Memo for chains that require one (e.g. XLM, EOS, Cosmos). Passed through to the destination on off-ramp; populated on source responses when upstream provisions a memo'd inbound. type: string minLength: 1 maxLength: 64 tag: description: >- Destination tag for chains that require one (e.g. XRP). Passed through to the destination on off-ramp; populated on source responses. type: string minLength: 1 maxLength: 64 required: - via title: Wallet bank_account: description: >- Bank account routing. On `to`: partner-supplied destination. On `from`: service-populated when autoramp provisions a fiat inbound. Ignored on the `from` side of requests. type: object properties: via: description: >- Bank rail identifier. Conversion destinations currently support `sepa` and `fps`; unsupported rails are rejected. type: string minLength: 1 maxLength: 32 bank: description: >- Bank / financial institution name for the beneficiary account. Optional; passed through to the destination on off-ramp. type: string maxLength: 256 iban: description: >- International Bank Account Number (SEPA, SWIFT). type: string minLength: 14 maxLength: 42 bic: description: Bank Identifier Code (SEPA, SWIFT). type: string minLength: 8 maxLength: 11 sort_code: description: UK sort code (FPS). type: string minLength: 6 maxLength: 8 account_number: description: >- Account number. Required for FPS destinations; may also be populated on source bank accounts. type: string minLength: 1 maxLength: 34 routing_number: description: >- Routing number populated on source bank accounts when supplied by the provider; not accepted on conversion destinations. type: string minLength: 1 maxLength: 32 swift: description: >- SWIFT code populated on source bank accounts when supplied by the provider; not accepted on conversion destinations. type: string minLength: 8 maxLength: 11 required: - via title: BankAccount required: - type title: ConversionEndpoint status: description: Lifecycle status (active | paused). type: string enum: - active - paused - provisioning created_at: $ref: '#/components/schemas/google.protobuf.Timestamp' updated_at: $ref: '#/components/schemas/google.protobuf.Timestamp' required: - id - from - to - status - created_at - updated_at title: Conversion required: - data examples: id-update-conversion-ok: summary: UpdateConversion returns the updated rule value: data: id: 550e8400-e29b-41d4-a716-446655440000 name: Renamed EUR autoramp from: symbol: EUR type: bank bank_account: via: sepa payee_name: Delta Commerce B.V. bank_address: Borschestraat 12, Amsterdam payee_address: >- 71 Sir John Rogerson's Quay, Dublin, D02 R296, Ireland to: symbol: USDC type: wallet wallet: via: polygon address: '0xabcdef1234567890abcdef1234567890abcdef12' status: paused created_at: '2026-05-25T10:30:00Z' updated_at: '2026-05-25T11:00:00Z' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/BadRequestError' - $ref: >- #/components/schemas/ConversionInvalidWithdrawalAddressErrorResponse '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ConversionsNotFoundErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/RuleAlreadyDeletedErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalError' '501': description: Error response content: application/json: schema: $ref: '#/components/schemas/UnimplementedError' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/UnavailableError' '504': description: Deadline exceeded content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' security: - ApiKey: [] ApiNonce: [] ApiSign: [] components: schemas: google.protobuf.Timestamp: description: RFC 3339 timestamp. type: string format: date-time BadRequestError: description: Request validation failed or the request could not be processed. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 400 code: type: string enum: - bad_request ConversionInvalidWithdrawalAddressErrorResponse: description: >- The off-ramp destination bank account is missing or has an invalid field for the chosen withdrawal rail (e.g. `bic` is required for SEPA but absent). `causes[]` names each offending field and is non-empty. type: object properties: error: description: Error details. type: object properties: type: type: string enum: - conversions_error status: type: integer format: uint16 enum: - 400 instance: type: string code: type: string enum: - conversion_invalid_withdrawal_address doc_url: type: - string - 'null' format: uri causes: type: array minItems: 1 items: $ref: '#/components/schemas/ConversionInvalidWithdrawalAddressCause' description: One entry per missing or invalid beneficiary bank field. required: - type - status - instance - code - causes required: - error UnauthenticatedError: description: Authentication credentials are missing, invalid, or not accepted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 401 code: type: string enum: - unauthenticated ForbiddenError: description: The authenticated caller is not allowed to perform this operation. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 403 code: type: string enum: - forbidden ConversionsNotFoundErrorResponse: description: The requested resource does not exist. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 404 code: type: string enum: - not_found RuleAlreadyDeletedErrorResponse: description: The conversion rule was already deleted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 409 code: type: string enum: - rule_already_deleted ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 500 code: type: string enum: - internal UnimplementedError: description: The operation is not implemented by the upstream service. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 501 code: type: string enum: - unimplemented UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 503 code: type: string enum: - unavailable DeadlineExceededError: description: The upstream service did not complete the request before the deadline. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 504 code: type: string enum: - deadline_exceeded PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' ConversionInvalidWithdrawalAddressCause: description: >- A single contributor to an invalid withdrawal address error. Each cause names one missing or invalid beneficiary bank field. type: object properties: field: description: >- Dot-notation path to the offending request field (e.g. `to.bank_account.bic`). type: string message: description: >- Human-readable explanation of why the field is required or invalid for the chosen withdrawal rail. type: string PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ````