> ## 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. # Create conversion rule > Creates a new conversion rule. Provisions the inbound deposit endpoint (IBAN for fiat-source, crypto address for crypto-source) the caller will fund. Once funded, transactions are produced against this conversion rule and become observable via the transactions surface. ## OpenAPI ````yaml https://d2588n1sy4m36o.cloudfront.net/uat/merged/openapi.json post /v1/accounts/{account_id}/conversions openapi: 3.1.0 info: title: PWS Public API version: '1' description: >- Integrate with Payward Services to onboard users, manage accounts and funds, trade assets, and receive event notifications. contact: name: Payward Services servers: - url: https://api.sandbox.services.payward.com security: [] tags: - name: Assets description: List the assets PWS is willing to swap. x-displayName: Assets - name: Conversions description: >- Rule-driven and on-demand fiat ↔ crypto value movement, including conversion rules and deposits. x-displayName: Conversions - name: Auto Earn description: >- Manage Auto Earn preferences and retrieve allocation and reward information. x-displayName: Auto Earn - name: Bonded Earn description: >- Allocate funds to and deallocate funds from bonded earn strategies, review allocations, and track request status. x-displayName: Bonded Earn - name: Funding description: >- Discover deposit and withdrawal options, manage deposit addresses, and move funds between accounts. x-displayName: Funding - name: Derivative transfers description: >- Move funds between an account's spot balance and the same owner's futures balance. x-displayName: Derivative transfers - name: Portfolio description: 'Inspect a customer''s portfolio: balances, valuations, and transactions.' x-displayName: Portfolio - name: Ramp description: >- Support Ramp flows with discovery, quotes, limits, and hosted checkout experiences. x-displayName: Ramp - name: Reports description: Settlement and reconciliation reports for the partner. x-displayName: Reports - name: Swaps description: Account-funded quotes that lock a price until they expire or are executed. x-displayName: Swaps - name: Onchain quotes description: Wallet-funded quotes that return the data needed to settle onchain. x-displayName: Onchain quotes - name: Price trigger swaps description: Swaps that wait for a target price before submitting a trade. x-displayName: Price trigger swaps - name: Travel Rule verifications description: Travel Rule address ownership verification flows. x-displayName: Travel Rule verifications - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions an account-owned user from an external reference and optional email. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. x-displayName: Users - name: Verifications description: Identity verification (KYC) submission and status for end users. x-displayName: Verifications - name: Webhooks description: >- Register HTTPS destinations to receive event deliveries, rotate signing secrets, and inspect, update, or delete existing subscriptions. Each subscription is owned by the authenticated partner; deliveries are signed with HMAC-SHA256 and retried on transient failures. x-displayName: Webhooks paths: /v1/accounts/{account_id}/conversions: post: tags: - Conversions summary: Create conversion rule description: >- Creates a new conversion rule. Provisions the inbound deposit endpoint (IBAN for fiat-source, crypto address for crypto-source) the caller will fund. Once funded, transactions are produced against this conversion rule and become observable via the transactions surface. operationId: createConversionRule parameters: - $ref: '#/components/parameters/AccountId' requestBody: content: application/json: schema: description: Request to create a new conversion rule. type: object properties: name: description: Optional partner-facing label for the conversion rule. type: string minLength: 1 maxLength: 128 from: description: >- Source side. Partners only specify `symbol`, `type`, and `via` here; any `address`/`bank_account` supplied is ignored (the inbound is provisioned by autoramp). type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: Asset ticker symbol (e.g., "EUR", "USDC", "BTC"). 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 name from the List deposit methods `network` field. 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 account_link_id: description: >- Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail. type: string minLength: 1 maxLength: 128 required: - via title: BankAccount required: - symbol - type title: ConversionEndpoint to: description: >- Destination side. Requires `address` (wallet) or `bank_account` (bank). type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: Asset ticker symbol (e.g., "EUR", "USDC", "BTC"). 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 name from the List deposit methods `network` field. 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 account_link_id: description: >- Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail. type: string minLength: 1 maxLength: 128 required: - via title: BankAccount required: - symbol - type title: ConversionEndpoint required: - from - to examples: id-create-conversion-rule-ok: summary: Convert EUR deposits to USDC on Polygon value: name: EUR autoramp to Polygon vault from: symbol: EUR type: bank bank_account: via: sepa to: symbol: USDC type: wallet wallet: via: polygon address: '0x1234567890abcdef1234567890abcdef12345678' required: true responses: '200': description: Successful response headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: type: object properties: data: description: The newly created conversion rule. type: object properties: id: description: Unique identifier for this conversion rule. type: string format: uuid name: description: Optional partner-facing label for the conversion rule. 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: $ref: '#/components/schemas/AssetSymbol' description: Asset ticker symbol (e.g., "EUR", "USDC", "BTC"). 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 name from the List deposit methods `network` field. 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. It appears on Get and List for SEPA (not currently returned for FPS); 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 or EMI (electronic money institution) address on the provisioned inbound. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); 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 or EMI address. Populated once the virtual account is provisioned. It appears on Get and List for SEPA (not currently returned for FPS); 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 account_link_id: description: >- Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail. type: string minLength: 1 maxLength: 128 required: - via title: BankAccount required: - type title: ConversionEndpoint to: description: >- Destination side. `address`/`bank_account` are partner-supplied. type: object properties: symbol: $ref: '#/components/schemas/AssetSymbol' description: Asset ticker symbol (e.g., "EUR", "USDC", "BTC"). 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 name from the List deposit methods `network` field. 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 account_link_id: description: >- Public Account Link identifier naming the linked bank account this endpoint routes to, in place of raw routing fields. Mutually exclusive with raw routing fields; `via` still selects the rail. type: string minLength: 1 maxLength: 128 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/DateTime' description: Time at which the conversion rule was created. updated_at: $ref: '#/components/schemas/DateTime' description: Time at which the conversion rule was last updated. required: - id - from - to - status - created_at - updated_at title: ConversionRule required: - data examples: id-create-conversion-rule-ok: summary: Created conversion rule with deposit instructions value: data: id: 550e8400-e29b-41d4-a716-446655440000 name: EUR autoramp to Polygon vault from: symbol: EUR type: bank bank_account: via: sepa iban: DE89370400440532013000 bic: COBADEFFXXX 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: '0x1234567890abcdef1234567890abcdef12345678' status: active created_at: '2026-05-25T10:30:00Z' updated_at: '2026-05-25T10:30:00Z' '400': $ref: '#/components/responses/ConversionsInvalidWithdrawalAddressResponse' description: Validation error '401': $ref: '#/components/responses/ConversionsUnauthenticatedResponse' description: Authentication required '403': $ref: '#/components/responses/ConversionsForbiddenResponse' description: Forbidden '404': $ref: '#/components/responses/ConversionsNotFoundResponse' description: Not found '409': $ref: '#/components/responses/ConversionsConversionLimitReachedResponse' description: Conflict '429': $ref: '#/components/responses/ConversionsResourceExhaustedResponse' description: Rate limit exceeded '500': $ref: '#/components/responses/ConversionsInternalResponse' description: Internal server error '501': $ref: '#/components/responses/ConversionsUnimplementedResponse' description: Error response '503': $ref: '#/components/responses/ConversionsUnavailableResponse' description: Service unavailable '504': $ref: '#/components/responses/ConversionsDeadlineExceededResponse' description: Deadline exceeded security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: parameters: AccountId: name: account_id in: path required: true example: WVSD33HRMGSZUBM7 schema: $ref: '#/components/schemas/AccountId' schemas: AssetSymbol: description: Symbol identifying an asset within its asset category. type: string minLength: 1 maxLength: 16 DateTime: description: RFC 3339 timestamp. type: string format: date-time AccountId: description: Globally unique public identifier for an account. type: string minLength: 14 maxLength: 42 BadRequestError: title: Bad Request description: Request validation failed or the request could not be processed. oneOf: - title: Bad Request 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 const: 400 code: type: string enum: - bad_request - title: Gateway description: >- Gateway-level validation failure returned before the request reaches the service. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 400 code: type: string const: gateway Conversions_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. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code - causes properties: status: type: integer format: int32 const: 400 code: type: string enum: - conversion_invalid_withdrawal_address causes: description: One entry per missing or invalid beneficiary bank field. type: array minItems: 1 items: $ref: >- #/components/schemas/Conversions_ConversionInvalidWithdrawalAddressCause UnauthenticatedError: title: Unauthenticated description: Authentication credentials are missing, invalid, or not accepted. oneOf: - title: Unauthenticated 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 const: 401 code: type: string enum: - unauthenticated - title: Gateway description: Authentication failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 401 code: type: string const: gateway ForbiddenError: title: Forbidden description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden 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 const: 403 code: type: string enum: - forbidden - title: Gateway description: Authorization failure returned by the API gateway. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway Conversions_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 const: 404 code: type: string enum: - not_found Conversions_ConversionLimitReachedErrorResponse: description: The maximum number of conversion rules was reached. 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 const: 409 code: type: string enum: - conversion_limit_reached 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 const: 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 const: 500 code: type: string enum: - internal UnimplementedError: description: The requested operation is not implemented. 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 const: 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 const: 503 code: type: string enum: - unavailable DeadlineExceededError: description: The request deadline was exceeded before a response could be produced. 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 const: 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' description: Validation error details. 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' Conversions_ConversionInvalidWithdrawalAddressCause: description: >- A single contributor to an invalid withdrawal address error. Each cause names one missing or invalid beneficiary bank field. type: object required: - field - message 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' description: General error details. 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 headers: TraceId: description: Trace identifier for the request. Include it when contacting support. schema: type: string example: 4bf92f3577b34da6a3ce929d0e0e4736 StrictTransportSecurity: description: Enforces HTTPS for the duration specified by `max-age`. schema: type: string example: max-age=31536000; includeSubDomains; preload CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store responses: ConversionsInvalidWithdrawalAddressResponse: description: Request validation failed or the withdrawal destination is invalid. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: oneOf: - $ref: '#/components/schemas/BadRequestError' title: Bad Request - $ref: >- #/components/schemas/Conversions_ConversionInvalidWithdrawalAddressErrorResponse title: Invalid withdrawal address examples: invalid-request: $ref: '#/components/examples/conversions-bad-request' invalid-withdrawal-address: $ref: '#/components/examples/conversions-invalid-withdrawal-address' ConversionsUnauthenticatedResponse: description: Authentication required. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: authentication-failed: $ref: '#/components/examples/conversions-unauthenticated' ConversionsForbiddenResponse: description: Forbidden. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: caller-is-not-allowed: $ref: '#/components/examples/conversions-forbidden' ConversionsNotFoundResponse: description: The requested conversion resource was not found. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/Conversions_ConversionsNotFoundErrorResponse' examples: conversion-resource-not-found: $ref: '#/components/examples/conversions-not-found' ConversionsConversionLimitReachedResponse: description: The maximum number of conversion rules was reached. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: >- #/components/schemas/Conversions_ConversionLimitReachedErrorResponse examples: conversion-limit-reached: $ref: '#/components/examples/conversions-conversion-limit-reached' ConversionsResourceExhaustedResponse: description: Rate limit exceeded. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: rate-limit-exceeded: $ref: '#/components/examples/conversions-resource-exhausted' ConversionsInternalResponse: description: Internal server error. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: $ref: '#/components/examples/conversions-internal' ConversionsUnimplementedResponse: description: Operation not implemented. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnimplementedError' examples: operation-not-implemented: $ref: '#/components/examples/conversions-unimplemented' ConversionsUnavailableResponse: description: Service unavailable. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: service-unavailable: $ref: '#/components/examples/conversions-unavailable' ConversionsDeadlineExceededResponse: description: Request deadline exceeded. headers: X-Trace-Id: $ref: '#/components/headers/TraceId' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: request-deadline-exceeded: $ref: '#/components/examples/conversions-deadline-exceeded' examples: conversions-bad-request: summary: Invalid request value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: bad_request causes: - field: account_id message: must be a valid account identifier conversions-invalid-withdrawal-address: summary: Invalid withdrawal address value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 400 code: conversion_invalid_withdrawal_address causes: - field: to.bank_account.bic message: is required for SEPA withdrawals conversions-unauthenticated: summary: Authentication failed value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 401 code: unauthenticated conversions-forbidden: summary: Caller is not allowed value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 403 code: forbidden conversions-not-found: summary: Conversion resource not found value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 404 code: not_found conversions-conversion-limit-reached: summary: Conversion limit reached value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 409 code: conversion_limit_reached conversions-resource-exhausted: summary: Rate limit exceeded value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 429 code: resource_exhausted conversions-internal: summary: Internal server error value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 500 code: internal conversions-unimplemented: summary: Operation not implemented value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 501 code: unimplemented conversions-unavailable: summary: Service unavailable value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 503 code: unavailable conversions-deadline-exceeded: summary: Request deadline exceeded value: error: type: conversions_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b status: 504 code: deadline_exceeded securitySchemes: ApiKey: type: apiKey in: header name: API-Key description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey in: header name: API-Sign description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey in: header name: API-Nonce description: Monotonically increasing nonce included in the request signature. ````