결제 요청 API

1.1 목표

유저 에이전트가 판매자, 유저, 결제 수단의 중간에서 동작할 수 있게 허용함
Allow the user agent to act as intermediary between merchants, users, and payment methods
판매자, 유저 에이전트, 결제 수단 사이의 커뮤니케이션 흐름을 (그 의미가 있을 정도로) 표준화함.
Standardize (to the extent that it makes sense) the communication flow between a merchant, user agent, and payment method
웹에서 더 안전한 결제 거래를 일으키는 결제 수단을 허용함
Allow payment methods to bring more secure payment transactions to the web

1.2 목표 아님

새로운 결제 수단을 만들고자 하지 않음
Not trying to create a new payment method
결제 프로세서를 직접적으로 통합하고자 하지 않음
Not trying to integrate directly with payment processors

2. 적합성

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].

This specification defines one class of products:

Conforming user agent

A user agent MUST behave as described in this specification in order to be considered conformant. In this specification, user agent means a Web browser or other interactive user agent as defined in [HTML5].

User agents MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

A conforming Payment Request API user agent MUST also be a conforming implementation of the IDL fragments of this specification, as described in the “Web IDL” specification. [WEBIDL]

Note

3. 의존성

이 스펙은 여러 다른 스펙에 의존합니다

This specification relies on several other underlying specifications.

Payment Request Architecture

The terms Payment Method, Payment App, and Payment Transaction Message Specification are defined by the Payment Request Architecture document [PAYMENTARCH].

Payment Method Identifiers

The term Payment Method Identifier is defined by the Payment Method Identifiers specification [METHODIDENTIFIERS].

HTML5

The terms global object, queue a task, browsing context, and top-level browsing context are defined by [HTML5].

ECMA-262 6th Edition, The ECMAScript 2015 Language Specification

The terms Promise, internal slot, TypeError, JSON.stringify, and JSON.parse are defined by [ECMA-262-2015].

This document uses the format object@[[slotname]] to mean the internal slot [[slotname]] of the object object.

The term JSON-serializable object used in this specification means an object that can be serialized to a string using JSON.stringify and later deserialized back to an object using JSON.parse with no loss of data.

DOM4

The Event type and the terms fire an event, dispatch flag, stop propagation flag, and stop immediate propagation flag are defined by [DOM4].

DOMException and the following DOMException types from [DOM4] are used:

Type	Message (optional)
`InvalidStateError`	The object is in an invalid state
`NotSupportedError`	The payment method was not supported
`SecurityError`	The operation is only supported in a secure context

WebIDL

When this specification says to throw an error, the user agent must throw an error as described in [WEBIDL]. When this occurs in a sub-algorithm, this results in termination of execution of the sub-algorithm and all ancestor algorithms until one is reached that explicitly describes procedures for catching exceptions.

Secure Contexts

The term secure context is defined by the Secure Contexts specification [POWERFUL-FEATURES].

4. PaymentRequest 인터페이스

[Constructor(sequence<DOMString> supportedMethods, PaymentDetails details, optional PaymentOptions options, optional object data)]
interface PaymentRequest : EventTarget {
    Promise<PaymentResponse> show();
    void                     abort();

    readonly attribute ShippingAddress? shippingAddress;
    readonly attribute DOMString?       shippingOption;

    // Supports "shippingaddresschange" event 
             attribute EventHandler     onshippingaddresschange;

    // Supports "shippingoptionchange" event 
             attribute EventHandler     onshippingoptionchange;
};

웹 페이지는 결제 요청을 만들기 위해 PaymentRequest를 생성합니다. 이는 보통 결제 프로세스에 진입하는 유저와 관련있습니다. (예: 게임에서 "파워 업"을 선택했을 때, 자동으로 주차장 구조의 키오스크가 나오거나, "구매", "결제", "체크아웃"버튼이 활성화 되거나 하는 등) PaymentRequest는 유저가 결제 요청을 승인하거나 거절하기 전에 입력을 제공하여, 웹 페이지가 유저 에이전트와 정보를 교환할 수 있게 합니다.

A web page creates a PaymentRequest to make a payment request. This is typically associated with the user initiating a payment process (e.g., selecting a "Power Up" in an interactive game, pulling up to an automated kiosk in a parking structure, or activating a "Buy", "Purchase", or "Checkout" button). The PaymentRequest allows the web page to exchange information with the user agent while the user is providing input before approving or denying a payment request.

다음 예제는 PaymentRequest를 어떻게 구성해야 하는 지와 유저 인터렉션의 시작을 나타내는 예제입니다.

The following example shows how to construct a PaymentRequest and begin the user interaction:

Example 1

var payment = new PaymentRequest(supportedMethods, details, options, data);
payment.addEventListener("shippingaddresschange", function (changeEvent) {
// 배송지 변경 처리
});

payment.show().then(function(paymentResponse) {
// paymentResponse 처리
// paymentResponse.methodName이 선택된 결제 수단을 포함함
// paymentResponse.details가 응답에서 정의한 결제 수단을 포함함 
  paymentResponse.complete(true);
}).catch(function(err) {
  console.error("어머, 뭔가 이상해요", err.message);
});

4.1 PaymentRequest 생성자

PaymentRequest는 제공된 supportedMethods 목록, 결제 details, 결제 options, 그리고 data로 정의된 어떤 결제 수단으로 구성합니다.

The PaymentRequest is constructed using the supplied supportedMethods list, the payment details, the payment options, and any payment method specific data.

Issue 40: How does a website pass additional (not payment method specific) data to the payment app?

It is proposed that a conformance criteria for implementations of this API be that any data passed into the request is passed on to the payment app unaltered. This would allow extensions of the data schema such as the addition of properties that are not documented in this specification or known to implementors such as JSON-LD @context or similar to be passed between the website and payment app.

