Transfers

Overview

The Transfers API moves an asset from one PWS account to another account in the authenticated caller’s program. The source and destination must be distinct accounts. The accounts may belong to the same user or to different users, but both must be in the authenticated caller’s program. Only account-to-account transfers are supported. Email, username-tag, and other recipient types are not supported.

Prerequisites

Payward Services API credentials (see the Authentication guide)
A source account with a sufficient available balance
A destination account in the same program

Create a transfer

Send POST /v1/transfers with the source account, destination account, asset symbol, and decimal amount.

curl -X POST "https://api.services.payward.com/v1/transfers" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "WVSD33HRMGSZUBM7",
    "to": "WNPY3PJZYD4L9E7B",
    "asset": "USD",
    "amount": "25.50"
  }'

Make retries idempotent

Generate one UUIDv4 for each intended transfer. Reuse that same key only when retrying the identical request.

The same key and request prevent a second transfer execution. The retry returns the transfer’s current recorded outcome.
The same key with different, otherwise valid transfer parameters returns 409 Conflict with code idempotency_conflict.
A keyed retry does not replay the original HTTP status and body. The response does not include Idempotent-Replayed.
A request rejected before it is recorded may leave the key available for another request.
A recorded key remains reserved beyond 24 hours. Never reuse it for a new transfer.

If you omit Idempotency-Key, transfer creation is not idempotent. Do not automatically retry a timeout or another unknown outcome. Reconcile the source account through Portfolio or contact Payward Services support first.

Response

A successful request returns HTTP 201:

{
  "data": {
    "transfer_id": "TRYCMN7-WXKJM-F47YIM",
    "status": "pending"
  }
}

Status	Description
`pending`	The transfer is still being processed.
`complete`	The transfer creation operation completed.
`failed`	The transfer creation operation could not be completed.

transfer_id is an opaque originating reference. It is distinct from the Portfolio transaction ID.

Reconcile through Portfolio

Transfer creation and Portfolio visibility are asynchronous. A create response with status: complete does not guarantee that the Portfolio transaction is visible yet. Poll GET /v1/accounts/{account_id}/portfolio/transactions using:

the request’s from account as account_id
types=transfer
a time range that includes the create request
no statuses filter, or a filter that includes in_progress

curl --get "https://api.services.payward.com/v1/accounts/WVSD33HRMGSZUBM7/portfolio/transactions" \
  --data-urlencode "types=transfer" \
  --data-urlencode "start_timestamp=2026-07-23T10:00:00Z" \
  --data-urlencode "end_timestamp=2026-07-23T11:00:00Z" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN"

Portfolio transactions are account-relative. The from account response contains spend, while the to account response contains receive. The example below queries the from account, so it shows only spend. When the transaction appears, its reference links it to the create response:

{
  "data": [
    {
      "id": "TXYCMN8-ABCD2-EFGH3I",
      "timestamp": "2026-07-23T10:15:30Z",
      "type": "transfer",
      "status": "in_progress",
      "reference": {
        "kind": "transfer",
        "id": "TRYCMN7-WXKJM-F47YIM"
      },
      "spend": {
        "sub_total": {
          "symbol": "USD",
          "name": "US Dollar",
          "type": "fiat",
          "amount": "25.50",
          "amount_in_quote": "25.50"
        },
        "total": {
          "symbol": "USD",
          "name": "US Dollar",
          "type": "fiat",
          "amount": "25.50",
          "amount_in_quote": "25.50"
        },
        "timestamp": "2026-07-23T10:15:30Z"
      }
    }
  ],
  "quote_symbol": "USD",
  "quote_type": "fiat"
}

Use the reference for deterministic later lookups:

references[0][kind]=transfer
references[0][id]=TRYCMN7-WXKJM-F47YIM

Reference entries use OR semantics with each other. They combine with types and other filters using AND semantics. Keep these identifiers distinct:

Identifier	Meaning
Portfolio `id` (`TX...`)	The Portfolio transaction identifier.
`reference.id` with `funding`	The originating Funding deposit identifier.
`reference.id` with `transfer`	The `transfer_id` returned by create.

Error handling

HTTP status	Cause
`400 Bad Request`	Invalid request, unsupported asset, or insufficient balance
`401 Unauthorized`	Missing or invalid API credentials
`403 Forbidden`	The caller cannot access an account or operation
`409 Conflict`	Idempotency key conflict or stale conversion rate
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected service failure
`503 Service Unavailable`	A required service is temporarily unavailable
`504 Gateway Timeout`	A required service did not respond in time

Get started

Market data

Accounts

Verifications

Trade

Earn

Payments

Overview

Prerequisites

Create a transfer

Make retries idempotent

Response

Reconcile through Portfolio

Error handling

​Overview

​Prerequisites

​Create a transfer

​Make retries idempotent

​Response

​Reconcile through Portfolio

​Error handling

Overview

Prerequisites

Create a transfer

Make retries idempotent

Response

Reconcile through Portfolio

Error handling