Create and Track Transfers

Overview

This guide documents the published SYSTEM transfer path available in this repo: create the transfer against a Slash connection, then track it through provider or internal admin transfer-order APIs. Creation and tracking live under different endpoint families, so the client must persist identifiers carefully.

Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. Slash connection business ID
4. workspace ID for history lookups
5. storage for provider IDs and any internal transfer bizId

Shared Headers

X-PORTAL-ACCESS-CODE: <system-portal-code>
Authorization: Bearer <accessToken>
Content-Type: application/json

Step-by-Step Flow

1. Create the transfer

API endpoint: POST /web/v1/slash/connections/{connectionBizId}/transfers This forwards the payload to the provider and returns the initial provider-side status.

curl -X POST 'https://api.example.com/web/v1/slash/connections/conn_abc123/transfers' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"sourceAccountId":"acct_src_001","destinationAccountId":"acct_dst_002","amount":50000,"currency":"USD","reference":"Monthly settlement"}'

{"code":"2000","message":"SUCCESS","data":{"id":"txfr_abc123","status":"pending","amount":50000,"currency":"USD"}}

2. Persist the returned identifier

API endpoint: application-side persistence step Store the provider ID immediately. If your application also creates an internal transfer order, store its bizId too.

{"providerTransferId":"txfr_abc123","internalTransferBizId":"TRF20260321000001","workspaceId":"WS_001"}

3. Query the internal transfer order by bizId

API endpoint: GET /web/v1/admin/transfer/query/orders/{bizId} Use this when the transfer has been mirrored into the internal ledger.

curl 'https://api.example.com/web/v1/admin/transfer/query/orders/TRF20260321000001' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"bizId":"TRF20260321000001","fromWalletId":"WLT-SRC-001","toWalletId":"WLT-DST-002","amount":100.5,"status":2,"statusName":"COMPLETED","failureReason":null}}

4. Poll the completion endpoint

API endpoint: GET /web/v1/admin/transfer/query/orders/{bizId}/completed This is the lightweight polling path for repeated status checks.

curl 'https://api.example.com/web/v1/admin/transfer/query/orders/TRF20260321000001/completed' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":true}

5. Inspect workspace transfer history

API endpoint: GET /web/v1/admin/transfer/query/orders/workspace/{workspaceId} Use this when a direct bizId is unavailable or operators need reconciliation context.

curl 'https://api.example.com/web/v1/admin/transfer/query/orders/workspace/WS_001?startTime=2026-03-01T00:00:00Z&endTime=2026-03-29T23:59:59Z&page=0&size=20&sort=createdAt,desc' \
  -H 'X-PORTAL-ACCESS-CODE: <system-portal-code>' \
  -H 'Authorization: Bearer <accessToken>'

{"code":"2000","message":"SUCCESS","data":{"content":[{"bizId":"TRF20260321000001","statusName":"COMPLETED","amount":100.5,"createdAt":"2026-03-21T10:00:00Z"}],"totalElements":1}}

Transfer Status Lifecycle

1. PENDING right after creation or internal acceptance
2. PROCESSING while funds are moving
3. COMPLETED when the transfer reaches terminal success
4. FAILED when the transfer stops with a non-recoverable error

Decision Points

1. if only the provider ID is available, track the provider state until an internal bizId appears
2. if the create response is already terminal, skip aggressive polling
3. use the full transfer-order fetch when the UI needs failure reason or wallet metadata
4. use workspace history for reconciliation and support tooling

Error Handling

1. 4000 on create usually means the forwarded payload is invalid
2. 4040 on internal lookup usually means the bizId is wrong or not materialized yet
3. treat FAILED and non-null failureReason as terminal states
4. do not assume the provider id and internal bizId are the same field

Next Steps

1. Wallets Discovery and Balances
2. Workspace Guide
3. Notifications Guide