케이퍼빌리티와 태스크

케이퍼빌리티는 고객이 특정 결과, 결제 방법, 방향을 사용할 수 있는지 알려줘요. 열린 태스크는 그 케이퍼빌리티나 관련 리소스가 진행되기 전에 무엇이 이뤄져야 하는지 알려줘요.

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

지원되는 케이퍼빌리티 발견

GET /v3/customers/{customerId}/capabilities/supported로 고객의 현재 옵션을 조회하세요:

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

의도한 directions, method, accountType과 일치하는 응답 항목을 선택하세요. availability가 available 또는 beta이고 eligibility.eligible이 true일 때만 진행하세요. institutions가 반환되면 그 응답의 ID만 선택하세요. 선택한 data[].id를 CAPABILITY_ID로 저장하세요. 다른 고객이나 환경의 케이퍼빌리티 ID를 절대 복사하지 마세요.

풀 계좌 대 명명 계좌 유형

은행 케이퍼빌리티는 두 가지 변형으로 제공되며, accountType 필드와 케이퍼빌리티 ID 접미사로 인코딩돼요 (예: ach_pooled, wire_named):

pooled: 공유 Swipelux 은행 계좌예요. 각 페이인은 자금을 라우팅하기 위해 고유 참조를 사용해요. 일회성 전송에는 이것을 선택하세요.
named: 고객 전용 은행 정보예요(가상 IBAN, 전용 ACH 계좌). 재사용 가능하며 어떤 지불자와도 공유할 수 있어요. 발급 은행 계좌에 필수예요.

기본값은 pooled이에요. 고객이 재사용 가능한 은행 정보가 필요할 때만 named를 사용하세요. 사용 가능한 변형은 supported 응답을 확인하세요.

케이퍼빌리티 요청

POST /v3/customers/{customerId}/capabilities/{capabilityId}로 선택한 옵션을 요청하세요:

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

명시적인 institutions 배열은 지원되는 케이퍼빌리티 응답이 반환한 ID 중에서 선택해야 할 때만 사용하세요. data.status를 CAPABILITY_STATUS, data.openTaskIds를 OPEN_TASK_IDS, 각 data.applications[].id를 APPLICATION_IDS에 저장하세요.

현재 태스크 완료

GET /v3/customers/{customerId}/tasks로 태스크를 나열하고, OPEN_TASK_IDS에서 ID를 선택한 뒤, GET /v3/customers/{customerId}/tasks/{taskId}로 각 현재 태스크를 조회하세요:

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

최신 data.revision과 data.requirements를 사용하세요. 둘 중 하나가 변경되었을 수 있다면 제출 직전에 태스크를 다시 조회하세요. 모든 열린 작업에는 dueAt 타임스탬프가 포함됩니다. Swipelux가 명시적인 기한 없이 작업을 생성하면 dueAt은 기본적으로 작업의 createdAt으로부터 정확히 31일 후로 설정됩니다. dueAt은 참고용으로만 취급하세요. API를 통해 설정할 수 없으며 자동 수명 주기 전환을 트리거하지 않습니다. 자동 전환은 별도로 설정된 deadline 필드가 있는 경우에만 발생합니다.

호스팅된 작업

태스크 상세 응답에서 verificationSessions와 tosSessions의 각 항목은 action 객체를 포함해요. 태스크 목록 응답에는 이러한 작업 링크가 포함되지 않아요. 각 세션의 id를 저장하고 고객을 안내하기 전에 action.kind를 확인하세요. 세션의 status만으로 링크 사용 가능 여부를 추론하지 마세요.

action.kind: "available"은 action.url과 action.expiresAt을 포함해요(현재는 항상 null이에요). action.url을 저장하고 고객을 해당 URL로 안내한 다음 태스크를 다시 조회하세요. 세션 수준의 url과 expiresAt 필드는 같은 값을 포함해요.
action.kind: "unavailable"은 링크를 제시하지 않아야 한다는 뜻이에요. 세션 수준의 url과 expiresAt 필드는 없어요. 세션의 status만으로 어떤 작업 종류가 반환될지는 결정되지 않아요.

{
  "data": {
    "verificationSessions": [
      {
        "id": "vfy_000000000000000003",
        "key": "identity_verification",
        "type": "identity_verification",
        "status": "action_required",
        "action": {
          "kind": "available",
          "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
          "expiresAt": null
        },
        "url": "https://platform.swipelux.com/kyc/redirect/cus_000000000000000001/tsk_000000000000000002/vfy_000000000000000003",
        "expiresAt": null
      }
    ],
    "tosSessions": [
      {
        "id": "vfy_000000000000000004",
        "key": "terms_of_service",
        "type": "terms_of_service",
        "status": "completed",
        "action": { "kind": "unavailable" }
      }
    ]
  }
}

