샌드박스 테스트

샌드박스는 프로덕션과 동일한 API 호스트를 사용해요. 샌드박스 API 키가 테스트 환경을 선택하며, 헬퍼가 실제 자금을 이동시키지 않고 결과를 시뮬레이션해요. 키는 백엔드에 보관하세요. 샌드박스 헬퍼는 프로덕션 컴플라이언스나 온보딩을 대체하지 않아요. 샌드박스 동작이 반환하는 유효성 검사, 상태, 재시도 가능한 플랫폼 실패를 통합이 어떻게 처리하는지 테스트하려면 오류 및 재시도를 사용하세요.

Environment variables

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

케이퍼빌리티 준비 상태 테스트

샌드박스에서는 ACH, Wire, SWIFT 케이퍼빌리티가 지정형과 풀형 모두 JPMorgan Chase(jpmorgan)에서만 제공돼요. 이러한 케이퍼빌리티를 요청할 때 institutions를 생략하면 Swipelux가 jpmorgan을 선택해요. 다른 은행을 지정하면 422 capability_institutions_unsupported가 반환돼요. 샌드박스의 지원 케이퍼빌리티 목록에는 이 방식들에 대해 jpmorgan만 표시돼요. 프로덕션 라우팅과 RTP, Pix, SPEI 같은 다른 방식은 변경되지 않아요.

Request a sandbox bank capability

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

케이퍼빌리티를 요청한 후 POST /v3/sandbox/customers/{customerId}/capabilities/{capabilityId}/status로 샌드박스 상태를 설정하세요:

Set capability status

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"}'

헬퍼를 사용한 후에는 케이퍼빌리티를 다시 조회하세요. 현재 status와 openTaskIds를 제품이 처리해야 하는 결과로 다루세요. 200 응답에도 고객 태스크나 pending 검토 같은 미완료 작업이 표시될 수 있어요. approval_scope_review_required, 운영상 보류, 종료 상태처럼 샌드박스에서 해소할 수 없는 이유로 케이퍼빌리티가 요청한 상태에 도달할 수 없으면 헬퍼는 409 capability_status_blocked를 반환해요. 문제 응답의 statusReason에는 케이퍼빌리티의 사유 코드와 메시지가 retryable: false와 함께 담겨요. 사유의 resolution을 확인하려면 케이퍼빌리티를 조회하세요. 지정형 케이퍼빌리티를 두 번째로 rejected로 강제하면 같은 케이퍼빌리티가 변경 없이 반환돼요. 거절된 케이퍼빌리티를 restricted 또는 ready로 강제하면 422 invalid_capability가 반환돼요. 이러한 상태를 테스트하려면 대신 새 샌드박스 고객을 생성하세요.

열린 태스크 테스트

POST /v3/sandbox/tasks로 샌드박스 태스크를 생성하세요. 테스트할 워크플로우의 리소스로 범위를 지정하고 items로 고객이 제출해야 할 내용을 설명하세요. 이 가이드는 capability 및 transfer 워크플로우를 보여 줘요. customer 스코프와 전체 요청 스키마는 API Reference에서 확인하세요. 텍스트 답변에는 explanation 항목을, 파일 업로드에는 document 항목을 사용하세요. 새 profile 항목에는 고객 필드를 지정하는 JSON Pointer인 profilePointer도 필요해요. 다른 항목 타입과 필드는 샌드박스 태스크 생성을 참고하세요. transfer 예시에서는 먼저 입금 또는 지급 플로우로 샌드박스 transfer를 생성한 다음, 반환된 data.id를 내보내세요:

Transfer ID

export TRANSFER_ID='tr_replace_with_your_transfer_id'

케이퍼빌리티 + explanation
전송 RFI + document

curl --request POST \
  "${API_BASE}/v3/sandbox/tasks" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "scope": {
    "type": "capability",
    "customerId": "${CUSTOMER_ID}",
    "capabilityId": "${CAPABILITY_ID}"
  },
  "items": [
    {
      "type": "explanation",
      "request": "Explain the source of funds."
    }
  ]
}
JSON

검토 중인 전송으로 태스크의 범위를 지정하고, 허용되는 유형, 형식, 유효 기간을 좁히는 constraints와 함께 document를 요청하세요.

Create document task

