메인 콘텐츠로 건너뛰기

신용카드 Onboarding

MarkdownChatGPTClaude

시작하기 전에​

API 요청은 액세스 토큰을 사용하여 인증됩니다. 유효한 액세스 토큰을 포함하지 않는 요청은 오류를 반환합니다. 인증에서 자세히 알아보세요.

기본 URL
  • UAT: https://transactions.transactional.uat.unico.app/api/public/v1
  • 프로덕션: https://transactions.transactional.unico.app/api/public/v1
중요

신용카드 Onboarding은 최종 사용자에게 셀피를 요청하여 전체 등록을 완료하는 방식 또는 Unico IDCloud 플랫폼의 다른 제품에서 실행된 프로세스의 생체 인식 캡처를 재사용하는 방식으로 수행할 수 있습니다.

  • 다른 IDCloud 제품에서 생성된 프로세스를 재사용하려면, additionalInfo.processID에 참조 프로세스 ID를 제공하세요;
  • 사용되는 참조 프로세스는 완료된 지 1시간 이내여야 합니다.

신용카드 검증​

POST /walletid/transaction — 신용카드를 검증합니다.

헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
본문
{
  "identity": { "key": "cpf", "value": "12345678900" },
  "orderNumber": "onboarding-98765",
  "company": "company-id",
  "redirectUrl": "https://yourapp.com/wallet/return",
  "card": {
    "binDigits": "12345678",
    "lastDigits": "1234",
    "expirationDate": "12/2028",
    "name": "John Doe"
  },
  "value": 5000.00,
  "additionalInfo": {
    "externalUserID": "YOUR_EXTERNAL_USER_ID"
  }
}
필드타입필수설명
identityobject예사용자 신원 정보입니다.
identity.keystring예사용자 식별 키의 유형입니다.
identity.valuestring예사용자 식별 키의 값입니다.
orderNumberstring예온보딩과 연결된 번호입니다. 포털에서 색인으로 사용되며 귀사 시스템과 비대면 카드 검증 간의 외래 키 역할을 합니다.
companystring예Unico가 제공하는, 거래를 담당하는 회사의 ID입니다.
redirectUrlstring아니요거래 완료 후 사용자를 리디렉션할 URL입니다(웹의 경우 HTTPS URL, 네이티브 모바일 앱의 경우 Schema URL).
cardobject예거래에 사용된 카드 정보입니다.
card.binDigitsstring예카드의 처음 8자리입니다.
card.lastDigitsstring예카드의 마지막 4자리입니다.
card.expirationDatestring아니요카드 만료일입니다.
card.namestring예카드 소유자의 이름입니다 — 인코딩 문제나 승인 문제를 피하기 위해 정확한지 확인하세요.
valuenumber아니요최대 보증 금액입니다.
additionalInfoobject아니요Unico IDCloud 플랫폼의 다른 제품에서 생체 인식 캡처를 재사용하려면 processID와 함께, 이 거래에 대해 사일런트 검증을 활성화하려면 externalUserID와 함께 이 객체를 전송하세요.
additionalInfo.processIDstring아니요IDCloud 플랫폼의 참조 프로세스 ID입니다.
additionalInfo.externalUserIDstring아니요디바이스 메타데이터를 수집할 때 SDK의 externalUserId를 통해 구성한 것과 동일한 식별자입니다. 사일런트 검증을 트리거하려는 경우에만 필요합니다 — 이것이 없으면 거래는 정상적으로 생성되지만 항상 표준 시각적 흐름을 따릅니다.
위험

orderNumber 필드에는 전자상거래 시스템에서 해당 구매의 고유한 주문 번호를 입력해야 합니다 — 별도의 트랜잭션 ID를 사용하는 것은 올바르지 않으며, 값을 재사용하면 replicated transaction 오류가 발생할 수 있습니다.

200 OK
{
  "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
  "status": "processing",
  "link": "https://developers/regional-solutions/card-not-present-verification.unico.app/t/6ab1771e-dfab-4e47-8316-2452268e5481",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
필드설명
id생성된 거래의 ID입니다.
status현재 거래 상태입니다.
link거래와 관련된 링크입니다. additionalInfo.processID가 제공되지 않은 경우에만 반환됩니다.
token비대면 카드 검증 웹 SDK를 초기화하기 위한 서명된 토큰입니다. additionalInfo.processID가 제공되지 않은 경우에만 반환됩니다.
참고

additionalInfo.externalUserID가 전송되고 거래가 사일런트하게 승인된 경우, 응답에서도 캡처 링크가 생략됩니다:

{
    "id": "6ab1771e-dfab-4e47-8316-2452268e5481",
    "status": "approved"
}

SDK 설정 및 타이밍 요구 사항을 포함한 전체 흐름은 사일런트 검증을 참조하세요.

검증 상태 확인​

GET /walletid/transactions/{transaction_id} — 특정 거래의 현재 상태를 확인합니다.

헤더
헤더값
AuthorizationBearer {token} — 유효한 액세스 토큰입니다.
200 OK
{
  "status": "processing",
  "hasIdentityChanged": false
}
필드설명
status거래의 현재 상태입니다.
hasIdentityChanged선택 사항입니다. 거래에서 신원 교체가 발생했는지 여부입니다.

가능한 모든 상태는 열거형을 참조하세요. 성능을 최적화하려면 이 엔드포인트를 폴링하는 대신 웹훅을 구현하세요.

오류 응답에 대해서는 오류 — 신용카드 Onboarding을 참조하세요.

마지막 업데이트 에