고객 - Swipelux

페이인, 페이아웃 또는 발급 은행 계좌를 구축하기 전에 고객을 생성하세요. 케이퍼빌리티, 계좌, 전송은 그 고객으로 범위가 지정돼요. externalId를 시스템 내 해당 레코드로의 안정적인 매핑으로 사용하세요.

Environment variables

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

개인 고객

개인은 type만 필요해요. 이미 알고 있는 프로필 필드를 포함하고, 현재 케이퍼빌리티나 태스크가 필요로 할 때만 추가하세요. POST /v3/customers로 고객을 생성하세요:

Create individual customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-user-123" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "individual",
  "externalId": "user_123",
  "individual": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

반환된 data.id를 CUSTOMER_ID로 저장하세요. 정책 컨텍스트는 개인 온보딩을 참고하세요.

기업 고객

기업은 business.legalName이 필요해요. 동일한 동작으로 기업을 생성하세요:

Create business customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: customer-company-456" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "business",
  "externalId": "company_456",
  "business": {
    "legalName": "Acme Payments SAS"
  }
}
JSON

반환된 data.id를 CUSTOMER_ID로 저장하세요. 정책과 문서 컨텍스트는 기업 온보딩을 참고하세요. 이사, 소유자, 기타 기업 참여자가 알려지거나 요청되면 추가하세요. 이 예시는 POST /v3/customers/{customerId}/related-parties로 이사를 생성해요:

Add related party

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/related-parties" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: related-party-director-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "partyType": "person",
  "roles": ["director"],
  "title": "Chief executive officer",
  "person": {
    "firstName": "Amina",
    "lastName": "Diallo",
    "residenceCountry": "FR"
  }
}
JSON

반환된 data.id를 RELATED_PARTY_ID로 저장하세요. 고객을 내보내야 한다면 POST /v3/customers/{customerId}/export를 사용하고 요청 스키마를 따르세요. json_basic_data 형식은 현재 공개 v3 고객 리소스를 JSON 첨부 파일로 반환해요. 각 호출은 현재 데이터를 다시 계산하며, 문서와 문서 메타데이터는 제외해요. 이식성 토큰(portability-token) 형식의 경우, Swipelux customerId가 아니라 수신 KYC 프로젝트의 클라이언트 ID를 forClientId로 보내세요. 반환된 data.token을 data.expiresAt 이전에 사용하세요. 동일한 Idempotency-Key와 본문을 재사용하면 그 토큰 결과가 재생돼요. 다른 토큰을 발급하려면 새 키를 사용하세요.

케이퍼빌리티에서 준비 상태 확인

고객은 API 내에서 검증이나 준비 상태를 별도로 갖지 않아요. 현재 프로필 데이터를 위해 GET /v3/customers/{customerId}로 고객을 조회한 뒤, 케이퍼빌리티와 그 openTaskIds를 사용해 고객이 다음에 무엇을 할 수 있는지 결정하세요.

Get customer

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

미제출 서류가 있는 고객 찾기

페이지에서 어떤 고객이 아직 필수 서류를 제출해야 하는지 확인하려면 GET /v3/customers에 include=documentRequirements를 전달하세요. include=capabilities,documentRequirements처럼 케이퍼빌리티 요약과 함께 사용할 수 있어요. documentRequirements 확장을 사용하려면 API 키에 accounts:read가 필요해요. 그러면 각 고객 요약에 documentRequirements 객체가 포함돼요.

Document requirement summary

{
  "documentRequirements": {
    "required": true,
    "count": 2
  }
}

count는 action_required 상태인 태스크에 있는 action_required 상태의 필수 서류 요구 사항 수예요. 계좌 전체 태스크를 포함한 모든 태스크 범위를 포괄하며, 케이퍼빌리티 준비 상태와 관계없어요.
count가 0보다 크면 required는 true예요.
대안 묶음은 한 번만 집계되며, 모든 대안이 서류를 요구하는 경우에만 집계돼요.

이 요약은 보수적이에요. 선택 서류, 조건부 필수 서류, 서류 경로와 비서류 경로가 섞인 대안은 제외돼요. 고객이 호스팅 인증으로 완료할 수 있는 요구 사항도 제외돼요. 따라서 required: false가 적용되는 서류 태스크가 없다는 증거는 아니에요. 고객 우선순위를 정하는 데 사용하고, 수집할 항목의 정식 목록은 고객의 태스크를 조회해 확인하세요. 확장을 사용하지 않으면 응답에 documentRequirements가 포함되지 않아요. 다음으로, 케이퍼빌리티와 태스크로 넘어가 필요한 제품 결과를 발견하고 활성화하세요.

시작하기

고객 온보딩

자금 흐름 구축

출시

고객

개인 고객

기업 고객

케이퍼빌리티에서 준비 상태 확인

미제출 서류가 있는 고객 찾기

​개인 고객

​기업 고객

​기업 관계자 추가

​케이퍼빌리티에서 준비 상태 확인

​미제출 서류가 있는 고객 찾기

개인 고객

기업 고객

기업 관계자 추가

케이퍼빌리티에서 준비 상태 확인

미제출 서류가 있는 고객 찾기