퀵스타트

고객을 생성하고 재사용 가능한 지갑을 하나 준비한 뒤 필요한 샌드박스 흐름을 실행하세요.

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 계좌를 발급해요.

제3자 페이아웃을 원하시면 수취인 또는 자금 지급을 따라주세요.

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로 저장하세요. 범용 케이퍼빌리티 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}"

페이인

완전한 페이인 흐름을 구축하세요.

페이아웃

프로덕션 페이아웃 처리를 구축하세요.

발급 은행 계좌

프로비저닝과 정보를 처리하세요.

다음으로 웹훅을 추가하세요. 위의 각 요청에는 이미 완전한 API 레퍼런스 스키마와 상태 페이지가 링크되어 있어요.

시작하기

고객 온보딩

자금 흐름 구축

출시

1. 샌드박스 구성

2. 고객 생성

3. 결과 선택

4. 적격 케이퍼빌리티 찾기

5. 케이퍼빌리티 요청

6. 샌드박스에서 온보딩 완료

7. 선택한 흐름 구축

페이인

페이아웃

발급 은행 계좌

​1. 샌드박스 구성

​2. 고객 생성

​3. 결과 선택

​4. 적격 케이퍼빌리티 찾기

​5. 케이퍼빌리티 요청

​6. 샌드박스에서 온보딩 완료

​7. 선택한 흐름 구축

페이인

페이아웃

발급 은행 계좌

1. 샌드박스 구성

2. 고객 생성

3. 결과 선택

4. 적격 케이퍼빌리티 찾기

5. 케이퍼빌리티 요청

6. 샌드박스에서 온보딩 완료

7. 선택한 흐름 구축