이것들은 태스크 범위 작업이며, 별도의 고객 검증 라이프사이클이 아니에요.

문서 업로드

요건이 문서를 요청하면 POST /v3/customers/{customerId}/documents로 업로드하세요:

export DOCUMENT_PATH='/absolute/path/to/requested-document.pdf'

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/documents" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-document-001" \
  --form "file=@${DOCUMENT_PATH}"

이를 참조하는 답변을 제출하기 전에 반환된 data.id를 DOCUMENT_ID로 저장하세요.

API 답변

현재 리비전에 대한 완전한 답변 세트 하나를 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_API_KEY}" \
  --header "Idempotency-Key: task-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "taskRevision": 3,
  "answers": [
    {
      "requirementId": "req_from_current_task",
      "answer": {
        "type": "text",
        "value": "Current answer"
      }
    }
  ]
}
JSON

모든 요건 ID와 답변 유형은 최신 태스크에서 가져오세요. API가 태스크가 변경되었다고 알리면 다시 조회하고 새 리비전에서 제출을 재구성하세요.

기업의 실질적 소유자 전제 조건

실질적 소유자 증거가 필요한 기업 케이퍼빌리티 요청은 고객에게 아직 자격을 갖춘 소유자가 없어도 성공해요. 케이퍼빌리티는 statusReason.code: tasks_due와 함께 restricted로 생성되고, 기업 인테이크 태스크가 소유권 구조를 포함해 누락된 소유권 사실을 요청해요. 같은 태스크는 요청에 qualification: "beneficial_owner"가 포함된 resource_reference 요건을 담고 있어요:

{
  "type": "resource_reference",
  "prompt": "Add or select a qualifying beneficial owner.",
  "required": true,
  "resourceType": "related_party",
  "qualification": "beneficial_owner"
}

관계자는 같은 고객의 활성 person 당사자이면서 ownership.declared: true이거나 제공된 소유권 비율이 25 이상일 때 자격을 갖춰요. 이 요건은 현재 관계자 명단에서 도출되므로 일반적으로 직접 답변하지 않아요:

자격을 갖춘 관계자를 생성하거나 업데이트하면 같은 재평가에서 요건이 충족되고, 그 소유자 자신의 프로필과 문서 작업이 열려요. 기업 관계자 추가를 참고하세요.
relatedPartyId를 담은 resource_reference 답변으로 자격을 갖춘 당사자를 명시적으로 참조할 수도 있어요.
요건은 충족된 후에도 현재 태스크에 계속 나열돼요. 다른 열린 의무가 남아 있지 않으면 태스크는 satisfied가 돼요.
마지막 자격을 갖춘 당사자를 보관 처리하거나 자격을 갖추게 한 사실을 제거하면, 태스크가 satisfied가 된 후라도 요건이 다시 열려요.

케이퍼빌리티가 준비되면 계속 진행

GET /v3/customers/{customerId}/capabilities/{capabilityId}로 케이퍼빌리티를 다시 조회하세요:

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

저장된 상태와 태스크 ID를 최신 응답으로 교체하세요. 현재 케이퍼빌리티 상태가 생성하려는 계좌, 견적, 전송을 허용할 때만 계속 진행하세요. 다음으로 일반적인 흐름에서 일치하는 여정을 선택하세요.

시작하기

고객 온보딩

자금 흐름 구축

출시

케이퍼빌리티와 태스크

지원되는 케이퍼빌리티 발견

풀 계좌 대 명명 계좌 유형

케이퍼빌리티 요청

현재 태스크 완료

호스팅된 작업

문서 업로드

API 답변

기업의 실질적 소유자 전제 조건

케이퍼빌리티가 준비되면 계속 진행

​지원되는 케이퍼빌리티 발견

​풀 계좌 대 명명 계좌 유형

​케이퍼빌리티 요청

​현재 태스크 완료

​호스팅된 작업

​문서 업로드

​API 답변

​기업의 실질적 소유자 전제 조건

​케이퍼빌리티가 준비되면 계속 진행

지원되는 케이퍼빌리티 발견

풀 계좌 대 명명 계좌 유형

케이퍼빌리티 요청

현재 태스크 완료

호스팅된 작업

문서 업로드

API 답변

기업의 실질적 소유자 전제 조건

케이퍼빌리티가 준비되면 계속 진행