快速入門

建立客戶、準備一個可重複使用的錢包,然後執行您需要的沙箱流程。

1. 設定沙箱

從您的後端使用沙箱 API 金鑰:

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_SANDBOX_API_KEY='replace-with-your-sandbox-key'

該金鑰會在共用 API 主機上選擇沙箱環境。

2. 建立客戶

使用 POST /v3/customers 建立個人客戶:

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-customer-001" \
  --header "Content-Type: application/json" \
  --data '{"type":"individual","externalId":"quickstart-customer-001"}'

將 data.id 儲存為 CUSTOMER_ID。

3. 選擇結果

入金: 收取 USD 並將 USDC 結算至客戶發行的錢包。
出金: 從客戶發行的錢包發送 USDC 至客戶名下的銀行帳戶。
發行銀行帳戶: 發行一個 ACH/USD 帳戶,並結算至客戶發行的錢包。

若要進行第三方出金,請依照收款人或發送資金。

4. 尋找符合資格的能力

使用 GET /v3/customers/{customerId}/capabilities/supported 列出支援的能力:

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/supported" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

選擇一個回應項目,其 availability 為 available 或 beta、eligibility.eligible 為 true、所需的 directions 與 method,以及對應的 accountType。將客戶發行的錢包作為入金目的地、出金來源或銀行帳戶結算帳戶;而在此出金路徑中,則將客戶名下帳戶作為 destinationId。若回傳了 institutions,請僅使用回傳的機構選項。將該項目的 id 儲存為 CAPABILITY_ID;請勿硬編碼萬用的 capability ID。

5. 申請該能力

使用 POST /v3/customers/{customerId}/capabilities/{capabilityId} 申請選定的能力:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-capability-001" \
  --header "Content-Type: application/json" \
  --data '{}'

將 data.status 儲存為 CAPABILITY_STATUS,並將 data.openTaskIds 儲存為 TASK_IDS。

6. 於沙箱中完成入駐

若 TASK_IDS 不為空,請依照能力與任務完成每一項當前的要求。在本教學中,請使用 POST /v3/sandbox/customers/{customerId}/capabilities/{capabilityId}/status 將該能力設為 ready:

curl --request POST \
  "${API_BASE}/v3/sandbox/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}/status" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"status":"ready"}'

此測試控制不是正式的入駐流程。請使用 GET /v3/customers/{customerId}/capabilities/{capabilityId} 重新讀取:

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

從 data.status 與 data.openTaskIds 更新 CAPABILITY_STATUS 與 TASK_IDS。僅在 CAPABILITY_STATUS 為 ready 時繼續。

7. 建構所選的流程

使用 POST /v3/customers/{customerId}/accounts 在 Base 上建立一個發行的 USDC 錢包:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-flow-wallet-001" \
  --header "Content-Type: application/json" \
  --data '{"origin":"issued","type":"wallet","currency":"USDC","network":"base"}'

將 data.id 儲存為 FLOW_WALLET_ID、data.status 儲存為 FLOW_WALLET_STATUS,並將 data.openTaskIds 儲存為 FLOW_WALLET_TASK_IDS。若 FLOW_WALLET_TASK_IDS 不為空,請依照能力與任務完成當前的任務。使用 GET /v3/customers/{customerId}/accounts/{accountId} 重新讀取錢包:

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts/${FLOW_WALLET_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

從 data.status 與 data.openTaskIds 更新 FLOW_WALLET_STATUS 與 FLOW_WALLET_TASK_IDS。僅在 FLOW_WALLET_STATUS 為 ready 時繼續。

入金
出金
發行銀行帳戶

使用 POST /v3/quotes 建立 USD 兌 USDC 報價:

curl --request POST \
  "${API_BASE}/v3/quotes" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payin-quote-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"customerId":"${CUSTOMER_ID}","capabilityId":"${CAPABILITY_ID}","in":{"amount":"150.00","currency":"USD"},"destinationId":"${FLOW_WALLET_ID}","out":{"currency":"USDC"}}
JSON

將 data.id 儲存為 QUOTE_ID,然後使用 POST /v3/transfers 執行:

curl --request POST \
  "${API_BASE}/v3/transfers" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payin-transfer-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"quoteId":"${QUOTE_ID}"}
JSON

將 data.id 儲存為 TRANSFER_ID。使用 GET /v3/transfers/{transferId}/instructions 取得指示:

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}/instructions" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

