Create transfer

Creates a transfer between accounts in the authenticated caller’s program.

If the conversion rate becomes stale before the transfer is created, the operation returns 409 with code stale_conversion_rate. Obtain a fresh rate before submitting a new transfer request.

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.

Idempotency-Key is optional to preserve compatibility with existing clients. When omitted, the operation remains non-idempotent: if a request times out or otherwise has an unknown outcome, do not automatically retry it because another transfer may be created. First reconcile the source account’s Portfolio transactions or contact Payward Services support.

When provided, Idempotency-Key must be a UUIDv4. Reusing the same key with the same request prevents a second transfer execution and returns the transfer’s current recorded outcome. The response can differ from the original response and does not include Idempotent-Replayed.

After the original transfer request has been recorded, reusing the same key with different, otherwise valid transfer parameters returns 409 Conflict. Each retry is validated before its idempotency key is compared with the recorded request. Consequently, a retry containing invalid parameters, such as an unsupported asset, returns the corresponding validation error instead of 409 Conflict. A request rejected before it is recorded may leave the key available for another request. Recorded transfer keys remain reserved beyond 24 hours and must not be reused for a new transfer. This is an exception to the general PWS idempotency standard.