안전한 결제 확인

1. 소개

이 절과 하위 절은 비규범적입니다.

이 규격은 웹에서 결제 흐름 중 강력한 인증 방법 사용을 가능하게 하는 API를 정의합니다. 이는 [webauthn-3] 와 동일한 인증 장점과 사용자 프라이버시 초점을 제공하는 것을 목표로 하며, 결제 처리를 위한 요구사항을 충족하도록 개선되었습니다.

[webauthn-3] 와 유사하게, 이 규격은 사용자와 관련된 두 가지 프로세스를 정의합니다. 첫 번째는 § 3 등록 (이전 "등록(enrollment)"), 여기서 사용자와 릴라잉 파티 사이의 관계가 생성됩니다. 두 번째는 § 4 인증 - 안전한 결제 확인 결제 방식에서 사용자가 릴라잉 파티 (중개 결제 서비스 제공자를 통해 가능)로부터 챌린지에 응답하여 특정 결제에 동의합니다.

이 규격의 목표 중 하나는 결제 과정 중 인증 마찰을 줄이는 것이며, 그 한 요소는 사용자가 한 번 등록으로 가능한 한 많은 인증을 수행할 수 있도록 하는 것입니다. 즉, 릴라잉 파티의 동의 하에, 이상적으로 사용자는 "한 번 등록"으로 최초로 등록한 가맹점 오리진뿐만 아니라 모든 가맹점 오리진(및 결제 서비스 제공자를 통해)에서 인증할 수 있어야 합니다.

이를 위해, 안전한 결제 확인의 중요한 기능은 상점(또는 다른 단체)이 릴라잉 파티를 대신하여 인증 절차를 시작할 수 있다는 것입니다. 릴라잉 파티는 자격 증명 생성 시, 해당 동작을 허용하도록 명시적으로 동의해야 합니다.

기능적으로, 이 규격은 PaymentRequest API를 위한 새로운 결제 방식을 정의하고, 결제 특화 데이터 구조, 장치 바인딩 및 결제 맥락에서 API 호출을 허용하기 위한 가정 완화를 위해 WebAuthn 확장을 추가하여 [webauthn-3] 를 확장합니다.

1.1. 사용 사례

[webauthn-3] 가 웹을 위한 일반 인증 기능을 제공하지만, 아래와 같은 사용 사례를 통해 이 규격에서 정의된 결제 특화 확장 기능의 가치를 설명합니다.

온라인 거래에 대해 암호 기반 인증의 일반적 사용 사례는 이미 충분히 확립되어 있다고 가정합니다.

1.1.1. 거래 확인의 암호화 증거

많은 온라인 결제 시스템에서 결제 수단을 발급하는 기관(예: 은행)은 인증을 통해 사기 방지하려고 합니다. [webauthn-3] 및 이 규격을 사용하면 인증자를 통해 상점의 오리진, 거래 금액 및 통화 등 결제 특화 정보를 암호화 서명할 수 있습니다. 은행은 릴라잉 파티로서, 결제 승인 결정 시 해당 결제 특화 정보의 서명을 검증할 수 있습니다.

은행이 일반 [webauthn-3] 를 사용할 경우, 검증할 결제 특화 정보는 WebAuthn의 challenge 에 저장되어야 합니다. 이는 다음과 같은 문제를 야기합니다:

challenge 필드의 오용(이 필드는 재사용 공격 방지 용도입니다).
명세가 없어 각 은행이 결제 특화 정보를 챌린지에 어떠한 형식과 인코딩으로 담을지 직접 설계해야 하므로, 배포가 복잡해지고 파편화가 증가합니다.
규제에 따라 사용자에게 결제 특화 정보가 표시되고 사용자 동의 증거가 요구될 수 있습니다. 일반 [webauthn-3] 에서는 이러한 정보 표시를 위한 UX가 명세되어 있지 않고, challenge 필드의 정보에 대한 UX가 제공되지 않습니다.

이러한 제한을 해소하기 위해 다음과 같은 안전한 결제 확인(SPC) 행동 양식이 도입됩니다:

challenge 필드는 일반 [webauthn-3] 처럼 오직 재사용 공격 방지 용도로만 사용됩니다.
SPC는 결제 특화 정보의 형식을 명세합니다. 이를 통해 범용 검증 코드와 테스트 스위트 개발이 가능합니다.
SPC는 사용자 에이전트가 결제 특화 정보를 사용자에게 악의적인 웹사이트(또는 신뢰된 웹사이트 내 악의적으로 삽입된 자바스크립트 코드)가 우회할 수 없는 방식으로 표시했음을 보장합니다.
- 결제 특화 정보는 CollectedClientData 딕셔너리에 포함되며, 자바스크립트에서 변조할 수 없습니다.
참고: 결제 생태계에서 은행 등 이해당사자들은 오늘날 브라우저의 TLS, iframe 등 Web 기능을 이용해 결제에 충분한 신뢰를 두고 있습니다. 현재 명세는 웹 결제의 보안성 및 사용성을 향상시키려 설계되었습니다.

1.1.2. 가맹점의 인증 제어

가맹점들은 결제 진행 중 사용자 이탈을 방지하고 인증 마찰을 줄이고자 합니다. 릴라잉 파티 (예: 은행)가 [webauthn-3] 로 사용자를 인증하려는 경우, 보통 iframe을 통해 인증합니다. 하지만 가맹점들은 인증 사용자 경험을 직접 관리하면서도 릴라잉 파티 가 인증 결과를 검증할 수 있기를 원합니다.

이러한 제한을 해소하기 위해 다음과 같은 안전한 결제 확인(SPC) 행동 양식이 도입됩니다:

SPC를 사용하면 릴라잉 파티 이외의 다른 주체가 릴라잉 파티를 대신하여 인증 자격증명을 사용할 수 있습니다. 릴라잉 파티는 인증 결과를 검증할 수 있습니다.

이 기능의 추가적 장점은 릴라잉 파티가 인증 프론트엔드 경험을 직접 구축하지 않아도 된다는 것입니다. 대신 결제 서비스 제공자가 상점들을 위해 이를 구축할 가능성이 높아집니다.

참고: 인증 사용자 경험을 직접 제공하고 싶은 릴라잉 파티는 SPC를 iframe에서 사용할 수 있습니다.

1.1.3. 장치 바인딩의 암호화 증거

결제 업계에서는 장치 소유 신호가 2차 요소로 중요한 역할을 합니다. WebAuthn은 하나의 자격증명이 여러 장치에서 동기화될 수 있는 패스키를 지원합니다(Web Authentication § 1.2.1 다중 장치 자격증명 사용 소비자). 동기화는 로그인 사용 사례에서 사용자 경험을 개선하지만, 일부 규제 환경에서는 동기화된 패스키만으로는 장치 소유 요건을 충족하지 못한다는 우려가 있습니다.

이런 우려를 해소하기 위해 사용자 에이전트가 생성하는 보조 공개/개인 키 쌍의 비밀키가 특정 장치에서만 존재(및 사용)하도록 만듭니다. 이러한 키와 SPC 내 사용을 브라우저 바인드 키 라고 합니다.

1.2. API 사용 예시 시나리오

이 절에서는 안전한 결제 확인을 위한 시나리오와 해당 API 사용 예시 코드를 설명합니다. 이것은 예시 흐름일 뿐이며 API 사용 범위를 제한하지 않습니다.

1.2.1. 결제 시 등록

이 흐름은 사용자가 어떤 상점에서 결제하는 과정 중 발급 은행이 새로운 자격증명을 생성해 저장하는 첫 등록 흐름입니다.

사용자가 merchant.example에 접속하여 상품을 선택하고 결제 과정을 진행합니다. 결제 수단 정보를 입력한 뒤 결제를 희망(예: "Pay" 버튼 누름)합니다.
상점은 발급 은행과 밴드 밖(out-of-band)(예: 다른 프로토콜 사용)으로 통신합니다. 발급 은행은 사용자 확인을 요청하고, 상점이 iframe에서 열 수 있도록 은행 제어의 URL을 제공합니다.
상점은 bank.example에 iframe을 열고 allow 속성을 "publickey-credentials-create"로 설정합니다.
iframe 내에서 발급 은행은 기존 방식(예: SMS OTP 등)으로 사용자를 확인합니다. 확인 후, 은행은 향후 결제에 SPC 인증 등록을 권유합니다.
사용자가 동의(예: 은행 UX의 "Register" 버튼 클릭)하면, 은행은 iframe 내에서 코드를 실행합니다(예시 아래 참고).
사용자는 WebAuthn 등록 과정을 거칩니다. 새 자격증명이 생성되고, 발급 은행 서버 DB에 사용자 및 결제 수단과 연계해 저장됩니다.
확인이 완료되면 은행 iframe이 닫히고, 상점은 사용자의 결제 과정을 끝마칩니다.

이 방식으로 사용자를 등록하는 샘플 코드는 다음과 같습니다:

if (!window.PublicKeyCredential) { /* 클라이언트가 지원 불가. 에러 처리 필요. */ }

const publicKey = {
  // 챌린지는 은행 서버가 생성 후 iframe으로 전달해야 합니다.
  challenge: new Uint8Array([21,31,105 /* 서버에서 생성된 무작위 바이트 29개 */]),

  // 릴라잉 파티:
  rp: {
    name: "Fancy Bank",
  },

  // 사용자:
  user: {
    // WebAuthn 일부. SPC에서는 필수 아님
    // 그러나 은행 서버에서 이 정보를 사용자 식별 목적으로 활용 가능
    // 동일 사용자에 대해 불일치 값 사용 시, 여러 자격증명 생성으로 UX 마찰(선택 화면)이 생길 수 있음
    id: Uint8Array.from(window.atob("MIIBkzCCATigAwIBAjCCAZMwggE4oAMCAQIwggGTMII="), c=>c.charCodeAt(0)),
    name: "jane.doe@email.example",
    displayName: "Jane Doe",
  },

  // 이 예시에서 릴라잉 파티는 ES256 또는 RS256 자격증명 둘 다 허용하지만 ES256을 선호
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7 // "ES256"
    },
    {
      type: "public-key",
      alg: -257 // "RS256"
    }
  ],

  authenticatorSelection: {
    userVerification: "required",
    residentKey: "required",
    authenticatorAttachment: "platform",
  },

  timeout: 360000,  // 6분

  // SPC 자격증명임을 나타냅니다. 현재 필수로써
  // 브라우저가 이 자격증명이 SPC와 관련됨을 인지할 수 있습니다.
  // 교차 오리진 iframe 내 자격증명 생성도 이로써 가능, 본 예시에서 필수
  //
  // 향후 명세 버전에서는 이 확장 필요성을 제거할 수 있음.
  extensions: {
    "payment": {
      isPayment: true,
      // 허용 알고리즘 목록(선택 사항). 비어있거나 미포함시 pubKeyCredParams(ES256, RS256)가 기본,
      // 여기선 ES256, RS256 허용하며 RS256이 선호됨
      browserBoundPubKeyCredParams: [
        {
          type: "public-key",
          alg: -257 // "RS256"
        },
        {
          type: "public-key",
          alg: -7 // "ES256"
        }
      ]
    }
  }
};

// 참고: 아래 호출 시 인증기에서 UI를 표시합니다.
navigator.credentials.create({ publicKey })
  .then(function (newCredentialInfo) {
    // 신규 자격증명 정보를 서버에 검증 및 등록 용도로 전송
  }).catch(function (err) {
    // 인증기가 없거나 사용자가 동의 거부. 적절히 처리 필요.
  });

1.2.2. 가맹점 사이트에서 인증

이미 등록된 자격증명을 가진 사용자가 거래를 수행하고, 발급 은행과 가맹점이 안전한 결제 확인(SPC)를 사용하고자 할 때의 흐름입니다.

사용자가 merchant.example에 방문하여 상품을 선택한 뒤 결제 과정을 진행합니다. 결제 수단 정보를 입력하고, 결제 의사를 표시합니다(예: "결제" 버튼 클릭).
가맹점은 결제 수단의 발급 은행과 밴드 밖(out-of-band)으로 통신합니다(예: 다른 프로토콜 사용). 발급 은행은 사용자 확인을 요청하며, 동시에 API 사용에 필요한 정보를 제공하여 SPC 사용을 승인했음을 상점에 알립니다. 이 정보에는 챌린지와 해당 사용자 및 결제 수단과 연계된 자격증명 ID 목록이 포함됩니다.
가맹점은 아래 예시 코드를 실행합니다.
사용자는 SPC UX에 표시된 결제 특화 정보에 동의하고, 이후 WebAuthn 인증 절차를 수행합니다. 서명된 암호문(브라우저 바인드 키 출력 포함)은 가맹점에 반환됩니다(AuthenticationExtensionsPaymentOutputs 포함).
가맹점은 서명된 암호문을 밴드 밖으로 발급 은행에 전달합니다. 발급 은행은 암호문을 검증하여 사용자의 유효성과 표시된 결제 특화 정보, 사용자의 거래 동의 여부를 확인합니다. 발급 은행이 거래를 승인하고, 가맹점은 결제 과정을 완료합니다. 발급 은행은 브라우저 바인드 키의 공개키, browserBoundPublicKey를 저장합니다.

사용자 인증을 위한 샘플 코드는 아래와 같습니다. 이 예시 코드는 promise 처리를 쉽게하기 위해 await/async 접근을 가정합니다.

/* securePaymentConfirmationAvailability는 브라우저가 SPC를 지원하는지 표시하며, */
/* 사용자가 이 기기에서 바로 사용할 수 있는 자격증명을 가진다는 뜻은 아닙니다. */
const spcAvailable =
  PaymentRequest &&
  PaymentRequest.securePaymentConfirmationAvailability &&
  (await PaymentRequest.securePaymentConfirmationAvailability()) === 'available';
if (!spcAvailable) {
  /* 브라우저가 SPC를 지원하지 않을 경우, 기존 방식으로 결제 흐름을 대체해야 합니다. */
}

const request = new PaymentRequest([{
  supportedMethods: "secure-payment-confirmation",
  data: {
    // 은행에서 받은 자격증명 ID 목록
    credentialIds,

    rpId: "fancybank.example",

    // 챌린지 또한 은행에서 제공됨
    challenge: new Uint8Array([21,31,105 /* 은행에서 생성된 임의 바이트 29개 */]),

    instrument: {
      displayName: "FancyBank Platinum Card",
      details: "****1234 | 01/29",
      icon: "https://fancybank.example/card-art.png",
    },

    payeeName: "Merchant Shop",
    payeeOrigin: "https://merchant.example",

    paymentEntitiesLogos: [
      {
        url: "https://fancybank.example/logo.png",
        label: "Fancy Bank",
      },
      {
        url: "https://securenetwork.example/logo.png",
        label: "Secure Network",
      },
    ],

    // 요청자의 로컬 환경 지정
    locale: ["en"],

    timeout: 360000,  // 6분

    // 허용 알고리즘 목록(선택 사항, 기본값 ES256/RS256). 
    // 이 예시에서는 ES256, RS256 모두 허용하며 ES256 우선. 
    // 브라우저 바인드 키가 이미 존재할 경우 새로 만들지 않으므로 목록은 키가 없을 때만 사용됨.
    browserBoundPubKeyCredParams: [
      {
        type: "public-key",
        alg: -7 // "ES256"
      },
      {
        type: "public-key",
        alg: -257 // "RS256"
      }
    ]
  }], {
    total: {
      label: "총액",
      amount: {
        currency: "USD",
        value: "5.00",
      },
    },
  });

try {
  const response = await request.show();
  await response.complete('success');

  // response.data는 PublicKeyCredential로, clientDataJSON에 거래 검증용 정보 포함(은행에서 사용).

  /* response.data를 발급 은행 검증 용도로 전송 */
} catch (err) {
  /* SPC를 사용할 수 없으면 기존 결제 흐름으로 대체해야 함 */
}

2. 용어

SPC 자격증명

이 규격에서 정의된 동작에 사용될 수 있는 WebAuthn 자격증명입니다.

이 규격은 릴라잉 파티가 SPC 자격증명을 다른 인증 흐름(예: 로그인)에 어떻게(혹은 하지 않고) 사용할지 제한하려는 목적이 아닙니다.

참고: 현 규격 버전에서는 릴라잉 파티가 자격증명이 1자 파티 또는 3자 파티 맥락에서 사용될 수 있도록 명확히 동의(opt-in)해야 함을 요구합니다. 장기적으로는 모든 WebAuthn 자격증명이 1자 파티 맥락(즉, 릴라잉 파티 도메인)에서 SPC에 사용할 수 있고, 3자 파티 사용만 opt-in이 필요하도록 발전하는 것이 목적입니다.

3자 파티 SPC 자격증명

SPC 자격증명 중 릴라잉 파티가 자격증명 생성 시 명확히 동의(opt-in)하여, 릴라잉 파티 이외의 주체가 Secure Payment Confirmation 인증에 이를 사용할 수 있도록 허용한 자격증명입니다.

SPC 자격증명이 3자 파티 허용 여부를 조용히 판별하는 단계

아직 정의되지 않은 프로세스이며, 사용자 에이전트가 릴라잉 파티 식별자와 자격증명 ID 만으로, 사용자 조작 없이 해당 ID의 자격증명이 3자 파티 SPC 자격증명인지 판별하는 단계입니다.

참고: WebAuthn 이슈 1667 참고.

현재 기기에서 자격증명 사용 가능 여부를 조용히 판별하는 단계

아직 정의되지 않은 프로세스이며, 사용자 에이전트가 릴라잉 파티 식별자와 자격증명 ID만으로, 사용자 조작 없이 해당 자격증명이 현 기기에서 사용 가능한지 판별하는 단계입니다(즉, WebAuthn Get 호출에 성공적으로 사용할 수 있는지 여부).

사용자 에이전트는 해당 자격증명이 사용할 수 있을 확률이 있어야만 거래 확인 UX를 사용자에게 조건부로 표시할 수 있습니다.

참고: 이 특성은 SPC 자격증명이 탐색가능이어야 구현 가능하므로, 본 규격에서 요구사항으로 코딩되어 있습니다.

참고: 이 특성은 WebAuthn Conditional UI Proposal에 요구되는 것과 매우 유사합니다. 둘 다 동일한 기반 API로 지원될 가능성이 높습니다.

브라우저 바인드 키

거래 상세 정보를 WebAuthn 자격증명과 추가로 서명하며, 사용자 에이전트가 특정 기기와 바인드하는 공개/개인 키 쌍입니다.

키 쌍

키 쌍은 구조체로, 공개키와 개인키로 구성되며, 구현 종속 타입입니다.

참고: 공개키와 개인키는 IANA COSE 알고리즘 레지스트리에서 참조하는 암호 알고리즘별로 사용되는 매개변수입니다 [IANA-COSE-ALGS-REG].

참고: 공개키는 등록 시 CollectedClientAdditionalPaymentRegistrationData.browserBoundPublicKey 와 결제 인증 시 CollectedClientAdditionalPaymentData.browserBoundPublicKey에 반환됩니다.

참고: 개인키는 BrowserBoundSignature.signature에 포함되는 암호 서명 생성에 사용됩니다. 사용자 에이전트는 개인키를 외부로 내보내지 않으며, 기기의 보안 요소에 저장할 수도 있습니다.

3. 등록

사용자를 안전한 결제 확인에 등록하려면, 릴라잉 파티가 navigator.credentials.create() 를 호출하고 payment WebAuthn 확장 을 지정해야 합니다.

테스트

참고: 이 규격에서는 브라우저가 Conditional UI 없이도 SPC 자격증명 ID를 캐시할 수 있도록 확장을 정의합니다. 향후 WebAuthn에 해당 기능이 추가된다면 SPC에서 확장 필요성을 제거할 수 있습니다. SPC 자격증명(확장 포함)은 본질적으로 완전한 WebAuthn 자격증명입니다.

참고: 등록 시, Web Authentication은 name 과 displayName 을 모두 요구하지만, user 멤버 정의에 따라, 구현에서는 이후 인증 절차에서 둘 중 어떤 것도 표시할 필요가 없습니다. 두 항목 중 2023년 10월 기준 name 이 더 꾸준히 표시되고 있습니다. 개발자들은 구현 변화를 모니터링해야 합니다.

4. 인증 - 안전한 결제 확인 결제 방식

안전한 결제 확인을 통해 결제를 인증하려면, 본 규격은 다음을 정의합니다:

결제 핸들러, 안전한 결제 확인 결제 핸들러, 결제 인증 요청을 처리합니다.
이 결제 핸들러의 표준화된 결제 방식 식별자, "secure-payment-confirmation"입니다.

안전한 결제 확인 결제 핸들러는 사용자와 거래를 확인한 후 인증 절차를 실행하여 사용자를 인증하고 인증 절차를 나타내는 서명된 blob을 생성합니다.

상위 수준에서, 안전한 결제 확인용 인증은 [webauthn-3]과 유사하지만 하나의 중요한 개념적 변화가 있습니다. 안전한 결제 확인은 제3자(예: 상점)가 릴라잉 파티를 대신해 인증 절차를 유발할 수 있도록 하며, 릴라잉 파티로부터 얻은 자격증명을 별도의 경로를 통해 전달할 수 있습니다. § 1.1.2 가맹점의 인증 제어 참고.

참고: 초기에 SPC 실험을 빠르게 지원하기 위해 이 API는 기존 Payment Request 및 Payment Handler API 구현 위에 설계되었습니다. 현재는 Payment Request와 독립적인 SPC 디자인을 탐색하기로 합의되었습니다. 구체적 일정은 없지만, SPC가 Payment Request 기반에서 분리될 것으로 예상합니다. 개발자에게는 기능 탐지, 호출, 기타 API 관련 요소가 개선될 것입니다.

4.1. [payment-method-id]에서 등록

표준화된 결제 방식 레지스트리에 다음을 추가하세요: [payment-method-id]:

"secure-payment-confirmation": 안전한 결제 확인 규격.

4.2. 결제 요청 생성자 수정

PaymentRequest 객체 생성자 단계에, 4.3 단계 뒤에 새 단계를 추가합니다:

결제 방식 처리: [하위 단계 1-3 생략]
1. seenPMIs에 "secure-payment-confirmation"이 포함돼 있고 seenPMIs의 크기가 1보다 크면 RangeError를 throw합니다.

4.3. 사용자 활성화 요구 조건 수정

PaymentRequest.show() 메서드 단계에서 2, 3단계를 다음과 같이 수정합니다:

관련 글로벌 객체에서 request 가 일시적 활성화(transient activation)가 아니면, 사용자 에이전트는 다음을 수행할 수 있습니다:
1. 거부된 promise를 "SecurityError" DOMException과 함께 반환.
그렇지 않으면, 사용자 활성화 소진을 관련 글로벌 객체에 대해 수행합니다.

참고: 사용자 에이전트가 사용자 활성화를 요구하지 않을 수 있으므로, 리디렉트 인증 흐름 등 활성화가 없는 상황도 지원합니다. 보안 고려는 § 11.4 사용자 활성화 요구 조건 미비 참고.

4.4. `SecurePaymentConfirmationRequest` 딕셔너리

dictionary SecurePaymentConfirmationRequest {
    required BufferSource challenge;
    required USVString rpId;
    required sequence<BufferSource> credentialIds;
    required PaymentCredentialInstrument instrument;
    unsigned long timeout;
    USVString payeeName;
    USVString payeeOrigin;
    sequence<PaymentEntityLogo> paymentEntitiesLogos;
    AuthenticationExtensionsClientInputs extensions;
    sequence<PublicKeyCredentialParameters> browserBoundPubKeyCredParams;
    sequence<USVString> locale;
    boolean showOptOut;
};

SecurePaymentConfirmationRequest 딕셔너리는 다음 멤버를 포함합니다:

challenge

릴라잉 파티가 서버에서 재사용 공격 방지용으로 생성한 난수 챌린지입니다.

rpId

자격증명의 릴라잉 파티 식별자입니다.

credentialIds

해당 결제 수단에 대한 자격증명 식별자 목록입니다.

instrument

등록 시 표시되는 결제 수단 이름과 아이콘 설명이며 거래 상세 정보와 함께 서명됩니다.

timeout

거래 상세 정보 서명 요청이 만료되기까지의 밀리초 수. 최대 1시간. 기본값 및 허용값 범위는 사용자 에이전트가 정의하며, Web Authentication은 추가 타임아웃 가이드를 제공합니다.

payeeName

이 SPC 호출의 수취인(예: 상점)의 표시 이름입니다. 선택사항이며, payeeOrigin과 함께, 또는 대신 제공할 수 있습니다.

payeeOrigin

이 SPC 호출의 수취인(예: 상점)의 origin입니다. 선택사항이며, payeeName과 함께, 또는 대신 제공할 수 있습니다.

paymentEntitiesLogos

결제를 중개하는 개체의 로고 선택 목록이며, 표시 우선순위가 높은 순서대로 나열됩니다. 사용자 에이전트가 일부 또는 전체 로고를 표시할 필요는 없으며, § 4.8 결제 가능 여부 확인 단계 참고.

참고: 이 규격은 로고의 표시 방법을 명확히 규정하지 않으며, 사용자 에이전트가 렌더링을 제어할 수 있도록 하고 다양한 조건을 고려해 정보를 적절히 표시할 수 있음. 리스트 내 로고 순서는 중요하며, 개발자가 새로운 순서를 실험해 원하는 결과를 얻을 수 있음.

extensions

지정된 자격증명에 사용해야 할 WebAuthn 확장입니다. 호출자가 결제 확장을 명시할 필요 없으며, 자동 추가됩니다.

browserBoundPubKeyCredParams

브라우저 바인드 키에 적용할 암호 알고리즘 유형을 제약하는 자격증명 허용 목록.

참고: 이 멤버는 브라우저 바인드 키가 새로 생성되어야 할 때만 사용됩니다.

locale

우선순위가 높은 순서대로 나열한 언어 태그 선택 목록입니다([BCP47] 참고). 이는 웹사이트의 지역(locale) 선호를 식별하며, 언어 우선순위 목록 [RFC4647] 형태입니다. 사용자 에이전트가 언어 협상(language negotiation) 및 지역 기반 포맷을 호출자와 함께 수행하는 데 사용 가능합니다.

showOptOut

거래 확인 UX에서 사용자가 거부할 기회를 받을지 여부입니다. 선택사항, 기본값은 false.

4.5. 결제 방식 추가 데이터 타입

이 결제 방식의 추가 데이터 타입은 SecurePaymentConfirmationRequest 입니다.

4.6. 안전한 결제 확인 사용 가능 여부 확인

PaymentRequest 에 정적 API가 추가되어 개발자가 안전한 결제 확인 사용 가능 여부를 간단히 확인할 수 있습니다. 이 메서드 securePaymentConfirmationAvailability()는 열거형(enum) 멤버를 반환하며, 안전한 결제 확인이 사용 가능 또는 불가능(내부 사유 설명 포함)함을 나타냅니다. 열거형 출력 사용은 개발자가 사용자 인증 옵션 안내 및 메시징에 도움됩니다.

enum SecurePaymentConfirmationAvailability {
  "available",
  "unavailable-unknown-reason",
  "unavailable-feature-not-enabled",
  "unavailable-no-permission-policy",
  "unavailable-no-user-verifying-platform-authenticator",
};

partial interface PaymentRequest {
    static Promise<SecurePaymentConfirmationAvailability> securePaymentConfirmationAvailability();
};

SecurePaymentConfirmationAvailability 열거형에는 다음 멤버가 포함됩니다:

available

사용자 에이전트가 현재 프레임에서 안전한 결제 확인 API를 사용할 수 있음으로 판단함을 나타냅니다.

참고: 이 결과는 특정 SPC 자격증명의 현재/향후 사용 가능 여부를 의미하지 않습니다.

unavailable-unknown-reason

호출 프레임에서 안전한 결제 확인 API를 사용할 수 없는 원인을 알 수 없음을 나타냅니다. 사용자 에이전트는 사용자 프라이버시 보호를 위해 항상 이 결과를 반환할 수 있습니다.

unavailable-feature-not-enabled

기능이 활성화되지 않아 호출 프레임에서 안전한 결제 확인 API를 사용할 수 없음을 나타냅니다.

unavailable-no-permission-policy

호출 프레임에서 "payment" 권한 정책이 없어 안전한 결제 확인 API를 사용할 수 없음을 나타냅니다.

unavailable-no-user-verifying-platform-authenticator

사용자 인증이 가능한 플랫폼 인증기가 없어 해당 프레임에서 안전한 결제 확인 API를 사용할 수 없음을 나타냅니다.

참고: isUserVerifyingPlatformAuthenticatorAvailable 호출로도 이 정보를 획득할 수 있으나, 개발자 편의상 본 API에도 포함시켰습니다.

securePaymentConfirmationAvailability() 메서드를 Document document에서 호출하면, 사용자 에이전트는 아래 단계를 수행합니다. 사용자 프라이버시 보호 또는 사용자 에이전트 특유의 사유로 단계 완료 불가시, 언제든지 "unavailable-unknown-reason"를 반환할 수 있습니다.

사용자 에이전트가 안전한 결제 확인을 지원하지 않거나, 지원하지만 기능이 비활성화된 경우 "unavailable-feature-not-enabled" 반환.
"payment" 권한 정책이 document에 활성화 되어 있지 않으면 "unavailable-no-permission-policy" 반환.
플랫폼 인증기가 없으면 "unavailable-no-user-verifying-platform-authenticator" 반환.
기타 이유로 해당 프레임에서 안전한 결제 확인 기능이 동작하지 않으면 "unavailable-unknown-reason" 반환.
"available" 반환.

개발자는 SPC 흐름 시작 여부 판단 시 다음과 같이 확인할 수 있습니다:

const spcAvailable =
    PaymentRequest &&
    PaymentRequest.securePaymentConfirmationAvailability &&
    await PaymentRequest.securePaymentConfirmationAvailability() === 'available';

참고: SPC 기능 탐지는 이미 생성된 PaymentRequest 객체에서 canMakePayment 를 호출하기보다, 정적 메서드 securePaymentConfirmationAvailability 사용을 권장합니다.

참고: 본 API의 프라이버시 고려는 § 12.5 securePaymentConfirmationAvailability를 통한 지문채취 참고.

4.7. 결제 방식 데이터 검증 단계

이 결제 방식에 대한 결제 방식 데이터 검증 단계는 입력 PaymentRequest request와 SecurePaymentConfirmationRequest data에 대해 다음과 같습니다:

테스트

data["credentialIds"] 가 비어 있으면 RangeError를 throw합니다.
data["credentialIds"]의 각 id에 대해:
1. id가 비어 있으면 RangeError를 throw합니다.
data["challenge"] 가 null이거나 비어 있으면 TypeError를 throw합니다.
data["instrument"]["displayName"] 이 비어 있으면 TypeError를 throw합니다.
data["instrument"]["icon"] 이 비어 있으면 TypeError를 throw합니다.
data["instrument"]["icon"]에 URL 파서를 실행합니다. 실패 반환이면 TypeError를 throw합니다.
data["instrument"]["details"] 가 존재하면서 비어 있으면 TypeError를 throw합니다.
data["rpId"] 이 유효한 도메인이 아니면, TypeError를 throw합니다.
data["payeeName"] 와 data["payeeOrigin"] 중 둘 다 생략된 경우, TypeError를 throw합니다.
data["payeeName"] 또는 data["payeeOrigin"] 중 하나라도 존재하면서 비어 있으면, TypeError를 throw합니다.
data["payeeOrigin"] 이 존재 시:
1. parsedURL = URL 파서 결과 data["payeeOrigin"].
2. parsedURL이 실패면 TypeError를 throw합니다.
3. parsedURL의 scheme가 "https"가 아니면 TypeError를 throw합니다.
data["paymentEntitiesLogos"] 가 존재하면서 비어 있지 않으면:
1. logo = data["paymentEntitiesLogos"]의 각 항목에 대해:
  1. logo["url"] 이 비어 있으면 TypeError를 throw합니다.
  2. logo["url"]에 URL 파서를 실행. 실패 반환이면 TypeError를 throw합니다.
  3. logo["label"] 이 비어 있으면 TypeError를 throw합니다.
data["locale"] 존재하고 비어 있지 않으면
1. tag = data["locale"]의 각 항목에 대해:
  1. tag이 올바른 [BCP47] 언어 태그가 아니면 TypeError를 throw합니다.
참고: locale 은 특정 입력 멤버와 관련된 언어나 방향 메타데이터와는 구별되며, 특정 문자열 값에 대한 주장이라기보다 호출자가 요청한 지역화 경험을 나타냅니다. 자세한 논의는 § 14 국제화 고려사항 참고.

4.8. 결제 가능 여부 확인 단계

이 결제 방식에 대한 결제 가능 여부 확인 단계는 입력 SecurePaymentConfirmationRequest data에 대해 다음과 같습니다:

테스트

data["payeeOrigin"] 이 존재할 경우:
1. parsedURL = URL 파서 결과 data["payeeOrigin"].
2. parsedURL이 실패가 아니라는 것을 assert합니다.
3. parsedURL의 scheme이 "https"임을 assert합니다.
참고: 이 사전 조건은 결제 방식 데이터 검증 단계에서 이미 확인되었습니다.
1. data["payeeOrigin"] 을 origin의 직렬화값으로 설정합니다.
아이콘 이미지 리소스를 가져오기(fetch), «["src" → data["instrument"]["icon"]]» 를 image로 전달합니다. 실패 시:
1. data["instrument"]["iconMustBeShown"] 이 true이면 false 반환.
2. 그 외에는 data["instrument"]["icon"] 를 빈 문자열로 설정.
  
  참고: 이 결과로 RP가 해당 아이콘이 표시되지 않았음을 알 수 있으며, instrument 값의 icon이 빈 문자열입니다.
참고: 이미지 리소스는 자격증명 매칭 여부와 관계없이 항상 가져와야 하며, 자격증명 존재 탐지(프라이버시 공격) 방지를 위해서입니다.
사용자 에이전트가 data["paymentEntitiesLogos"]의 항목을 리스트 끝에서 시작해 처음까지 제거할 수 있습니다.

참고: 사용자 에이전트가 표시할 로고 수를 제어할 수 있으며, 리스트의 로고는 호출자에게 표시 우선순위 내림차순임을 보장합니다.
logo = data["paymentEntitiesLogos"]의 각 항목에 대해:
1. 이미지 리소스 가져오기(fetch)를 logo에 대해 수행하고, «["src" → logo["url"]]»를 image로 전달하고 결과를 디코드합니다.
2. fetch 또는 decode 실패 시, logo["url"]를 빈 문자열로 설정합니다.
  
  참고: RP가 해당 로고가 표시되지 않았음을 알 수 있으며, paymentEntitiesLogos 값의 해당 logo의 url이 빈 문자열입니다.
참고: 로고 리소스도 자격증명 매칭 여부와 관계없이 항상 가져와야 하며, 자격증명 존재 탐지(프라이버시 공격) 방지 목적입니다.
id = data["credentialIds"]의 각 항목에 대해:
1. 현재 기기에서 자격증명 사용 가능 여부 조용하게 판별하는 단계를 실행하여 data["rpId"] 및 id를 전달합니다. 결과가 false이면 id를 data["credentialIds"]에서 제거합니다.
2. data["rpId"] 가 관련 설정 객체의 origin이 아니면, SPC 자격증명이 3자 파티 허용 여부를 조용히 판별하는 단계를 실행하고, data["rpId"]와 id를 전달합니다. 결과가 false이면 id를 data["credentialIds"]에서 제거합니다.
true 반환.

4.9. 거래 확인 UX 표시

PaymentRequest.show() 가 호출되고 안전한 결제 확인 결제 핸들러 가 선택된 경우(해당 알고리즘 19~24단계), 사용자 에이전트는 반드시 사용자에게 진행 선택 또는 방법을 결정할 수 있는 사용자 인터페이스를 표시해야 합니다.

4.9.1. 사용자에게 제공되는 정보

사용자 에이전트의 구현 자유도를 제한하지 않기 위해 이 규격은 특정 UI 표시를 요구하지 않습니다. 그러나 릴라잉 파티가 CollectedClientPaymentData 에 포함된 정보를 신뢰할 수 있도록, 사용자 에이전트는 아래 정보를 사용자에게 반드시 전달하고 인증에 대한 사용자의 동의를 반드시 수집해야 합니다:

payeeName 이 존재하는 경우.
payeeOrigin 이 존재하는 경우.
해당 거래의 total, 즉 currency 및 value.
결제 수단 instrument 상세(즉 displayName, details, icon). 이미지 리소스를 입력값 icon 에서 fetch/decode하지 못한 경우, 사용자 에이전트는 아이콘을 여기서 표시하지 않거나 기본 결제 수단 아이콘을 대신 사용할 수 있습니다.

참고: 지정 아이콘 fetch/decode 실패 시 iconMustBeShown 은 반드시 false이며, 아니면 결제 가능 여부 확인 단계가 실패했을 것임.
url 항목이 비어있지 않은 paymentEntitiesLogos 에 해당하는 로고.
- 사용자 에이전트는 각 PaymentEntityLogo에 대해 label 표시를 요구받지 않지만, 접근성 목적상 사용하는 것이 좋음(label은 항상 포함·서명됨).

사용자 에이전트는 locale 정보를 활용해 웹사이트와 일치하는 언어, 포맷의 지역화된 UX 표시를 할 수 있습니다.

showOptOut 이 true인 경우, 사용자 에이전트는 지정 릴라잉 파티에 대한 과정 거부(opt-out) 선택 기회를 반드시 제공해야 합니다.

테스트

authentication-optout.https.html (실시간 테스트) (소스)

4.9.2. 거래 확인 UX 결과

사용자 에이전트는 사용자가 진행 여부와 방법을 아래 옵션 중 하나로 표시할 수 있도록 해야 합니다:

사용자가 SPC 자격증명으로 인증하며 결제 진행을 희망할 경우

PaymentRequest 에 대해 user accepts the payment request algorithm 실행.

사용자가 결제를 진행하려 하지만 SPC 자격증명을 사용할 수 없거나 사용을 원치 않을 경우

아래 단계 실행:

data["credentialIds"] 를 빈 리스트로 설정.

참고: 이로 인해 PaymentRequest.show() promise가 "NotAllowedError" DOMException 으로 reject됨(§ 4.10 결제 요청 응답 단계 참고).
해당 PaymentRequest 에 대해 user accepts the payment request algorithm 실행.

테스트

authentication-auth-another-way.https.html (실시간 테스트) (소스)

사용자가 결제 진행을 원치 않을 경우

해당 PaymentRequest 에 대해 user aborts the payment request algorithm 실행.

참고: 이로 인해 PaymentRequest.show() promise는 "AbortError" DOMException 으로 reject됨.

사용자가 지정 릴라잉 파티에 대한 과정에서 opt-out을 희망할 경우

PaymentRequest.show() 를 "OptOutError" DOMException으로 reject. (§ 12.6 사용자 거부 참고)

참고: 해당 옵션은 showOptOut 이 true일 때만 반드시 사용자에게 노출되어야 함.

4.9.3. 테스트 자동화 지원

현재 거래 자동화 모드가 "none"이 아니면, 사용자 에이전트는 먼저 자동화 컨텍스트에 있는지 확인해야 하며(WebDriver 보안 고려 참고), 위 정보 전달·동의 수집을 건너뛰고 아래 각 자동화 모드 값에 따라 동작해야 합니다:

"autoAccept": 사용자가 거래 세부정보를 보고 수락한 것처럼 동작.
"autoChooseToAuthAnotherWay": 사용자가 거래 세부정보를 보고 수락, 동시에 SPC 자격증명 인증 사용을 원치 않은 것처럼 동작. data["credentialIds"] 가 비어 있다면 "autoAccept"와 동일.
"autoReject": 사용자가 거래 세부정보를 보고 거절한 것처럼 동작(즉, 거래 진행 원치 않음).
"autoOptOut": 사용자가 거래 세부정보를 보고 opt-out을 희망한 것처럼 동작.

4.10. 결제 요청 응답 단계

결제 요청 응답 단계는 해당 PaymentRequest request와 SecurePaymentConfirmationRequest data에 대해 다음과 같습니다.

참고: 이 단계는 사용자가 거래 확인 UX를 수락한 경우에만 실행되며, user accepts the payment request algorithm 에 의해 호출됩니다.

data["credentialIds"] 가 비어 있으면, "NotAllowedError" DOMException을 throw. 이는 사용자가 SPC 인증 사용이 불가능하거나 원치 않는 경우 인증 절차 프라이버시를 보장함.

참고: 여기서 throw되면 PaymentRequest.show() promise가 "NotAllowedError" DOMException 으로 reject됨.
topOrigin = 최상위 오리진(request의 관련 설정 객체 기준)으로 설정.
payment = AuthenticationExtensionsPaymentInputs 딕셔너리(아래 필드 갖음):

isPayment

불리언 값 true.

rpId

data["rpId"].

topOrigin

topOrigin

payeeName

data["payeeName"] 이 존재하면, 없으면 생략.

payeeOrigin

data["payeeOrigin"] 이 존재하면, 없으면 생략.

paymentEntitiesLogos

data["paymentEntitiesLogos"] 가 존재·비어 있지 않으면, 없거나 비어 있으면 생략.

현 규격은 PaymentEntityLogo 당 단일 URL만 지원하므로 구조 복사·서명만 해도 사용자에게 무엇이 표시됐는지 표시 가능. 차후 멀티 URL 지원 시 RP에 표시된 실제 URL 전달이 필요함.

total

request.[[details]]["total"].

instrument

data["instrument"].

browserBoundPubKeyCredParams

data["browserBoundPubKeyCredParams"].
extensions = AuthenticationExtensionsClientInputs 딕셔너리(payment 멤버에 payment 설정, 다른 멤버는 data["extensions"]에서 복사).
publicKeyOpts = PublicKeyCredentialRequestOptions 딕셔너리(아래 필드 갖음):

challenge

data["challenge"].

timeout

data["timeout"].

rpId

data["rpId"].

userVerification

required.

extensions

extensions

참고: 이 알고리즘은 userVerification값을 "required"로 고정(Chrome 초안 구현이 지원하는 값). 향후 WG가 다른 값(예: "preferred"/"discouraged") 수요 있으면 구현자 제안 환영.
id = data["credentialIds"]의 각 항목에 대해:
1. descriptor = PublicKeyCredentialDescriptor 딕셔너리(아래 필드 갖음):
  
  type
  
  public-key.
  
  id
  
  id
  
  transports
  
  길이 1 시퀀스로, "internal" 만 포함.
2. descriptor를 publicKeyOpts["allowCredentials"]에 append.
outputCredential = Request a Credential 알고리즘 실행, «["publicKey" → publicKeyOpts]» 전달.

참고: Chrome 초안에서는 전체 data.credentialIds가 아닌 현재 기기와 맞는 것 하나만 넘기지만, 표준은 전체 리스트를 넘김.

참고: 이 단계는 [webauthn-3]의 Get 동작을 trig함.
outputCredential 반환.

5. WebAuthn 확장 - "`payment`"

이 클라이언트 등록 확장 및 인증 확장은 각각 자격증명이 안전한 결제 확인용으로 생성 또는 사용됨을 나타냅니다.

등록 시, 이 확장은 브라우저가 안전한 결제 확인 자격증명 ID를 식별·캐시할 수 있도록 합니다. 인증 시, 이 확장은 제3자가 릴라잉 파티를 대신하여 인증 절차를 실행할 수 있도록 하며, 동시에 거래 정보를 서명된 암호문에 추가합니다.

특히, 웹사이트는 navigator.credentials.get() 를 이용하여 이 확장에 직접 접근하면 안 됩니다; 인증은 반드시 PaymentRequest 에서 "secure-payment-confirmation" 결제 방식과 함께 사용해야만 활성화됩니다.

참고: 과거에는 payment 확장이 교차(origin) iframe에서 자격증명 생성을 허용했으나, 이제 WebAuthn에서 기본 허용됨(WebAuthn PR #1801).

테스트

이 테스트는 명세 라인에 직접 대응하지는 않으며, 교차(origin) iframe 내부에서 인증을 트리거할 수 있음을 테스트합니다. 해당 동작은 금지 라인이 없음을 통해 명세됩니다.

authentication-in-iframe.sub.https.html (실시간 테스트) (소스)

확장 식별자

payment

동작 적용 대상

등록 및 인증

클라이언트 확장 입력

partial dictionary AuthenticationExtensionsClientInputs {
  AuthenticationExtensionsPaymentInputs payment;
};

dictionary AuthenticationExtensionsPaymentInputs {
  boolean isPayment;
  sequence<PublicKeyCredentialParameters> browserBoundPubKeyCredParams;

  // Only used for authentication.
  USVString rpId;
  USVString topOrigin;
  USVString payeeName;
  USVString payeeOrigin;
  sequence<PaymentEntityLogo> paymentEntitiesLogos;
  PaymentCurrencyAmount total;
  PaymentCredentialInstrument instrument;
};

isPayment

확장이 활성화 중임을 나타냅니다.

rpId