Note

supportedMethods 시퀀스는 판매자가 웹 사이트에서 허용하는 결제 수단을 위한 결제 수단 식별자를 포함합니다.

The supportedMethods sequence contains the payment method identifiers for the payment methods that the merchant web site accepts.

Example 2

["visa", "bitcoin", "bobpay.com"]

details 객체는 유저가 주문에서 라인 아이템을 완료하기 위해 요구되는 거래 관련 정보를 포함합니다.

The details object contains information about the transaction that the user is being asked to complete such as the line items in an order.

Example 3

{
  "items": [
    {
      "id": "basket",
      "label": "Sub-total",
      "amount": { "currency": "USD", "value" : "55.00" }, // US$55.00
    },
    {
      "id": "tax",
      "label": "Sales Tax",
      "amount": { "currency": "USD", "value" : "5.00" }, // US$5.00
    },
    {
      "id": "total",
      "label": "Total due",
      "amount": { "currency": "USD", "value" : "60.00" }, // US$60.00
    }
  ]
}

options 객체는 웹 페이지가 결제 요청 시스템으로부터 사용하기를 원하는 옵션에 대한 정보를 포함합니다.

The options object contains information about what options the web page wishes to use from the payment request system.

Example 4

{
  "requestShipping": true
}

data는 지원하는 결제 수단에서 필요로 할 수 있는 옵션 정보를 가지는 시리얼화된 JSON 객체입니다.

data is a JSON-serializable object that provides optional information that might be needed by the supported payment methods.

Example 5

{
  "bobpay.com": {
      "merchantIdentifier": "XXXX",
      "bobPaySpecificField": true
  },
  "bitcoin": {
      "address": "XXXX"
  }
}

Issue 15: Combine API parameters into a single request object + options

There is an open issue about whether supportedMethods, details, and data should be combined into a single object.

Issue 16: Use navigator.payments singleton, factory method, or PaymentRequest constructor

There is an open issue about how a payment request is initiated. The options proposed include using a singleton at navigator.payments, using a factory method to create an instance, or using a constructor as currently described in the specification.

Issue 47: Should a payment request be just data, or a programmable object?

There is an open issue about whether the payment request should be a programmable object or should be just pure data that can be operated on by methods.

Issue 19: Should the API handle pre-auth, recurring payments, and similar scenarios

There is an open issue about whether the API should handle occasions when a site wants to request a payment method but not actually make a charge immediately. These may include identification validation, pre-auth for a deposit, pre-auth for a later payment, making recurring payments, and more.

Issue 23: Can the merchant influence order of presentation of payment apps to the user

There is an open issue about whether the merchant can influence order of presentation of payment apps to the user. There is a suggestion that we should support merchants specifying a preference and allow users to express a preference that overrides merchant preferences.

Issue 48: Should list of accepted payment methods be strings or objects?

There is an open issue about whether the list of supported payment methods should be passed to the user agent as a simple sequence of strings or as a more complex and flexible object structure.

Issue 51: Should the payment API be more conversational or less conversational?

There is an open issue regarding whether the current pattern of using events for exchange of data between the user agent and the website is the best design for this API. An alternative pattern has been proposed in the issue thread.

PaymentRequest 생성자는 반드시 아래 순서대로 동작해야합니다. [MUST]

The PaymentRequest constructor MUST act as follows:

supportedMethods 시퀀스의 길이가 0이라면, TypeError를 던집니다.
If the length of the supportedMethods sequence is zero, then throw a TypeError.
생성자를 호출하는 스크립트의 전역 객체가 보안 콘텍스트를 고려하지 않았다면, SecurityError를 던집니다.
If the global object of the script calling the constructor is not considered a secure context, then throw a SecurityError.

Issue 22: Spec should use [SecureContext] once that is defined in Web IDL
Using [SecureContext] in Web IDL will allow us to eliminate this prose.
생성자를 호출하는 스크립트의 브라우징 콘텍스트가 상위 레벨 브라우징 콘텍스트가 아니라면, SecurityError를 던집니다.
If the browsing context of the script calling the constructor is not a top-level browsing context, then throw a SecurityError.

Issue 2: Should the Payment Request API only be available in a top-level browsing context?

There is an open issue about requiring a top-level browsing context for using PaymentRequest. Requiring one is a mitigation for a user being tricked into thinking a trusted site is asking for payment when in fact an untrusted iframe is asking for payment. The problem is some iframes may have a legitimate reason to request payment.
details가 0개보다 더 큰 길이인 items의 시퀀스를 포함하지 않는다면, TypeError를 던집니다.
If details does not contain a sequence of items with length greater than zero, then throw a TypeError.
data가 시리얼화된 JSON 객체가 아니라면, TypeError를 던집니다.
If data is not a JSON-serializable object, then throw a TypeError.
data의 어떤 상위 레벨 필드의 이름이 supportedMethods 내 결제 수단 식별자 중 하나라도 매치되지 않는다면, TypeError를 던집니다.
If the name of any top level field of data does not match one of the payment method identifiers in supportedMethods, then throw a TypeError.
어떤 상위 레벨 필드의 값이 시리얼화된 JSON 객체가 아니라면, TypeError를 던집니다.
If the value of any top level field is not a JSON-serializable object, then throw a TypeError.
request를 새 PaymentRequest로 합니다.
Let request be a new PaymentRequest.
request@[[supportedMethods]]에 supportedMethods를 담습니다.
Store supportedMethods into request@[[supportedMethods]].
request@[[details]]에 details를 담습니다.
Store details into request@[[details]].
request@[[options]]에 options를 담습니다.
Store options into request@[[options]].
request@[[data]]에 data를 담습니다.
Store data into request@[[data]].
request@[[state]] 값을 created로 설정합니다.
Set the value request@[[state]] to created.
request의 shippingAddress 속성 값을 null로 설정합니다.
Set the value of the shippingAddress attribute on request to null.
request의 shippingOption 속성 값을 null로 설정합니다.
Set the value of the shippingOption attribute on request to null.
details가 길이가 1인 shippingOptions 시퀀스를 포함하고 있다면, shippingOption을 시퀀스 내 단일 ShippingOption의 id로 설정합니다.
If details contains a shippingOptions sequence with a length of 1, then set shippingOption to the id of the only ShippingOption in the sequence.
request@[[updating]] 값을 false로 설정합니다.
Set the value request@[[updating]] to false.
request를 반환합니다.
Return request.

4.2 show()

show 메서드는 페이지에서 결제 요청에 따른 유저 인터렉션을 시작하고 싶을 때 호출합니다. show 메서드는 유저가 결제 요청을 승인했을 때 해소되는 Promise를 반환합니다. 유저 인터페이스 중 몇가지는 유저가 결제 요청을 원활하게 하도록 show 메서드 반환 이후 보여집니다.

The show method is called when the page wants to begin user interaction for the payment request. The show method will return a Promise that will be resolved when the user accepts the payment request. Some kind of user interface will be presented to the user to facilitate the payment request after the show method returns.

Issue 56: Should a website be able to provide a label for the 'Buy' or 'Checkout' button displayed in the payment app?

It may help users understand what they are accepting if the web site is able to label the "accept" button. For example, if a user is about to "Buy" something, "Reserve" something, "Subscribe" to something, etc. That said, this may create payment interface/experience issues and accidentally lead to customers thinking they're performing actions like a one-time purchase, when they are in fact signing up for a subscription.

show 메서드는 반드시 아래 순서대로 동작해야합니다. [MUST]

The show method MUST act as follows:

메소드가 호출되면 request를 PaymentRequest 객체로 합니다.
Let request be the PaymentRequest object on which the method is called..
request@[[state]] 값이 created가 아니라면 InvalidStateError를 던집니다.
If the value of request@[[state]] is not created then throw an InvalidStateError.
request@[[state]] 값을 interactive로 설정합니다.
Set the value of request@[[state]] to interactive.
acceptPromise를 새 Promise로 합니다.
Let acceptPromise be a new Promise.
request@[[acceptPromise]]에 acceptPromise를 담습니다.
Store acceptPromise in request@[[acceptPromise]].
acceptPromise를 반환받을 나머지 스텝을 비동기로 수행합니다.
Return acceptPromise and asynchronously perform the remaining steps.
acceptedMethods를 유저 에이전트가 허용하지 않는 모든 식별자를 제거한 결제 수단 식별자 request@[[supportedMethods]]의 시퀀스로 합니다.
Let acceptedMethods be the sequence of payment method identifiers request@[[supportedMethods]] with all identifiers removed that the user agent does not accept.
acceptedMethods의 길이가 0이라면, NotSupportedError와 함께 acceptPromise를 받지 않습니다.
If the length of acceptedMethods is zero, then reject acceptPromise with a NotSupportedError.
결제 요청 프로세스가 유저와 상호작용할 수 있게 하는 유저 인터페이스를 보여줍니다. acceptPromise는 유저 인터페이스의 인터렉션을 통한 유저 에이전트 결제 요청 알고리즘에 의해 해결됩니다.
Show a user interface to allow the user to interact with the payment request process. The acceptPromise will later be resolved by the user accepts the payment request algorithm through interaction with the user interface.

4.3 abort()

abort 메소드는 웹 페이지에서 show 메서드가 호출된 이후 [[acceptPromise]]가 해결되기 전에 결제 요청을 취소하기를 원할 때 호출합니다.

The abort method may be called if the web page wishes to abort the payment request after the show method has been called and before the [[acceptPromise]] has been resolved.

abort 메서드는 반드시 아래 순서대로 동작해야합니다. [MUST]

The abort method MUST act as follows:

만약 [[state]] 값이 interactive가 아니라면 InvalidStateError를 던집니다.
If the value of [[state]] is not interactive then throw an InvalidStateError.
내장 슬롯 [[state]]의 값을 closed로 설정합니다.
Set the value of the internal slot [[state]] to closed.
메소드로부터 반환받을 나머지 스텝을 비동기로 수행합니다.
Return from the method and asynchronously perform the remaining steps.
현재 유저 인터렉션을 취소하고 남은 유저 인터페이스를 닫습니다.
Abort the current user interaction and close down any remaining user interface

4.4 상태 변화

내장 슬롯 [[state]]는 아래의 상태 변화를 따릅니다:

The internal slot [[state]] follows the following state transitions:

역주: 아래 이미지는 원래 엑박이에요..

Transition diagram for internal slot state of a PaymentRequest object

4.5 shippingAddress

shippingAddress는 유저가 배송지를 제공할 때 채워집니다. 기본값은 null입니다. 유저가 배송지를 제공할 때, 배송지 변경 알고리즘이 동작합니다.

shippingAddress is populated when the user provides a shipping address. It is null by default. When a user provides a shipping address, the shipping address changed algorithm runs.

onshippingaddresschange는 shippingaddresschange Event를 위한 EventHandler입니다.

onshippingaddresschange is an EventHandler for an Event named shippingaddresschange.

4.6 shippingOption

shippingOption은 유저가 배송 옵션을 선택했을 때 채워집니다. 기본값은 null입니다. 유저가 배송 옵션을 선택했을 때, 배송 옵션 변경 알고리즘이 동작합니다.

shippingOption is populated when the user chooses a shipping option. It is null by default. When a user chooses a shipping option, the shipping option changed algorithm runs.

onshippingoptionchange는 shippingoptionchange Event를 위한 EventHandler입니다.

onshippingoptionchange is an EventHandler for an Event named shippingoptionchange.

4.7 내장 슬롯

PaymentRequest의 인스턴스는 아래 표의 내장 슬롯과 함께 생성됩니다.

Instances of PaymentRequest are created with the internal slots in the following table:

내장 슬롯	설명 (표준이 아님)
[[supportedMethods]]	`supportMethods`는 생성자로 제공됩니다. The `supportMethods` supplied to the constructor.
[[details]]	결제 요청을 위한 현재 `PaymentDetails`는 생성자에 의해 초기화되고 생성되며 `updateWith`를 호출하여 갱신합니다. The current `PaymentDetails` for the payment request initially supplied to the constructor and then updated with calls to `updateWith`.
[[options]]	`PaymentOptions`은 생성자로 제공됩니다. The `PaymentOptions` supplied to the constructor.
[[data]]	`data`에 정의된 결제 수단은 앱의 동작에 영향을 주는 Payment App에서 사용하는 생성자로 제공됩니다. The payment method specific `data` supplied to the constructor used by a Payment App to influence the app's behavior.
[[state]]	결제 요청 중 현재 상태입니다. The current state of the payment request.
[[updating]]	true는 결제 요청을 업데이트하기 위해 `updateWith`을 호출한 상태이고, false는 그 외의 경우입니다. true is there is a pending `updateWith` call to update the payment request and false otherwise.
[[acceptPromise]]	`show` 중에 생성된 보류중인 Promise는 유저가 결제 요청을 수락하면 해결됩니다. The pending Promise created during `show` that will be resolved if the user accepts the payment request.

5. CurrencyAmount

dictionary CurrencyAmount {
    required DOMString currency;
    required DOMString value;
};

Issue 119: Should negative amounts be reflected using signed values?

The resolution of the WG per Issue #57 defined a format for currencies and amounts that lacked support for negative values. The format below adds this capability in a way that is not common for financial messaging standards (using signed numbers). The rationale for negative numbers is to support discounts. The group is still discussing whether functionality to support discounts might be implemented in a different manner (e.g., via a transaction type).

CurrencyAmount 사전은 금전 합계를 제공할 때 사용합니다. 아래 필드는 유효한 CurrencyAmount를 위해, 반드시 제공해야합니다. [MUST]

The CurrencyAmount dictionary is used to supply monetary amounts. The following fields MUST be supplied for a CurrencyAmount to be valid:

currency: currency는 화폐 식별자를 포함하는 문자열입니다. 대부분의 식별자는 [ISO4217]에서 정의하는 알파벳으로 구성된 세 글자 코드(예를 들어, "USD"는 US 달러를 나타냅니다)로 이루어져 있으나, 임의의 문자열도 유효할 수 있도록 고려해야하며, user agents는 반드시 이 문자열의 유효성을 검증해서는 안됩니다.
currency is a string containing a currency identifier. The most common identifiers are three-letter alphabetic codes as defined by [ISO4217] (for example, "USD" for US Dollars) however any string is considered valid and user agents MUST not attempt to validate this string.
value: 10진수 화폐 값을 포함하는 문자열입니다. 만약 10진수 구분자가 필요하다면 문자열은 반드시 single U+002E FULL STOP을 10진수 구분자로 사용하여야 합니다 [MUST]. 값이 음수라면 문자열은 반드시 single U+002D HYPHEN-MINUS로 시작해야합니다 [MUST]. 그 밖의 모든 문자는 반드시 U+0030 DIGIT ZERO (0)부터 U+0039 DIGIT NINE (9) 범위에 속하는 문자로 시작해야합니다.
A string containing the decimal monetary value. If a decimal separator is needed then the string MUST use a single U+002E FULL STOP character as the decimal separator. The string MUST begin with a single U+002D HYPHEN-MINUS character if the value is negative. All other characters must be characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).

Note
문자열은 반드시 이 정규 표현식과 매칭해야 합니다. ^-?[0-9]+(\.[0-9]+)?$
The string should match the regular expression ^-?[0-9]+(\.[0-9]+)?$.

다음 예제는 US$55.00을 나타냅니다.

The following example shows how to represent US$55.00.

Example 6

{
  "currency": "USD",
  "value" : "55.00"
}

6. PaymentDetails 사전

dictionary PaymentDetails {
    sequence<PaymentItem>    items;
    sequence<ShippingOption> shippingOptions;
};

PaymentDetails 사전은 PaymentRequest 생성자로 전달되며, 요청 거래에 대한 정보를 제공합니다. PaymentDetails 사전 또한 updateWith를 사용하여 결제 요청을 갱신할 수 있습니다.

The PaymentDetails dictionary is passed to the PaymentRequest constructor and provides information about the requested transaction. The PaymentDetails dictionary is also used to update the payment request using updateWith.

다음 필드는 PaymentDetails 사전의 일부입니다.

The following fields are part of the PaymentDetails dictionary:

items

이 PaymentItem 사전의 시퀀스는 결제 요청이 무엇을 위한 것인지 감지합니다. 이 시퀀스는 반드시 최소한 하나 이상 PaymentItem을 가져야합니다. 시퀀스 내 마지막 PaymentItem은 결제 요청의 총량을 나타냅니다. 이 호출 코드가 담당하는 건 이전 아이템의 합이 총량이 되도록 하는 것입니다. 유저 에이전트는 만약 이 값이 true라면 검증을 하지 않을 수도 있습니다. [MAY]

This sequence of PaymentItem dictionaries indicates what the payment request is for. The sequence must contain at least one PaymentItem. The last PaymentItem in the sequence represents the total amount of the payment request. It is the responsibility of the calling code to ensure that the total amount is the sum of the preceding items. The user agent MAY not validate that this is true.

shippingOptions

선택에 사용할 수 있는 다른 배송 옵션을 포함하는 시퀀스입니다.

만약 시퀀스가 비어있다면, 이는 판매자가 현재 shippingAddress에 배송할 수 없다고 감지합니다.

만약 시퀀스가 하나의 아이템만 가지고 있다면, 이는 이후에 사용될 배송 옵션이 되고 shippingOption은 배송 옵션 변경 알고리즘을 사용하지 않는 옵션의 id로 정의됩니다.

A sequence containing the different shipping options that the use may choose from.

If the sequence is empty, then this indicates that the merchant cannot ship to the current shippingAddress.

If the sequence only contains one item, then this is the shipping option that will be used and shippingOption will be set to the id of this option without running the shipping option changed algorithm.

Issue 18: Constructor should not include "total" in list of items

There is an open issue about whether the items sequence should special-case the last item in the sequence to represent the total.

7. PaymentOptions 사전

dictionary PaymentOptions {
    boolean requestShipping = false;
};

PaymentOptions 사전은 PaymentRequest 생성자로 전달되며, 결제 요청 시 원하는 옵션에 대한 정보를 제공합니다.

The PaymentOptions dictionary is passed to the PaymentRequest constructor and provides information about the options desired for the payment request.

아래 필드들은 PaymentRequest 생성자로 인해 전달될 수도 있습니다. [MAY]

The following fields MAY be passed to the PaymentRequest constructor:

requestShipping: 이 boolean 값은 유저 에이전트가 결제 요청의 일부로 배송지를 모으고 반환해줄 지 결정합니다. 예를 들어, 판매자가 유저에게 물리적인 물건을 배송해야할 때 이 값을 true로 설정합니다. 온라인에서만 판매하는 전자 상품 거래인 경우에는 이 값을 false로 설정합니다. 만약 이 값이 제공되지 않은 경우 PaymentRequest는 false 값이 제공되었다고 가정하여 동작합니다.
This boolean value indicates whether the user agent should collect and return a shipping address as part of the payment request. For example, this would be set to true when physical goods need to be shipped by the merchant to the user. This would be set to false for an online-only electronic purchase transaction. If this value is not supplied then the the PaymentRequest behaves as if a value of false had been supplied.

8. PaymentItem 사전

dictionary PaymentItem {
    required DOMString      id;
    required DOMString      label;
    required CurrencyAmount amount;
};

하나 혹은 그 이상의 PaymentItem 사전 시퀀스는 PaymentDetails 사전에 포함되어 있으며, 결제 요청이 있을 때 요청한 값이 무엇인 지 나타냅니다.

A sequence of one or more PaymentItem dictionaries is included in the PaymentDetails dictionary to indicate the what the payment request is for and the value asked for.

아래 필드는 반드시 PaymentItem에 유효한 값으로 포함해야 합니다. [MUST]

The following fields MUST be included in a PaymentItem for it to be valid:

id: 이 PaymentItem에 참조하기 위해 사용하는 문자열 식별자입니다. 이 값은 반드시 PaymentRequest에 고유한 값으로 주어야 합니다. [MUST]
This is a string identifier used to reference this PaymentItem. It MUST be unique for a given PaymentRequest.
label: 아이템에 대한 사람이 읽기좋은 설명입니다. 유저 에이전트는 이 값을 유저에게 보여줄 수도 있습니다.
This is a human-readable description of the item. The user agent may display this to the user.
amount: 아이템을 위한 금전 합계를 포함하는 CurrencyAmount입니다.
A CurrencyAmount containing the monetary amount for the item.

Issue 3: Should it be possible to provide amounts in more than one currency
There is an open issue about whether it should be possible to provide a PaymentItem with amounts in more than once currency.

Issue 4: Should it be possible to vary amounts depending on payment method
There is an open issue about whether it should be possible to provide a different amounts depending upon the payment method.

Issue 14: Handling non-decimal currencies
There is an open issue about whether and how to handle non-decimal currencies.

9. ShippingAddress 인터페이스

interface ShippingAddress {
    // [...] fields TBC 
};

만약 PaymentRequest에서 전달한 PaymentOptions 내의 requestShipping 플래그가 true로 설정되어 있다면, 유저 에이전트는 PaymentRequest 객체의 shippingAddress 필드를 사용자가 선택한 배송지로 채웁니다.

If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then the user agent will populate the shippingAddress field of the PaymentRequest object with the user's selected shipping address.

Issue 6: Write-up proposal for shipping address fields

The fields of the ShippingAddress interface are yet to be defined.

Issue 1: Should the merchant be able to request your email and recipient phone number

There is an open question about what data beyond shipping address the merchant might be able to request from the user agent. Is capturing email and recipient phone important to you?

10. ShippingOption 인터페이스

dictionary ShippingOption {
    required string         id;
    required string         label;
    required CurrencyAmount amount;
};

ShippingOption 사전은 배송 옵션을 설명하는 필드를 가집니다. 웹 페이지에서는 유저에게 하나 혹은 그 이상의 배송 옵션을 updateWith 메소드를 호출 한 뒤 변경 이벤트를 받아서 제공할 수 있습니다.

The ShippingOption dictionary has fields describing a shipping option. A web page can provide the user with one or more shipping options by calling the updateWith method in response to a change event.

아래 필드는 반드시 PaymentItem에 유효한 값으로 포함해야 합니다. [MUST]

The following fields MUST be included in a PaymentItem for it to be valid:

id: 이 ShippingOption에 참조하기 위해 사용하는 문자열 식별자입니다. 이 값은 반드시 PaymentRequest에 고유한 값으로 주어야 합니다. [MUST]
This is a string identifier used to reference this ShippingOption. It MUST be unique for a given PaymentRequest.
label: 아이템에 대한 사람이 읽기좋은 설명입니다 유저 에이전트는 이 문자열을 사용하여 유저에게 배송 옵션을 보여줘야 합니다. [SHOULD]
This is a human-readable description of the item. The user agent SHOULD use this string to display the shipping option to the user.
amount: 아이템을 위한 금전 합계를 포함하는 CurrencyAmount입니다.
A CurrencyAmount containing the monetary amount for the item.

11. PaymentResponse 인터페이스

interface PaymentResponse {
    readonly attribute DOMString methodName;
    readonly attribute object    details;

    Promise<void> complete(boolean success);
};

PaymentResponse는 유저가 결제 방법을 선택하고 결제 요청을 동의했을 때 반환됩니다. 이는 아래 필드를 포함합니다.

A PaymentResponse is returned when a user has selected a payment method and approved a payment request. It contains the following fields:

methodName: 유저가 거래를 이행하고자 선택한 결제 수단을 위한 결제 수단 식별자입니다.
The payment method identifier for the payment method that the user selected to fulfil the transaction.
details: 거래를 처리하고 성공적인 계좌 대치를 결정하기 위해 판매자가 사용하는 결제 수단 특정 메시지를 제공하는 시리얼화된 JSON 객체입니다.
A JSON-serializable object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer.

11.1 complete()

complete 메서드는 반드시 유저가 결제 요청을 허락하고 [[acceptPromise]가 해결된 뒤 호출해야합니다. complete 메서드는 불리언 타입의 인수를 가지며, 이 인수가 true인 경우 프로세스를 성공적으로 진행한 것이며, false인 경우 프로세스를 실패한 것입니다. complete 메서드를 호출하여 유저 에이전트의 유저 인터렉션을 끝내도록 지시합니다. (그리고 나머지 유저 인터페이스도 다 닫아야합니다.)

The complete method must be called after the user has accepted the payment request and the [[acceptPromise]] has been resolved. The complete method takes a boolean argument that indicates the payment was successfully processed if true and that processing failed if false. Calling the complete method tells the user agent that the user interaction is over (and should cause any remaining user interface to be closed).

Issue 17: complete() should take a string argument not boolean

There is an open issue about what values can be supplied to complete. These may depend on the payment method selected and should then be defined in Payment Transaction Message specifications such as the Basic Card Payment document.

complete 메서드는 반드시 아래 순서대로 동작해야합니다. [MUST]

The complete method MUST act as follows:

promise를 새 Promise로 합니다.
Let promise be a new Promise.
만약 내장 슬롯 [[completeCalled]]의 값이 true라면 InvalidStateError를 던집니다.
If the value of the internal slot [[completeCalled]] is true, then throw an InvalidStateError.
내장 슬롯 [[completeCalled]]의 값을 true로 설정합니다.
Set the value of the internal slot [[completeCalled]] to true.
promise를 반환하고 남은 스텝을 비동기로 수행합니다.
Return promise and asynchronously perform the remaining steps.
success 값을 결제 요청을 허용하는 Payment App으로 전달합니다.
Pass the value of success to the Payment App that accepted the payment request.
남아있는 유저 인터페이스를 닫습니다.
Close down any remaining user interface.
promise를 undefined로 해결합니다.
Resolve promise with undefined.

Issue 5: Should the web page be able to provide status information before calling complete()

There is an open issue about whether there should be a way for a merchant to keep the user informed about the progress of a transaction after the user approves the payment request.

11.2 내장 슬롯

PaymentResponse의 인스턴스는 아래 표의 내장 슬롯과 함께 생성됩니다.

Instances of PaymentResponse are created with the internal slots in the following table:

내장 슬롯	설명 (표준이 아님)
[[completeCalled]]	만약 `complete` 메서드가 호출되었다면 true, 그 외의 경우 false true if the `complete` method has been called and false otherwise.

12. 이벤트

12.1 개요

이 섹션은 표준에 준하지 않습니다.

이벤트 이름	인터페이스	언제 전달되는 지...
`shippingaddresschange`	`PaymentRequestUpdateEvent`	유저가 새로운 배송지를 제공한다. The user provides a new shipping address.
`shippingoptionchange`	`PaymentRequestUpdateEvent`	유저가 새로운 배송 옵션을 선택한다. The user chooses a new shipping option.

12.2 PaymentRequestUpdateEvent

[Constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict)]
interface PaymentRequestUpdateEvent : Event {
    void updateWith(Promise<PaymentDetails> d);
};

dictionary PaymentRequestUpdateEventInit : EventInit {
};

PaymentRequestUpdateEvent 는 웹 페이지가 유저 인터렉션에 반응하여 결제 요청 디테일을 업데이트 할 수 있게 합니다.

The PaymentRequestUpdateEvent enables the web page to update the details of the payment request in response to a user interaction.

만약 웹 페이지가 결제 요청을 갱신하기를 원한다면 updateWith를 호출하고, 유저 에이전트가 유저에게 보여주는 [user agent SHOULD] 변경 값을 포함하는 PaymentDetails 사전과 함께 해결되는 promise를 제공해야 합니다.

If the web page wishes to update the payment request then it should call updateWith and provide a promise that will resolve with a PaymentDetails dictionary containing changed values that the user agent SHOULD present to the user.

PaymentRequestUpdateEvent 생성자는 반드시 내장 슬롯 [[waitForUpdate]]를 false로 해야합니다. [MUST]

The PaymentRequestUpdateEvent constructor MUST set the internal slot [[waitForUpdate]] to false.

updateWith 메서드는 반드시 아래 순서대로 동작해야합니다. [MUST]

The updateWith method MUST act as follows:

target을 이벤트의 타겟인 PaymentRequest 객체로 합니다.
Let target be the PaymentRequest object that is the target of the event.
만약 dispatch flag가 지정되지 않았다면, a href="#dfn-invalidstateerror" class="internalDFN" data-link-type="dfn">InvalidStateError를 던집니다.
If the dispatch flag is unset, then throw an InvalidStateError.
만약 [[waitForUpdate]]가 true라면 InvalidStateError를 던집니다.
If [[waitForUpdate]] is true, then throw an InvalidStateError.
target@[[state]]가 interactive가 아니라면, InvalidStateError를 던집니다.
If target@[[state]] is not interactive, then throw an InvalidStateError.
target@[[updating]]가 true라면, InvalidStateError를 던집니다.
If target@[[updating]] is true, then throw an InvalidStateError.
stop propagation flag와 stop immediate propagation flag를 설정합니다.
Set the stop propagation flag and stop immediate propagation flag.
[[waitForUpdate]]를 true로 설정합니다.
Set [[waitForUpdate]] to true.
target@[[updating]]를 true로 설정합니다.
Set target@[[updating]] to true.
유저 에이전트는 유저가 허락한 결제 요청을 허용하는 유저 인터페이스를 비활성화해야합니다. [user agent SHOULD] 웹 페이지가 변경을 요청한 내용이 변경되기 전에 이 결제가 허용되지 않게 하기 위함입니다. 웹페이지는 반드시 결제 요청이 유효함을 다시 나타내기 위해 promise d를 해결해야합니다. [MUST]
The user agent SHOULD disable the user interface that allows the user to accept the payment request. This is to ensure that the payment is not accepted until the web page has made changes required by the change. The web page MUST settle the promise d to indicate that the payment request is valid again.

유저 에이전트는 다른 갱신 이벤트 발생을 박기 위해 유저 인터페이스의 모든 부분을 비활성화해야합니다. [SHOULD] 한번에 하나의 갱신만 처리합니다.

The user agent SHOULD disable any part of the user interface that could cause another update event to be fired. Only one update may be processed at a time.

Issue: Consider adding a timeout to the updating flag in case page doesn't resolve promise from updateWith
We should consider adding a timeout mechanism so that if the page never resolves the promise within a reasonable amount of time then the user agent behaves as if the promise was rejected.
메서드로부터 반환받고 나머지 스텝을 비동기로 수행합니다.
Return from the method and asynchronously perform the remaining steps.
d가 놓일 때까지 기다립니다.
Wait until d settles.
만약 d가 details와 함께 해결되었고 details가 PaymentDetails 사전이라면:
If d is resolved with details and details is a PaymentDetails dictionary, then:
1. 만약 details가 items 값을 가진다면, 이 값을 target@[[details]]의 items 필드에 복사합니다.
  If details contains an items value, then copy this value to the items field of target@[[details]].
2. 만약 details가 shippingOptions 시퀀스를 가진다면, 이 값을 target@[[details]]의 shippingOptions 필드에 복사합니다.
  If details contains a shippingOptions sequence, then copy this value to the shippingOptions field of target@[[details]].
3. newOption을 null로 합니다.
  Let newOption be null.
4. 만약 details가 shippingOptions 시퀀스를 가지고 그 길이가 1이라면, newOption을 시퀀스 내 단일 ShippingOption의 id로 설정합니다.
  If details contains a shippingOptions sequence with a length of 1, then set newOption to the id of the only ShippingOption in the sequence.
5. target의 shippingOption 값을 newOption으로 설정합니다.
  Set the value of shippingOption on target to newOption.
[[waitForUpdate]]를 fasle로 설정합니다.
Set [[waitForUpdate]] to false.
target@[[updating]]을 false로 설정합니다.
Set target@[[updating]] to false.
유저 에이전트는 target 안의 변경 값을 기반으로 유저 인터페이스를 갱신합니다. 유저 에이전트는 필요한 경우 위 스텝에서 비활성화 시켰을 수도 있는 사용자 인터페이스를 다시 사용하도록 설정해야 합니다. [SHOULD]
The user agent should update the user interface based on any changed values in target. The user agent SHOULD re-enable user interface elements that might have been disabled in the steps above if appropriate.

13. 알고리즘

PaymentRequest 객체의 내장 슬롯 [[state]]가 interactive로 지정되었을 때, 유저 에이전트는 아래 알고리즘을 유저 인터렉션을 기반으로 일으켜야합니다.

When the internal slot [[state]] of a PaymentRequest object is set to interactive, the user agent will trigger the following algorithms based on user interaction.

13.1 배송지 변경 알고리즘

배송지 변경 알고리즘은 유저가 새 배송지를 제공했을 때 동작합니다. 이는 반드시 아래 순서대로 동작해야합니다. [MUST]

The shipping address changed algorithm runs when the user provides a new shipping address. It MUST run the following steps:

request를 사용자와 인터렉션하는 PaymentRequest 객체로 합니다.
Let request be the PaymentRequest object that the user is interacting with.
name을 shippingaddresschange로 합니다.
Let name be shippingaddresschange.
request의 shippingAddress 속성을 유저가 제공한 배송지로 설정합니다.
Set the shippingAddress attribute on request to the shipping address provided by the user.
request 및 name과 함께 PaymentRequest 갱신 알고리즘을 돌립니다.
Run the PaymentRequest updated algorithm with request and name.

13.2 배송 옵션 변경 알고리즘

배송 옵션 변경 알고리즘은 유저가 새로운 배송 옵션을 선택했을 때 동작합니다. 이는 반드시 아래 순서대로 동작해야합니다. [MUST]

The shipping option changed algorithm runs when the user chooses a new shipping option. It MUST run the following steps:

request를 사용자와 인터렉션하는 PaymentRequest 객체로 합니다.
Let request be the PaymentRequest object that the user is interacting with.
name을 shippingoptionchange로 합니다.
Let name be shippingoptionchange.
request의 shippingOption 속성을 유저가 제공한 ShippingOption의 id 문자열로 설정합니다.
Set the shippingOption attribute on request to the id string of the ShippingOption provided by the user.
request 및 name과 함께 PaymentRequest 갱신 알고리즘을 돌립니다.
Run the PaymentRequest updated algorithm with request and name.

13.3 PaymentRequest 갱신 알고리즘

PaymentRequest 갱신 알고리즘은 유저가 name의 이벤트 네임과 함께 request로 호출되는 PaymentRequest를 변경을 나타내기 위해 이벤트를 발생시키는 위의 다른 알고리즘에 의해 동작합니다.

The PaymentRequest updated algorithm is run by other algorithms above to fire an event to indicate that a user has made a change to a PaymentRequest called request with an event name of name.

It MUST run the following steps:

request@[[updating]]이 true라면, 이 알고리즘을 제거하고 추후 조치를 취하지 않습니다. 한번에 하나의 업데이트만 가능합니다. 이 일은 발생해서는 안됩니다.
If the request@[[updating]] is true, then terminate this algorithm and take no further action. Only one update may take place at a time. This should never occur.
request@[[state]]가 interactive로 설정되어있지 않다면 이 알고리즘을 제거하고 추후 조치를 취하지 않습니다. 유저 에이전트 유저 인터페이스는 이런 일이 일어나지 않도록 안전하게 해야합니다.
If the request@[[state]] is not set to interactive, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
event를 새 PaymentRequestUpdateEvent로 합니다.
Let event be a new PaymentRequestUpdateEvent.
request에 따라 event 타입의 name으로 정의된 이벤트의 작동을 작업 대기열에 담을 수 있습니다.
Queue a task to fire an event named name of type event at request.

13.4 유저 에이전트 위임 결제 요청 알고리즘

The PaymentRequest interface allows a web page to call abort to tell the user agent to abort the payment request and to tear down any user interface that might be shown. For example, a web page may choose to do this the goods they are selling are only available for a limited amount of time. If the user does not accept the payment request within the allowed time period, then the request will be aborted.

A user agent may not always be able to abort a request. For example, if the user agent has delegated responsibility for the request to another app. To support this situation, the user agent must run the User agent delegates payment request algorithm. The algorithm MUST run the following steps:

Let request be the PaymentRequest object that the user is interacting with.
If the request@[[updating]] is true, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
If the request@[[state]] is not interactive, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
Set request@[[state]] to delegated.

Issue 39: How are web-based payment apps supported?

The architecture document suggests that payment apps may take numerous forms, including as web-based apps. This specification should describe how the user-agent will pass the payment request data and the complete signal to a web-based payment app and also how it will receive the payment response from the payment app.

Issue 7: Should we support a delegated state for PaymentRequest?

We believe there are user agent configurations that can cause the UI to get into a state where cancellation by the web page during user interaction is difficult. Users should still be able to cancel the payment but script will not be able to. We need to investigate in more detail the consequences of this and whether it is really needed.

If we specify delegated then it isn't necessary for all user agents to be able to move to this state but it would be necessary for all payment flows that wish to call abort to account for the situation where this may fail in the delegated state.

Issue 50: How are payment requests and responses passed between the browser and third-party native wallets?

This specification should describe how the user agent will pass the payment request data and the complete signal to a native payment app and also how it will receive the payment response from the payment app.

13.5 User accepts the payment request algorithm

The user accepts the payment request algorithm runs when the user accepts the payment request and confirms that they want to pay. It MUST run the following steps:

Let request be the PaymentRequest object that the user is interacting with.
If the request@[[updating]] is true, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
If request@[[state]] is not interactive and the not delegated, then terminate this algorithm and take no further action. The user agent user interface should ensure that this never occurs.
If the requestShipping value of request@[[options]] is true, then if the shippingAddress attribute of request is null or if the shippingOption attribute of request is null, then terminate this algorithm and take no further action. This should never occur.
Let response be a new PaymentResponse.
Set the methodName attribute value of response to the payment method identifier for the payment method that the user selected to accept the payment.
Set the details attribute value of response to a JSON-serializable object containing the payment method specific message used by the merchant to process the transaction. The format of this response will be defined by a Payment Transaction Message Specification.
Set response@[[completeCalled]] to false.
Set request@[[state]] to closed.
Resolve the pending promise request@[[acceptPromise]].

A.1 Normative references

[DOM4]: Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C. W3C DOM4. 19 November 2015. W3C Recommendation. URL: http://www.w3.org/TR/dom/
[ECMA-262-2015]: Allen Wirfs-Brock. Ecma International. ECMA-262 6th Edition, The ECMAScript 2015 Language Specification. June 2015. Standard. URL: http://www.ecma-international.org/ecma-262/6.0/index.html
[HTML5]: Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. W3C. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[ISO4217]: ISO 4217: Codes for the representation of currencies and funds. ISO.
[METHODIDENTIFIERS]: Adrian Bateman; Zach Koch; Richard Barnes; Roy McElmurry. Payment Method Identifiers. W3C Editor's Draft. URL: https://www.w3.org/TR/payment-method-id/
[POWERFUL-FEATURES]: Mike West. W3C. Secure Contexts. 13 April 2016. W3C Working Draft. URL: http://www.w3.org/TR/powerful-features/
[RFC2119]: S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]: Cameron McCormack; Boris Zbarsky. W3C. WebIDL Level 1. 8 March 2016. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL-1/

A.2 Informative references

[PAYMENTARCH]: Adrian Bateman; Zach Koch; Richard Barnes; Roy McElmurry. Payment Request Architecture. W3C Editor's Draft. URL: https://w3c.github.io/browser-payment-api/specs/architecture.html