curl --request POST \
  "${API_BASE}/v3/sandbox/tasks" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "scope": {
    "type": "transfer",
    "customerId": "${CUSTOMER_ID}",
    "transferId": "${TRANSFER_ID}"
  },
  "category": "transaction_rfi",
  "items": [
    {
      "type": "document",
      "request": "Upload a bank statement showing the source of funds for this transfer.",
      "constraints": {
        "acceptedDocumentTypes": ["bank_statement"],
        "acceptedFormats": ["pdf", "jpeg"],
        "maxAgeDays": 90
      }
    }
  ]
}
JSON

이 예시는 허용되는 문서 타입, 형식, 유효 기간을 제한해요. 지원되는 모든 문서 제약 조건은 샌드박스 태스크 생성을 참고하세요.

data.id를 TASK_ID, data.revision을 TASK_REVISION, 현재 data.requirements[0].id를 REQUIREMENT_ID로 저장하세요. POST /v3/customers/{customerId}/tasks/{taskId}/submissions를 호출할 때는 생성한 항목 타입에 답변을 맞추세요:

설명 답변
문서 답변

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: sandbox-task-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "taskRevision": ${TASK_REVISION},
  "answers": [
    {
      "requirementId": "${REQUIREMENT_ID}",
      "answer": {
        "type": "text",
        "value": "Sandbox requirement completed."
      }
    }
  ]
}
JSON

POST /v3/customers/{customerId}/documents로 조건에 맞는 파일을 업로드하고, 반환된 data.id를 DOCUMENT_ID로 저장한 다음 문서 답변으로 제출하세요:

Upload document

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: sandbox-task-document-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "taskRevision": ${TASK_REVISION},
  "answers": [
    {
      "requirementId": "${REQUIREMENT_ID}",
      "answer": {
        "type": "document",
        "documentIds": ["${DOCUMENT_ID}"]
      }
    }
  ]
}
JSON

그런 다음 POST /v3/sandbox/tasks/{taskId}/review로 현재 제출을 승인하거나 거부하세요:

Review submission

curl --request POST \
  "${API_BASE}/v3/sandbox/tasks/${TASK_ID}/review" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"outcome":"accepted"}'

POST /v3/sandbox/tasks로 생성한 태스크와 Swipelux가 수집하는 케이퍼빌리티 접수 태스크는 검토할 수 있어요. Operations 또는 다른 워크플로가 소유한 태스크를 검토하면 409 task_not_sandbox_reviewable이 반환돼요. 해당 태스크는 태스크 엔드포인트를 통해 계속 조회할 수 있으며 소유자의 검토를 기다려요. 404 task_not_found는 태스크 ID를 알 수 없거나 다른 가맹점에 속한다는 의미예요. 프로덕션 태스크 완료 패턴은 케이퍼빌리티와 태스크를 참고하세요.

샌드박스 지갑 충전

POST /v3/sandbox/accounts/{accountId}/topup로 발급 지갑에 크레딧을 적립하세요:

Top up issued wallet

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

시뮬레이션된 자금 조달 전송을 확인하려면 반환된 data.id를 TRANSFER_ID로 저장하세요. topup id는 전송 id입니다. GET /v3/transfers/{transferId}로 조회하거나 GET /v3/transfers로 나열하여 인바운드 입금 코드 경로를 샌드박스 topup으로 시험하세요. 전송 프로젝션은 origin: "inbound_deposit", method: "stablecoin_transfers", direction: "stablecoin_move"가 설정된 완료된 인바운드 스테이블코인 입금이며, 이에 대응하는 accountId, origin, method, direction 목록 필터로 반환됩니다.

전송 완료 또는 실패

POST /v3/sandbox/transfers/{transferId}/state로 결과를 설정하세요:

완료
실패

curl --request POST \
  "${API_BASE}/v3/sandbox/transfers/${TRANSFER_ID}/state" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"state":"completed"}'

curl --request POST \
  "${API_BASE}/v3/sandbox/transfers/${TRANSFER_ID}/state" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "state": "failed",
  "stateDetail": {
    "code": "sandbox_review",
    "message": "Sandbox transfer failed."
  }
}
JSON

다음으로 샌드박스에서 페이인, 페이아웃 또는 발급 은행 계좌 흐름을 실행하세요.

시작하기

고객 온보딩

자금 흐름 구축

출시

샌드박스 테스트

케이퍼빌리티 준비 상태 테스트

열린 태스크 테스트

샌드박스 지갑 충전

전송 완료 또는 실패

​케이퍼빌리티 준비 상태 테스트

​열린 태스크 테스트

​샌드박스 지갑 충전

​전송 완료 또는 실패

케이퍼빌리티 준비 상태 테스트

열린 태스크 테스트

샌드박스 지갑 충전

전송 완료 또는 실패