> ## 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 transfer > Creates a transfer between accounts in the authenticated caller's program. The returned `transfer_id` is the originating reference for the corresponding Portfolio transaction. Once that transaction is visible, retrieve it with `GET /v1/accounts/{account_id}/portfolio/transactions` using `reference.kind=transfer` and `reference.id` equal to this `transfer_id`. Use the `from` account from this request as `account_id` when retrieving the initiating account's transaction. Transfer creation and Portfolio transaction visibility are asynchronous boundaries. A response with `status=complete` confirms the create operation's current outcome, but the corresponding Portfolio transaction may not be visible immediately. Discover it by polling Portfolio with the transfer type and an appropriate time range; the Portfolio transaction can first have `status=in_progress` before reaching `successful` or `failed`. This operation is not idempotent. If a request times out or otherwise has an unknown outcome, do not automatically retry it because the transfer may already have been created. First reconcile the source account's Portfolio transactions or contact Payward Services support. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json post /v1/transfers openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversion rules (rule-driven fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Travel Rule address ownership verification, 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: [] ApiSign: [] ApiNonce: [] 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: Conversion rules description: >- Rule-driven fiat ↔ crypto value movement, including conversion rules and deposits. - 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: Travel Rule Verifications description: Travel Rule address ownership verification flows. - name: Verifications description: Identity verification (KYC) submission and status for end users. - name: Webhooks description: Manage webhook subscriptions for asynchronous event delivery. paths: /v1/transfers: post: tags: - Funds summary: Create transfer description: > Creates a transfer between accounts in the authenticated caller's program. The returned `transfer_id` is the originating reference for the corresponding Portfolio transaction. Once that transaction is visible, retrieve it with `GET /v1/accounts/{account_id}/portfolio/transactions` using `reference.kind=transfer` and `reference.id` equal to this `transfer_id`. Use the `from` account from this request as `account_id` when retrieving the initiating account's transaction. Transfer creation and Portfolio transaction visibility are asynchronous boundaries. A response with `status=complete` confirms the create operation's current outcome, but the corresponding Portfolio transaction may not be visible immediately. Discover it by polling Portfolio with the transfer type and an appropriate time range; the Portfolio transaction can first have `status=in_progress` before reaching `successful` or `failed`. This operation is not idempotent. If a request times out or otherwise has an unknown outcome, do not automatically retry it because the transfer may already have been created. First reconcile the source account's Portfolio transactions or contact Payward Services support. operationId: createTransfer requestBody: required: true content: application/json: schema: description: Request to create an account-funded transfer. type: object required: - from - to - asset - amount properties: from: description: Public account ID to debit. allOf: - $ref: '#/components/schemas/AccountId' to: description: Public account ID to credit. allOf: - $ref: '#/components/schemas/AccountId' asset: description: >- Asset ticker symbol to transfer. Currency assets and tokenized assets such as xStocks are supported when eligible for transfers. type: string minLength: 1 maxLength: 16 amount: description: >- Decimal amount represented as a string to preserve precision. type: string minLength: 1 maxLength: 64 pattern: ^[0-9]+(\.[0-9]+)?$ examples: account-recipient: summary: Transfer a currency asset to an account value: from: WVSD33HRMGSZUBM7 to: WNPY3PJZYD4L9E7B asset: USD amount: '25.50' xstock-recipient: summary: Transfer an xStock to an account value: from: WVSD33HRMGSZUBM7 to: WNPY3PJZYD4L9E7B asset: TSLAx amount: '1.00' responses: '201': description: Transfer created. headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/CreateTransferEnvelope' examples: created: summary: Transfer accepted value: data: transfer_id: TRYCMN7-WXKJM-F47YIM status: pending completed: summary: Transfer completed value: data: transfer_id: TRYCMN7-WXKJM-F47YIM status: complete '400': description: Request validation failed or the transfer could not be processed. headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/BadRequestError' examples: invalid-transfer: summary: Transfer request cannot be processed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: transfer message: Transfer request cannot be processed status: 400 code: bad_request self-transfer: summary: Source and recipient are the same account value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: to message: >- Transfers from and to the same account are not supported status: 400 code: bad_request unsupported-asset: summary: Unsupported asset value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: asset message: Unsupported asset status: 400 code: bad_request insufficient-balance: summary: Insufficient balance value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b causes: - field: amount message: Insufficient balance status: 400 code: bad_request '401': description: Authentication required headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' examples: authentication-failed: summary: Authentication failed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: unauthenticated status: 401 '403': description: Forbidden headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' examples: caller-is-not-allowed: summary: Caller is not allowed value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: forbidden status: 403 '429': description: Rate limit exceeded headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' examples: rate-limit-exceeded: summary: Rate limit exceeded value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: resource_exhausted status: 429 '500': description: Internal server error headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: internal-error: summary: Internal server error value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: internal status: 500 '503': description: Service unavailable headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/UnavailableError' examples: service-unavailable: summary: Service unavailable value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: unavailable status: 503 '504': description: Request deadline exceeded headers: Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' Strict-Transport-Security: $ref: '#/components/headers/StrictTransportSecurity' X-Content-Type-Options: $ref: '#/components/headers/XContentTypeOptions' Content-Security-Policy: $ref: '#/components/headers/ContentSecurityPolicy' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' examples: request-deadline-exceeded: summary: Request deadline exceeded value: error: type: funding_error instance: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b code: deadline_exceeded status: 504 security: - ApiKey: [] ApiSign: [] ApiNonce: [] components: schemas: AccountId: type: string description: Canonical identifier for an account in the Payward public API. minLength: 14 maxLength: 42 CreateTransferEnvelope: description: Response returned after creating a transfer. type: object required: - data properties: data: description: Created transfer. allOf: - $ref: '#/components/schemas/Transfer' 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 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 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 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 Transfer: description: Created transfer. type: object required: - transfer_id - status properties: transfer_id: description: >- Opaque transfer identifier. When the corresponding Portfolio transaction is available, this value is returned as `reference.id` with `reference.kind=transfer`. It is distinct from the Portfolio transaction's `TX`-namespace `id`. type: string minLength: 1 maxLength: 128 status: description: Current status of the transfer creation operation. allOf: - $ref: '#/components/schemas/TransferStatus' 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' 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 TransferStatus: description: >- Coarsened status of the transfer creation operation. `pending` means the transfer is still being processed, `complete` means the create operation has completed, and `failed` means it could not be completed. type: string enum: - pending - complete - failed 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: RequestId: description: >- Unique identifier for tracing this request across services. Include in support tickets. schema: type: string format: uuid example: 5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b RateLimitLimit: description: Total requests allowed in the current window. schema: type: integer example: 1000 RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer example: 955 RateLimitReset: description: Unix timestamp (seconds) when the rate-limit window resets. schema: type: integer format: int64 example: 1713182400 StrictTransportSecurity: description: >- Enforces HTTPS for the configured period. Always `max-age=63072000; includeSubDomains; preload`. schema: type: string example: max-age=63072000; includeSubDomains; preload XContentTypeOptions: description: Disables MIME sniffing. Always `nosniff`. schema: type: string enum: - nosniff example: nosniff ContentSecurityPolicy: description: >- Prevents embedding and resource loading. Always `default-src 'none'; frame-ancestors 'none'`. schema: type: string example: default-src 'none'; frame-ancestors 'none' CacheControl: description: Prevents caching of sensitive financial data. Always `no-store`. schema: type: string enum: - no-store example: no-store RetryAfter: description: Seconds the client should wait before retrying. schema: type: integer example: 30 securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ````