Transfers Guide

Overview

The SYSTEM transfer domain spans two related surfaces in this repo: provider-side creation through slash-payment and internal/admin transfer-order tracking through the transfer endpoints. That split matters because transfer creation and transfer status inspection do not currently live under the same published path family.

What This Domain Covers

1. creating a transfer against a Slash connection
2. storing the returned business or provider identifiers
3. querying transfer orders by business ID
4. polling completion state
5. inspecting workspace transfer history

Common Prerequisites

1. Authorization: Bearer <accessToken>
2. X-PORTAL-ACCESS-CODE: <system-portal-code>
3. workspace and connection context
4. knowledge of whether the product uses provider IDs, internal transfer bizId values, or both

Shared Headers

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

Published Endpoint Families

Transfer creation

1. POST /web/v1/slash/connections/{connectionBizId}/transfers

Internal transfer-order tracking

1. GET /web/v1/admin/transfer/query/orders/{bizId}
2. GET /web/v1/admin/transfer/query/orders/{bizId}/completed
3. GET /web/v1/admin/transfer/query/orders/workspace/{workspaceId}

Transfer Status Lifecycle

Use the transfer constants as the canonical status vocabulary:

1. PENDING
2. PROCESSING
3. COMPLETED
4. FAILED

The create endpoint may expose provider-native lowercase states such as pending, while the admin transfer-order endpoints expose internal status codes and names.

Typical Developer Sequence

1. create the transfer against the provider connection
2. store the returned identifier immediately
3. if the transfer is mirrored into the internal transfer ledger, query the transfer-order bizId
4. poll the lightweight completion endpoint until the transfer is terminal
5. fall back to the workspace transfer list for reconciliation or troubleshooting

Decision Points

1. whether the caller needs immediate provider confirmation only or internal ledger reconciliation as well
2. whether a transfer is tracked by external transaction ID, internal bizId, or both
3. whether polling should use the lightweight completion endpoint or the full transfer-order fetch
4. whether failures should route into retry UX or operator reconciliation

Error Handling

1. a 4000 on create usually means the provider payload is invalid
2. a 4040 on admin lookup means the bizId is wrong or the order has not yet been materialized into the internal transfer ledger
3. treat FAILED and provider-specific failure reasons as user-visible terminal states
4. the workspace list endpoint is useful for backfill and audit even when direct bizId lookup is unavailable

Next Steps

1. Create and Track Transfers
2. Wallets Guide
3. Workspace Guide