回應包含 data.transferId 與 data.instructions。將 data.transferId 儲存為 TRANSFER_ID,將 data.instructions 儲存為 FUNDING_INSTRUCTIONS。

使用 POST /v3/sandbox/accounts/{accountId}/topup 為就緒的錢包儲值:

curl --request POST \
  "${API_BASE}/v3/sandbox/accounts/${FLOW_WALLET_ID}/topup" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"amount":"250.00","currency":"USDC"}'

使用 POST /v3/customers/{customerId}/accounts 建立客戶名下的 ACH 帳戶:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payout-account-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{"origin":"external","type":"bank","methods":["ach"],"country":"US","currency":"USD","details":{"routingNumber":"021000021","accountNumber":"123456789","accountType":"checking","bankName":"Example Bank","accountHolderName":"Amina Diallo"}}
JSON

將 data.id 儲存為 PAYOUT_ACCOUNT_ID、data.status 儲存為 PAYOUT_ACCOUNT_STATUS,並將 data.openTaskIds 儲存為 PAYOUT_ACCOUNT_TASK_IDS。若 PAYOUT_ACCOUNT_TASK_IDS 不為空,請依照能力與任務完成當前的任務。使用 GET /v3/customers/{customerId}/accounts/{accountId} 重新讀取:

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts/${PAYOUT_ACCOUNT_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

從 data.status 與 data.openTaskIds 更新 PAYOUT_ACCOUNT_STATUS 與 PAYOUT_ACCOUNT_TASK_IDS。僅在 PAYOUT_ACCOUNT_STATUS 為 ready 時繼續,然後使用 POST /v3/quotes 建立報價:

curl --request POST \
  "${API_BASE}/v3/quotes" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payout-quote-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"customerId":"${CUSTOMER_ID}","capabilityId":"${CAPABILITY_ID}","in":{"amount":"150.00","currency":"USDC","accountId":"${FLOW_WALLET_ID}"},"destinationId":"${PAYOUT_ACCOUNT_ID}","out":{"currency":"USD"}}
JSON

將 data.id 儲存為 QUOTE_ID,使用 POST /v3/transfers 執行,並將回傳的 data.id 儲存為 TRANSFER_ID:

curl --request POST \
  "${API_BASE}/v3/transfers" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payout-transfer-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"quoteId":"${QUOTE_ID}"}
JSON

使用 POST /v3/customers/{customerId}/accounts 建立一個 ACH/USD 帳戶,並結算至就緒的錢包:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-bank-account-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"origin":"issued","type":"bank","method":"ach","country":"US","currency":"USD","settlement":{"accountId":"${FLOW_WALLET_ID}"}}
JSON

將 data.id 儲存為 BANK_ACCOUNT_ID,然後使用 GET /v3/customers/{customerId}/accounts/{accountId} 讀取佈建狀態:

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts/${BANK_ACCOUNT_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

將 data.status 儲存為 BANK_ACCOUNT_STATUS、data.details 儲存為 BANK_ACCOUNT_DETAILS,並將 data.openTaskIds 儲存為 BANK_ACCOUNT_TASK_IDS。完成任何當前任務,然後再次讀取該帳戶,直到其狀態允許使用且 data.details 已存在。銀行資料可能不會立即提供。當您能夠呈現 BANK_ACCOUNT_DETAILS 中所回傳的完整、可重複使用的銀行資料時,此分支才算完成。切勿在帳戶仍在佈建期間建構或顯示暫時性的資料。

對於入金與出金,請使用 GET /v3/transfers/{transferId} 監控 TRANSFER_ID:

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

入金

建構完整的入金流程。

出金

建構正式環境的出金處理。

發行銀行帳戶

處理佈建與帳戶資料。

接下來,請加入 webhook。上述每個請求都已連結至其完整的 API 參考結構與狀態說明頁。

開始使用

客戶引導

建立金流

上線

1. 設定沙箱

2. 建立客戶

3. 選擇結果

4. 尋找符合資格的能力

5. 申請該能力

6. 於沙箱中完成入駐

7. 建構所選的流程

入金

出金

發行銀行帳戶

​1. 設定沙箱

​2. 建立客戶

​3. 選擇結果

​4. 尋找符合資格的能力

​5. 申請該能力

​6. 於沙箱中完成入駐

​7. 建構所選的流程

入金

出金

發行銀行帳戶

1. 設定沙箱

2. 建立客戶

3. 選擇結果

4. 尋找符合資格的能力

5. 申請該能力

6. 於沙箱中完成入駐

7. 建構所選的流程