@tosspayments/tosspayments-sdk 2.9.0 → 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/types/index.d.ts +472 -45
package/package.json
CHANGED
package/types/index.d.ts
CHANGED
|
@@ -1,20 +1,321 @@
|
|
|
1
1
|
declare function clearTossPayments(): void;
|
|
2
2
|
|
|
3
|
-
// standard-public-interfaces 2.
|
|
3
|
+
// standard-public-interfaces 2.22.2 — 자동 생성 파일입니다. 직접 수정하지 마세요.
|
|
4
4
|
|
|
5
|
+
/**
|
|
6
|
+
* 구매자가 결제 UI에서 선택한 결제수단입니다. `method`로 결제가 처리되는 경로를 알 수 있고, 카드사, 간편결제사, 계좌이체 제공자 같은 상세 정보는 수단별 객체(`card`, `transfer`, `brandpay`, `custom` 등)에 담겨요.
|
|
7
|
+
*/
|
|
5
8
|
type WidgetSelectedPaymentMethod = {
|
|
6
9
|
/**
|
|
7
|
-
*
|
|
10
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요 — 카드사는 `card.cardCompany`, 앱카드는 `card.useAppCardOnly`와 `card.appCard`, 간편결제사는 `card.easyPay`, 계좌이체 제공자는 `transfer.provider`.
|
|
11
|
+
* `code`는 결제 어드민의 노출 방식에 따라 달라질 수 있어요. 예를 들어 카드 아래에서 신한카드를 고르면 `CARD`, 결제수단 목록에서 바로 신한카드를 고르면 `SHINHAN`이 응답돼요.
|
|
12
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
13
|
+
*/
|
|
14
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
15
|
+
/**
|
|
16
|
+
* 결제가 처리되는 경로입니다. 일반결제는 결제수단 이름(`CARD`, `TRANSFER` 등)이고, 브랜드페이는 `BRANDPAY`, 키인은 `KEYIN`, 커스텀 결제수단은 `CUSTOM`이에요. 간편결제와 앱카드는 카드로 결제되므로 `CARD`예요.
|
|
17
|
+
*/
|
|
18
|
+
method: 'CARD';
|
|
19
|
+
/**
|
|
20
|
+
* 카드로 결제할 때의 정보입니다. `method`가 `CARD`일 때 응답돼요. 간편결제와 앱카드도 여기에 담겨요.
|
|
21
|
+
*/
|
|
22
|
+
card: {
|
|
23
|
+
/**
|
|
24
|
+
* 카드사 코드입니다. 카드사를 아직 고르지 않았으면 응답되지 않아요. 주문서형에서는 카드사를 고르면 `paymentMethodSelect` 이벤트가 다시 발행됩니다. [기관 코드](/codes/org-codes)를 참고하세요.
|
|
25
|
+
*/
|
|
26
|
+
cardCompany?: WidgetsCardCompanyCode;
|
|
27
|
+
/**
|
|
28
|
+
* 간편결제사 코드입니다(예: `TOSSPAY`). 간편결제가 아니면 응답되지 않아요.
|
|
29
|
+
*/
|
|
30
|
+
easyPay?: WidgetsEasyPayCode;
|
|
31
|
+
/**
|
|
32
|
+
* `true`면 구매자가 앱카드 버튼을 골라 카드사 앱으로 결제돼요. 결제 요청 시 SDK가 알아서 진행하므로 이 값을 `requestPayment()`에 넘길 필요는 없어요. 앱카드 전용 할인을 선택한 것과는 다른 값이에요.
|
|
33
|
+
*/
|
|
34
|
+
useAppCardOnly?: boolean;
|
|
35
|
+
/**
|
|
36
|
+
* 앱카드 코드입니다(예: `KBPAY`). 표시 이름이 아니라 식별 코드라 앱 이름이 바뀌어도 유지돼요. 앱카드가 아니면 응답되지 않아요.
|
|
37
|
+
*/
|
|
38
|
+
appCard?: WidgetsAppCardCode;
|
|
39
|
+
};
|
|
40
|
+
} | {
|
|
41
|
+
/**
|
|
42
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
43
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
44
|
+
*/
|
|
45
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
46
|
+
method: 'FOREIGN_EASY_PAY';
|
|
47
|
+
/**
|
|
48
|
+
* 해외 간편결제 정보입니다. `method`가 `FOREIGN_EASY_PAY`일 때 응답돼요.
|
|
49
|
+
*/
|
|
50
|
+
foreignEasyPay: {
|
|
51
|
+
/**
|
|
52
|
+
* 해외 간편결제사 코드입니다(예: `PAYPAL`).
|
|
53
|
+
*/
|
|
54
|
+
provider: WidgetsForeignEasyPayCode;
|
|
55
|
+
};
|
|
56
|
+
} | {
|
|
57
|
+
/**
|
|
58
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
59
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
60
|
+
*/
|
|
61
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
62
|
+
method: 'TRANSFER';
|
|
63
|
+
/**
|
|
64
|
+
* 계좌이체 정보입니다. `method`가 `TRANSFER`일 때 응답돼요.
|
|
65
|
+
*/
|
|
66
|
+
transfer: {
|
|
67
|
+
/**
|
|
68
|
+
* 오픈뱅킹 이체는 `TOSS_PAYMENTS`, 뱅크페이 이체는 `BANKPAY`로 응답돼요. 제공자가 구분되지 않는 일반 계좌이체는 응답되지 않아요.
|
|
69
|
+
*/
|
|
70
|
+
provider?: 'TOSS_PAYMENTS' | 'BANKPAY';
|
|
71
|
+
};
|
|
72
|
+
} | {
|
|
73
|
+
/**
|
|
74
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
75
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
76
|
+
*/
|
|
77
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
78
|
+
method: 'VIRTUAL_ACCOUNT';
|
|
79
|
+
} | {
|
|
80
|
+
/**
|
|
81
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
82
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
83
|
+
*/
|
|
84
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
85
|
+
method: 'MOBILE_PHONE';
|
|
86
|
+
} | {
|
|
87
|
+
/**
|
|
88
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
89
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
90
|
+
*/
|
|
91
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
92
|
+
method: 'CULTURE_GIFT_CERTIFICATE';
|
|
93
|
+
} | {
|
|
94
|
+
/**
|
|
95
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
96
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
97
|
+
*/
|
|
98
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
99
|
+
method: 'GAME_GIFT_CERTIFICATE';
|
|
100
|
+
} | {
|
|
101
|
+
/**
|
|
102
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
103
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
104
|
+
*/
|
|
105
|
+
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
106
|
+
method: 'BOOK_GIFT_CERTIFICATE';
|
|
107
|
+
} | {
|
|
108
|
+
/**
|
|
109
|
+
* 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드입니다. 새 연동에서는 `method`와 수단별 객체를 쓰세요.
|
|
110
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
8
111
|
*/
|
|
9
112
|
code: Exclude<WidgetsPaymentMethodCode, 'BRANDPAY'>;
|
|
113
|
+
method: 'KEYIN';
|
|
10
114
|
} | {
|
|
115
|
+
/**
|
|
116
|
+
* 브랜드페이는 `code`가 항상 `BRANDPAY`예요.
|
|
117
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 수단별 객체를 사용해주세요. 값은 그대로 유지됩니다.
|
|
118
|
+
*/
|
|
11
119
|
code: 'BRANDPAY';
|
|
120
|
+
method: 'BRANDPAY';
|
|
12
121
|
/**
|
|
13
|
-
* 현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다.
|
|
122
|
+
* 현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. `brandpay.methodId`와 같은 값이에요.
|
|
123
|
+
* @deprecated 이전 버전 호환용입니다. `brandpay.methodId`를 사용해주세요. 값은 그대로 유지됩니다.
|
|
14
124
|
*/
|
|
15
125
|
methodId?: string;
|
|
126
|
+
/**
|
|
127
|
+
* 브랜드페이로 결제할 때의 정보입니다. `method`가 `BRANDPAY`일 때 응답돼요.
|
|
128
|
+
*/
|
|
129
|
+
brandpay: {
|
|
130
|
+
/**
|
|
131
|
+
* 현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다. 등록된 결제수단이 없거나 아직 목록을 불러오기 전이면 응답되지 않아요.
|
|
132
|
+
* 주문서형에서는 목록이 준비되면 `paymentMethodSelect` 이벤트가 한 번 발행되니 그때 다시 읽으세요.
|
|
133
|
+
*/
|
|
134
|
+
methodId?: string;
|
|
135
|
+
/**
|
|
136
|
+
* 현재 브랜드페이에서 선택되어 있는 결제수단의 종류입니다. 카드면 `CARD`, 계좌면 `ACCOUNT`예요.
|
|
137
|
+
* `methodId`와 같은 조건으로 응답되지 않을 수 있어요.
|
|
138
|
+
*/
|
|
139
|
+
method?: 'CARD' | 'ACCOUNT';
|
|
140
|
+
};
|
|
141
|
+
} | {
|
|
142
|
+
/**
|
|
143
|
+
* 커스텀 결제수단의 `code`는 결제 어드민에 등록한 `key` 원문이라 일반 결제수단 코드와 같을 수 있어요(예: `key`가 `CARD`). 커스텀 여부는 `method === 'CUSTOM'`으로만 판정하세요.
|
|
144
|
+
* @deprecated 이전 버전 호환용입니다. `method`와 `custom.key`를 사용해주세요. 값은 그대로 유지됩니다.
|
|
145
|
+
*/
|
|
146
|
+
code: string;
|
|
147
|
+
method: 'CUSTOM';
|
|
148
|
+
/**
|
|
149
|
+
* 커스텀 결제수단 정보입니다. `method`가 `CUSTOM`일 때 응답돼요.
|
|
150
|
+
*/
|
|
151
|
+
custom: {
|
|
152
|
+
/**
|
|
153
|
+
* 결제 어드민에 등록한 커스텀 결제수단의 `key` 값입니다. `code`와 같은 값이에요.
|
|
154
|
+
*/
|
|
155
|
+
key: string;
|
|
156
|
+
};
|
|
157
|
+
};
|
|
158
|
+
/**
|
|
159
|
+
* 카드사 코드입니다. [기관 코드](/codes/org-codes)를 참고하세요. SDK 가 아는 카드사만 응답되므로 이 목록 밖의 값은 오지 않아요.
|
|
160
|
+
*/
|
|
161
|
+
type WidgetsCardCompanyCode = 'SHINHAN' | 'HYUNDAI' | 'SAMSUNG' | 'WOORI' | 'KOOKMIN' | 'LOTTE' | 'NONGHYEOP' | 'HANA' | 'BC' | 'KDBBANK' | 'TOSSBANK' | 'KAKAOBANK' | 'SUHYEOP' | 'JEONBUKBANK' | 'KBANK' | 'POST' | 'SAEMAUL' | 'CITI' | 'SAVINGBANK' | 'JEJUBANK' | 'GWANGJUBANK' | 'SHINHYEOP' | 'JCB' | 'UNIONPAY' | 'MASTER' | 'VISA' | 'DINERS' | 'DISCOVER' | 'IBK_BC' | 'AMEX';
|
|
162
|
+
/**
|
|
163
|
+
* 간편결제사 코드입니다.
|
|
164
|
+
*/
|
|
165
|
+
type WidgetsEasyPayCode = 'TOSSPAY' | 'NAVERPAY' | 'SAMSUNGPAY' | 'LPAY' | 'KAKAOPAY' | 'PAYCO' | 'SSG' | 'APPLEPAY' | 'PINPAY';
|
|
166
|
+
/**
|
|
167
|
+
* 앱카드 코드입니다.
|
|
168
|
+
*/
|
|
169
|
+
type WidgetsAppCardCode = 'KBPAY';
|
|
170
|
+
/**
|
|
171
|
+
* 해외 간편결제사 코드입니다.
|
|
172
|
+
*/
|
|
173
|
+
type WidgetsForeignEasyPayCode = 'PAYPAL' | 'GCASH' | 'TOUCHNGO' | 'BOOST' | 'BPI' | 'BILLEASE' | 'DANA' | 'ALIPAYHK' | 'TRUEMONEY' | 'RABBIT_LINE_PAY' | 'ALIPAY' | 'PAYPAY';
|
|
174
|
+
/**
|
|
175
|
+
* 결제 UI의 화면 항목 코드입니다. 결제수단, 카드사, 간편결제사, 계좌이체 제공자가 한 자리에 섞여 있어요.
|
|
176
|
+
*/
|
|
177
|
+
type WidgetsPaymentMethodCode = 'CARD' | 'VIRTUAL_ACCOUNT' | 'MOBILE_PHONE' | 'TRANSFER' | 'CULTURE_GIFT_CERTIFICATE' | 'GAME_GIFT_CERTIFICATE' | 'BOOK_GIFT_CERTIFICATE' | WidgetsEasyPayCode | WidgetsAppCardCode | WidgetsForeignEasyPayCode | WidgetsCardCompanyCode | 'TOSS_PAYMENTS' | 'BANKPAY' | 'BRANDPAY' | 'KEYIN' | (NonNullable<unknown> & string);
|
|
178
|
+
|
|
179
|
+
interface Amount {
|
|
180
|
+
/**
|
|
181
|
+
* 결제 금액입니다.
|
|
182
|
+
*/
|
|
183
|
+
value: number;
|
|
184
|
+
/**
|
|
185
|
+
* 결제 통화입니다. 일반결제는 `KRW`만 지원합니다. 해외 간편결제(PayPal)는 `USD`만 지원합니다.
|
|
186
|
+
*/
|
|
187
|
+
currency: string;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
type WithRedirection<T> = T & {
|
|
191
|
+
/**
|
|
192
|
+
* 결제 요청이 성공하면 리다이렉트되는 URL입니다. `https://www.example.com/success`와 같이 오리진을 포함한 형태로 설정해주세요.
|
|
193
|
+
* 리다이렉트되면 URL의 쿼리 파라미터로 `amount`, `orderId`, `paymentKey`가 추가돼요.
|
|
194
|
+
*/
|
|
195
|
+
successUrl?: string | null;
|
|
196
|
+
/**
|
|
197
|
+
* 결제 요청이 실패하면 리다이렉트되는 URL입니다. `https://www.example.com/fail`와 같이 오리진을 포함한 형태로 설정해주세요.
|
|
198
|
+
* 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
|
|
199
|
+
*/
|
|
200
|
+
failUrl?: string | null;
|
|
201
|
+
};
|
|
202
|
+
|
|
203
|
+
type SelectedPaymentMethodOf<Method extends WidgetSelectedPaymentMethod['method']> = Extract<WidgetSelectedPaymentMethod, {
|
|
204
|
+
method: Method;
|
|
205
|
+
}>;
|
|
206
|
+
/**
|
|
207
|
+
* 구매자가 고른 결제수단으로 어떻게 결제되는지를 담은 값입니다.
|
|
208
|
+
*
|
|
209
|
+
* `getSelectedPaymentMethod()`가 무엇을 골랐는지라면, 이 값은 그 수단으로 얼마를 어떤 조건(할부, 카드포인트, 즉시할인, 입금기한)으로
|
|
210
|
+
* 결제하는지예요. 선택한 결제수단을 그대로 품고 있어서 `method`와 수단별 객체를 같은 방식으로 읽을 수 있어요.
|
|
211
|
+
*
|
|
212
|
+
* 주문서형은 `paymentMethodWidget.getSelectedPaymentInfo()`로 조회하고, 결제창형은 `paymentRequest` 이벤트의 `paymentInfo`로 받아요.
|
|
213
|
+
* 결제 요청에 넘기는 값이 아니라서 `requestPayment()`에 전달하지 않아요 — 결제 요청 때 SDK가 알아서 실어요.
|
|
214
|
+
*/
|
|
215
|
+
type WidgetSelectedPaymentInfo = (SelectedPaymentMethodOf<'CARD'> & {
|
|
216
|
+
/**
|
|
217
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
218
|
+
*/
|
|
219
|
+
amount: Amount;
|
|
220
|
+
card: {
|
|
221
|
+
/**
|
|
222
|
+
* 구매자가 선택한 할부 개월 수입니다. `0`은 일시불이에요.
|
|
223
|
+
*/
|
|
224
|
+
cardInstallmentPlan?: number;
|
|
225
|
+
/**
|
|
226
|
+
* 구매자의 카드사 포인트 사용 선택 여부입니다.
|
|
227
|
+
*/
|
|
228
|
+
useCardPoint?: boolean;
|
|
229
|
+
/**
|
|
230
|
+
* 결제수단에 적용된 즉시 할인(프로모션) 코드입니다. 조회하거나 결제하기를 누른 시점의 결제 금액으로 계산돼요.
|
|
231
|
+
*/
|
|
232
|
+
discountCode?: string;
|
|
233
|
+
};
|
|
234
|
+
}) | (SelectedPaymentMethodOf<'FOREIGN_EASY_PAY'> & {
|
|
235
|
+
/**
|
|
236
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
237
|
+
*/
|
|
238
|
+
amount: Amount;
|
|
239
|
+
}) | (SelectedPaymentMethodOf<'TRANSFER'> & {
|
|
240
|
+
/**
|
|
241
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
242
|
+
*/
|
|
243
|
+
amount: Amount;
|
|
244
|
+
}) | (SelectedPaymentMethodOf<'VIRTUAL_ACCOUNT'> & {
|
|
245
|
+
/**
|
|
246
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
247
|
+
*/
|
|
248
|
+
amount: Amount;
|
|
249
|
+
/**
|
|
250
|
+
* 가상계좌 정보입니다. `method`가 `VIRTUAL_ACCOUNT`일 때 응답돼요.
|
|
251
|
+
*/
|
|
252
|
+
virtualAccount: {
|
|
253
|
+
/**
|
|
254
|
+
* 결제 어드민의 가상계좌 설정에 따라 계산된 입금기한입니다. 조회하거나 결제하기를 누른 시점 기준이라 결제 요청 시점에 다시 계산될 수 있어요.
|
|
255
|
+
* `Payment.virtualAccount.dueDate`와 같은 오프셋 포함 형식이에요(예: `2026-09-16T23:59:59+09:00`).
|
|
256
|
+
* `requestPayment()`의 `dueDate`는 오프셋 없이 한국 시각으로 적는 요청 형식이라 서로 달라요.
|
|
257
|
+
*/
|
|
258
|
+
dueDate: string;
|
|
259
|
+
};
|
|
260
|
+
}) | (SelectedPaymentMethodOf<'MOBILE_PHONE' | 'CULTURE_GIFT_CERTIFICATE' | 'GAME_GIFT_CERTIFICATE' | 'BOOK_GIFT_CERTIFICATE' | 'KEYIN'> & {
|
|
261
|
+
/**
|
|
262
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
263
|
+
*/
|
|
264
|
+
amount: Amount;
|
|
265
|
+
}) | (SelectedPaymentMethodOf<'BRANDPAY'> & {
|
|
266
|
+
/**
|
|
267
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
268
|
+
*/
|
|
269
|
+
amount: Amount;
|
|
270
|
+
brandpay: {
|
|
271
|
+
/**
|
|
272
|
+
* 구매자가 선택한 할부 개월 수입니다. `0`은 일시불이에요.
|
|
273
|
+
*/
|
|
274
|
+
cardInstallmentPlan?: number;
|
|
275
|
+
/**
|
|
276
|
+
* 구매자의 카드사 포인트 사용 선택 여부입니다.
|
|
277
|
+
*/
|
|
278
|
+
useCardPoint?: boolean;
|
|
279
|
+
/**
|
|
280
|
+
* 결제수단에 적용된 즉시 할인(프로모션) 코드입니다. 조회하거나 결제하기를 누른 시점의 결제 금액으로 계산돼요.
|
|
281
|
+
*/
|
|
282
|
+
discountCode?: string;
|
|
283
|
+
/**
|
|
284
|
+
* 구매자가 브랜드페이에서 선택한 현금영수증 발급 정보입니다.
|
|
285
|
+
*/
|
|
286
|
+
cashReceipt?: WidgetCashReceipt;
|
|
287
|
+
};
|
|
288
|
+
}) | (SelectedPaymentMethodOf<'CUSTOM'> & {
|
|
289
|
+
/**
|
|
290
|
+
* 결제 UI에 설정된 결제 금액입니다.
|
|
291
|
+
*/
|
|
292
|
+
amount: Amount;
|
|
293
|
+
});
|
|
294
|
+
/**
|
|
295
|
+
* 현금영수증 발급 정보입니다.
|
|
296
|
+
*/
|
|
297
|
+
type WidgetCashReceipt = {
|
|
298
|
+
/**
|
|
299
|
+
* 현금영수증 발급 용도입니다. `소득공제`, `지출증빙`, `미발행` 중 하나예요.
|
|
300
|
+
*/
|
|
301
|
+
type: '소득공제';
|
|
302
|
+
/**
|
|
303
|
+
* 현금영수증 발급 번호의 종류입니다. 휴대폰 번호는 `MOBILE`, 현금영수증 카드는 `CASH_RECEIPT_CARD`, 사업자등록번호는 `BUSINESS_REGISTRATION`이에요. `미발행`이면 응답되지 않아요.
|
|
304
|
+
*/
|
|
305
|
+
registrationNumberType: 'MOBILE' | 'CASH_RECEIPT_CARD';
|
|
306
|
+
/**
|
|
307
|
+
* 현금영수증 발급 번호입니다. `미발행`이면 응답되지 않아요.
|
|
308
|
+
*/
|
|
309
|
+
registrationNumber: string;
|
|
310
|
+
} | {
|
|
311
|
+
type: '지출증빙';
|
|
312
|
+
registrationNumberType: 'BUSINESS_REGISTRATION' | 'CASH_RECEIPT_CARD';
|
|
313
|
+
registrationNumber: string;
|
|
314
|
+
} | {
|
|
315
|
+
type: '미발행';
|
|
316
|
+
registrationNumberType?: never;
|
|
317
|
+
registrationNumber?: never;
|
|
16
318
|
};
|
|
17
|
-
type WidgetsPaymentMethodCode = 'CARD' | 'VIRTUAL_ACCOUNT' | 'MOBILE_PHONE' | 'TRANSFER' | 'CULTURE_GIFT_CERTIFICATE' | 'GAME_GIFT_CERTIFICATE' | 'BOOK_GIFT_CERTIFICATE' | 'TOSSPAY' | 'NAVERPAY' | 'SAMSUNGPAY' | 'LPAY' | 'KAKAOPAY' | 'PAYCO' | 'SSG' | 'APPLEPAY' | 'PINPAY' | 'KBPAY' | 'PAYPAL' | 'GCASH' | 'TOUCHNGO' | 'BOOST' | 'BPI' | 'BILLEASE' | 'DANA' | 'ALIPAYHK' | 'TRUEMONEY' | 'RABBIT_LINE_PAY' | 'ALIPAY' | 'SHINHAN' | 'HYUNDAI' | 'SAMSUNG' | 'WOORI' | 'KOOKMIN' | 'LOTTE' | 'NONGHYEOP' | 'HANA' | 'BC' | 'KDBBANK' | 'TOSSBANK' | 'KAKAOBANK' | 'SUHYEOP' | 'JEONBUKBANK' | 'KBANK' | 'POST' | 'SAEMAUL' | 'CITI' | 'SAVINGBANK' | 'JEJUBANK' | 'GWANGJUBANK' | 'SHINHYEOP' | 'JCB' | 'UNIONPAY' | 'MASTER' | 'VISA' | 'DINERS' | 'DISCOVER' | 'IBK_BC' | 'AMEX' | 'TOSS_PAYMENTS' | 'BANKPAY' | 'BRANDPAY' | 'KEYIN' | (NonNullable<unknown> & string);
|
|
18
319
|
|
|
19
320
|
interface WidgetPaymentMethodWidget {
|
|
20
321
|
/**
|
|
@@ -23,24 +324,26 @@ interface WidgetPaymentMethodWidget {
|
|
|
23
324
|
* @example
|
|
24
325
|
* ```javascript
|
|
25
326
|
* paymentMethodWidget.on('paymentMethodSelect', selectedPaymentMethod => {
|
|
26
|
-
if (selectedPaymentMethod.
|
|
27
|
-
// 카드 안내사항
|
|
327
|
+
if (selectedPaymentMethod.method === 'CARD') {
|
|
328
|
+
// 카드 안내사항 노출. 카드사를 골랐다면 selectedPaymentMethod.card.cardCompany 로 알 수 있어요.
|
|
28
329
|
}
|
|
29
|
-
if (selectedPaymentMethod.
|
|
330
|
+
if (selectedPaymentMethod.method === 'CUSTOM' && selectedPaymentMethod.custom.key === '문화바우처') {
|
|
30
331
|
// 커스텀 결제수단 (결제 Pro 플랜 기능)
|
|
31
332
|
// 문화바우처 안내사항 노출
|
|
32
333
|
}
|
|
33
334
|
});
|
|
34
335
|
* ```
|
|
35
336
|
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
337
|
+
* 최초 렌더 후에는 이벤트가 발행되지 않아요. 렌더 직후 `getSelectedPaymentMethod()`를 한 번 호출해 초기 선택을 읽으세요. 브랜드페이만 예외로 마운트 시 발행됩니다.
|
|
338
|
+
*
|
|
339
|
+
* @param {'paymentMethodSelect'} eventName 구독할 이벤트입니다. `paymentMethodSelect` 이벤트로 구매자가 선택한 결제수단을 확인하세요.
|
|
340
|
+
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다. 콜백 파라미터로 구매자가 선택한 결제수단(`selectedPaymentMethod`)이 전달돼요. [getSelectedPaymentMethod()](#paymentmethodwidgetgetselectedpaymentmethod)의 응답과 같은 값이에요. `method`로 결제가 처리되는 경로를, 수단별 객체(`card`, `transfer`, `brandpay`, `custom` 등)로 카드사, 간편결제사, 계좌이체 제공자를 알 수 있어요. 결제 Pro 플랜으로 [커스텀 결제수단](/guides/v2/payment-widget/pro/integration-custom)을 연동했다면 `method`가 `CUSTOM`이고 `custom.key`에 결제 어드민에서 설정한 `key` 값이 응답돼요. `code`는 이전 버전과의 호환을 위해 남아 있는 화면 항목 코드예요.
|
|
38
341
|
*
|
|
39
342
|
* @throws {@link PublicError.Widgets.InvalidEventParameterError} eventName이 유효하지 않은 경우
|
|
40
343
|
* @throws {@link PublicError.Widgets.InvalidCallbackParameterError} callback이 유효하지 않은 경우
|
|
41
344
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
42
345
|
*/
|
|
43
|
-
on: (eventName: 'paymentMethodSelect', callback: (
|
|
346
|
+
on: (eventName: 'paymentMethodSelect', callback: (selectedPaymentMethod: WidgetSelectedPaymentMethod) => void) => void;
|
|
44
347
|
/**
|
|
45
348
|
* 구매자가 선택한 결제수단을 불러옵니다. [자세히 >](#paymentmethodwidgetgetselectedpaymentmethod)
|
|
46
349
|
*
|
|
@@ -49,9 +352,33 @@ interface WidgetPaymentMethodWidget {
|
|
|
49
352
|
* const paymentMethod = await paymentMethodWidget.getSelectedPaymentMethod();
|
|
50
353
|
* ```
|
|
51
354
|
*
|
|
355
|
+
* 최초 렌더 직후의 기본 선택과 이전 결제수단 복원은 `paymentMethodSelect` 이벤트가 발행되지 않으므로, 렌더 직후 이 메서드로 초기 선택을 읽으세요.
|
|
356
|
+
* SDK 가 아직 모르는 결제수단이 선택되어 있으면 `UnknownError`가 발생해요.
|
|
357
|
+
*
|
|
52
358
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
53
359
|
*/
|
|
54
360
|
getSelectedPaymentMethod: () => Promise<WidgetSelectedPaymentMethod>;
|
|
361
|
+
/**
|
|
362
|
+
* 구매자가 고른 결제수단으로 어떻게 결제되는지를 불러옵니다. [자세히 >](#paymentmethodwidgetgetselectedpaymentinfo)
|
|
363
|
+
*
|
|
364
|
+
* @example
|
|
365
|
+
* ```javascript
|
|
366
|
+
* const selectedPaymentInfo = await paymentMethodWidget.getSelectedPaymentInfo();
|
|
367
|
+
*
|
|
368
|
+
* if (selectedPaymentInfo.method === 'CARD') {
|
|
369
|
+
* console.log(selectedPaymentInfo.card.cardInstallmentPlan); // 구매자가 선택한 할부 개월 수
|
|
370
|
+
* }
|
|
371
|
+
* ```
|
|
372
|
+
*
|
|
373
|
+
* `getSelectedPaymentMethod()`가 무엇을 골랐는지라면, 이 메서드는 그 수단으로 얼마를 어떤 조건(할부, 카드포인트, 즉시할인, 입금기한)으로 결제하는지예요.
|
|
374
|
+
* 조회 전용 값이라 `requestPayment()`에 전달하지 않아요 — 결제 요청 때 SDK가 알아서 실어요.
|
|
375
|
+
* 결제 금액을 바꾼 뒤 조회하면 바뀐 금액 기준으로 결제 UI가 가진 현재 상태를 그대로 돌려줘요. 예를 들어 새 금액에서 고를 수 없게 된 할부 개월은 기본값으로 돌아가요.
|
|
376
|
+
* 값은 부르는 시점에 계산돼요. 저장해 두고 재사용하지 말고, 결제 금액이나 할부 같은 결제 조건을 화면에 보여줄 때, `setAmount()`를 호출한 뒤, `requestPayment()`를 호출하기 직전에 다시 부르세요. `paymentMethodSelect` 이벤트(브랜드페이는 결제수단을 바꿀 때도 발행돼요)가 오면 다시 읽으세요.
|
|
377
|
+
*
|
|
378
|
+
* @throws {@link PublicError.Widgets.NotSelectedPaymentMethodError} 결제수단이 선택되지 않은 경우
|
|
379
|
+
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
380
|
+
*/
|
|
381
|
+
getSelectedPaymentInfo: () => Promise<WidgetSelectedPaymentInfo>;
|
|
55
382
|
/**
|
|
56
383
|
* 결제 UI 객체를 제거합니다. [자세히 >](#paymentmethodwidgetdestroy)
|
|
57
384
|
*
|
|
@@ -65,13 +392,34 @@ interface WidgetPaymentMethodWidget {
|
|
|
65
392
|
destroy: () => Promise<void>;
|
|
66
393
|
}
|
|
67
394
|
|
|
395
|
+
/**
|
|
396
|
+
* 구매자의 약관 동의 상태입니다.
|
|
397
|
+
*/
|
|
68
398
|
interface WidgetAgreementStatus {
|
|
399
|
+
/**
|
|
400
|
+
* 구매자가 모든 필수 약관에 동의했는지 알려줍니다.
|
|
401
|
+
*/
|
|
69
402
|
agreedRequiredTerms: boolean;
|
|
403
|
+
/**
|
|
404
|
+
* 개별 약관에 동의했는지 알려줍니다.
|
|
405
|
+
*/
|
|
70
406
|
agreements: Array<{
|
|
407
|
+
/**
|
|
408
|
+
* 약관 정보입니다.
|
|
409
|
+
*/
|
|
71
410
|
term: {
|
|
411
|
+
/**
|
|
412
|
+
* 약관의 식별자입니다.
|
|
413
|
+
*/
|
|
72
414
|
id: string;
|
|
415
|
+
/**
|
|
416
|
+
* 약관의 필수 여부입니다.
|
|
417
|
+
*/
|
|
73
418
|
required: boolean;
|
|
74
419
|
};
|
|
420
|
+
/**
|
|
421
|
+
* 구매자의 약관 동의 여부입니다.
|
|
422
|
+
*/
|
|
75
423
|
agreed: boolean;
|
|
76
424
|
}>;
|
|
77
425
|
}
|
|
@@ -81,7 +429,7 @@ interface WidgetAgreementWidget {
|
|
|
81
429
|
* 약관 UI의 이벤트를 구독합니다. [자세히 >](#agreementwidgeton)
|
|
82
430
|
*
|
|
83
431
|
* @param {'agreementStatusChange'} eventName 구독할 이벤트입니다. `agreementStatusChange` 이벤트로 구매자가 약관에 동의했는지 확인하세요.
|
|
84
|
-
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
|
|
432
|
+
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다. 콜백 파라미터로 구매자의 약관 동의 상태(`agreementStatus`)가 전달돼요.
|
|
85
433
|
*
|
|
86
434
|
* @example
|
|
87
435
|
* ```javascript
|
|
@@ -153,6 +501,14 @@ interface WidgetPaymentRequest {
|
|
|
153
501
|
* 결제 관련 정보를 추가할 수 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍을 자유롭게 추가해주세요. 키는 `[` , `]` 를 사용하지 않는 최대 40자의 문자열, 값은 최대 2000자의 문자열입니다.
|
|
154
502
|
*/
|
|
155
503
|
metadata?: Record<string | symbol | number, unknown> | null;
|
|
504
|
+
/**
|
|
505
|
+
* @ignore
|
|
506
|
+
*/
|
|
507
|
+
orderProductCode?: string | null;
|
|
508
|
+
/**
|
|
509
|
+
* @ignore
|
|
510
|
+
*/
|
|
511
|
+
shippingAddress?: string | null;
|
|
156
512
|
/**
|
|
157
513
|
* @ignore
|
|
158
514
|
*/
|
|
@@ -184,6 +540,22 @@ interface WidgetPaymentRequest {
|
|
|
184
540
|
*/
|
|
185
541
|
challengeMode?: 'CHALLENGE_REQUIRED' | null;
|
|
186
542
|
} | null;
|
|
543
|
+
/**
|
|
544
|
+
* @ignore
|
|
545
|
+
*/
|
|
546
|
+
affiliateCards?: Array<{
|
|
547
|
+
issuerCode: string;
|
|
548
|
+
cardProductCode: string;
|
|
549
|
+
}> | null;
|
|
550
|
+
/**
|
|
551
|
+
* @ignore
|
|
552
|
+
*/
|
|
553
|
+
dividedSettlements?: Array<{
|
|
554
|
+
subMid: string;
|
|
555
|
+
amount: number;
|
|
556
|
+
taxFreeAmount: number;
|
|
557
|
+
productInfo: string;
|
|
558
|
+
}> | null;
|
|
187
559
|
} | null;
|
|
188
560
|
/**
|
|
189
561
|
* 구매자가 계좌이체를 선택하면 결제에 적용되는 옵션입니다.
|
|
@@ -224,6 +596,19 @@ interface WidgetPaymentRequest {
|
|
|
224
596
|
* 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
|
|
225
597
|
*/
|
|
226
598
|
isCulturalExpenses?: boolean | null;
|
|
599
|
+
/**
|
|
600
|
+
* @ignore
|
|
601
|
+
*/
|
|
602
|
+
showSecuritiesAccount?: boolean | null;
|
|
603
|
+
/**
|
|
604
|
+
* @ignore
|
|
605
|
+
*/
|
|
606
|
+
dividedSettlements?: Array<{
|
|
607
|
+
subMid: string;
|
|
608
|
+
amount: number;
|
|
609
|
+
taxFreeAmount: number;
|
|
610
|
+
productInfo: string;
|
|
611
|
+
}> | null;
|
|
227
612
|
} | null;
|
|
228
613
|
/**
|
|
229
614
|
* 구매자가 가상계좌를 선택하면 결제에 적용되는 옵션입니다.
|
|
@@ -389,30 +774,6 @@ interface WidgetPaymentRequest {
|
|
|
389
774
|
}> | null;
|
|
390
775
|
}
|
|
391
776
|
|
|
392
|
-
interface Amount {
|
|
393
|
-
/**
|
|
394
|
-
* 결제 금액입니다.
|
|
395
|
-
*/
|
|
396
|
-
value: number;
|
|
397
|
-
/**
|
|
398
|
-
* 결제 통화입니다. 일반결제는 `KRW`만 지원합니다. 해외 간편결제(PayPal)는 `USD`만 지원합니다.
|
|
399
|
-
*/
|
|
400
|
-
currency: string;
|
|
401
|
-
}
|
|
402
|
-
|
|
403
|
-
type WithRedirection<T> = T & {
|
|
404
|
-
/**
|
|
405
|
-
* 결제 요청이 성공하면 리다이렉트되는 URL입니다. `https://www.example.com/success`와 같이 오리진을 포함한 형태로 설정해주세요.
|
|
406
|
-
* 리다이렉트되면 URL의 쿼리 파라미터로 `amount`, `orderId`, `paymentKey`가 추가돼요.
|
|
407
|
-
*/
|
|
408
|
-
successUrl?: string | null;
|
|
409
|
-
/**
|
|
410
|
-
* 결제 요청이 실패하면 리다이렉트되는 URL입니다. `https://www.example.com/fail`와 같이 오리진을 포함한 형태로 설정해주세요.
|
|
411
|
-
* 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
|
|
412
|
-
*/
|
|
413
|
-
failUrl?: string | null;
|
|
414
|
-
};
|
|
415
|
-
|
|
416
777
|
type WidgetPaymentResult = {
|
|
417
778
|
/**
|
|
418
779
|
* 결제 타입입니다. `NORMAL`(일반결제), `BRANDPAY`(브랜드페이) 중 하나입니다.
|
|
@@ -459,7 +820,7 @@ interface WidgetPaymentWindow {
|
|
|
459
820
|
* 결제창 이벤트를 구독합니다. [자세히 >](#paymentwindowon)
|
|
460
821
|
*
|
|
461
822
|
* @param {'paymentRequest' | 'cancel'} eventName 구독할 이벤트입니다. `paymentRequest`로 구매자의 결제 요청을 받아 [widgets.requestPayment()](#widgetsrequestpayment)를 호출하고, `cancel`로 구매자가 결제를 포기한 순간을 감지할 수 있어요.
|
|
462
|
-
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다. `paymentRequest`는 콜백 파라미터로 `paymentMethod`
|
|
823
|
+
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다. `paymentRequest`는 콜백 파라미터로 `paymentMethod`와 `paymentInfo`가 전달돼요. `paymentMethod`는 [getSelectedPaymentMethod()](/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentmethod)와 같은 선택 결제수단이고, `paymentInfo`는 [getSelectedPaymentInfo()](/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentinfo)와 같은 결제 정보로 `paymentMethod`를 모두 포함해요. `paymentInfo`는 구매자가 고른 결제 조건을 확인하는 값이라 `requestPayment()`에 전달하지 않아요. 두 값은 구매자가 결제하기를 누른 시점의 값이에요. 콜백 안에서 `setAmount()`로 금액을 바꿨다면 결제를 요청하지 말고 구매자가 결제하기를 다시 누르게 하세요.
|
|
463
824
|
*
|
|
464
825
|
* @throws {@link PublicError.Widgets.InvalidEventParameterError} eventName이 유효하지 않은 경우
|
|
465
826
|
* @throws {@link PublicError.Widgets.InvalidCallbackParameterError} callback이 유효하지 않은 경우
|
|
@@ -482,23 +843,37 @@ interface WidgetPaymentWindow {
|
|
|
482
843
|
* @docsAlias paymentRequest 이벤트
|
|
483
844
|
*
|
|
484
845
|
* @param {'paymentRequest'} eventName 구독할 이벤트입니다. `paymentRequest` 이벤트로 구매자의 결제 요청을 수신하세요.
|
|
485
|
-
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
|
|
846
|
+
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다. 콜백 파라미터로 `paymentMethod`와 `paymentInfo`가 전달돼요. `paymentMethod`는 [getSelectedPaymentMethod()](/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentmethod)와 같은 선택 결제수단이고, `paymentInfo`는 [getSelectedPaymentInfo()](/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentinfo)와 같은 결제 정보로 `paymentMethod`를 모두 포함해요. `paymentInfo`는 구매자가 고른 결제 조건을 확인하는 값이라 `requestPayment()`에 전달하지 않아요. 두 값은 구매자가 결제하기를 누른 시점의 값이에요. 콜백 안에서 `setAmount()`로 금액을 바꿨다면 결제를 요청하지 말고 구매자가 결제하기를 다시 누르게 하세요.
|
|
486
847
|
*
|
|
487
848
|
* @example
|
|
488
849
|
* ```javascript
|
|
489
|
-
* paymentWindow.on('paymentRequest', ({ paymentMethod }) => {
|
|
850
|
+
* paymentWindow.on('paymentRequest', async ({ paymentMethod, paymentInfo }) => {
|
|
851
|
+
* if (paymentInfo.method === 'CARD') {
|
|
852
|
+
* console.log(paymentInfo.card.cardInstallmentPlan); // 구매자가 선택한 할부 개월 수
|
|
853
|
+
* }
|
|
490
854
|
* // 결제 요청 처리
|
|
491
855
|
* });
|
|
492
856
|
* ```
|
|
493
857
|
*/
|
|
494
|
-
type WidgetPaymentWindowOnPaymentRequest = (eventName: 'paymentRequest', callback: (
|
|
858
|
+
type WidgetPaymentWindowOnPaymentRequest = (eventName: 'paymentRequest', callback: (
|
|
859
|
+
/**
|
|
860
|
+
* 결제 요청 정보입니다.
|
|
861
|
+
*/
|
|
862
|
+
params: {
|
|
863
|
+
/**
|
|
864
|
+
* 구매자가 선택한 결제수단입니다. 주문서형 [getSelectedPaymentMethod()](/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentmethod)의 응답과 같은 값이에요.
|
|
865
|
+
*/
|
|
495
866
|
paymentMethod: WidgetSelectedPaymentMethod;
|
|
867
|
+
/**
|
|
868
|
+
* 구매자가 고른 결제 금액과 결제 조건입니다. 주문서형 [getSelectedPaymentInfo()](/sdk/v2/js/payment-widget#paymentmethodwidgetgetselectedpaymentinfo)의 응답과 같은 값이에요. `requestPayment()`에 전달하지 않아요.
|
|
869
|
+
*/
|
|
870
|
+
paymentInfo: WidgetSelectedPaymentInfo;
|
|
496
871
|
}) => Promise<void>) => void;
|
|
497
872
|
/**
|
|
498
873
|
* @docsAlias cancel 이벤트
|
|
499
874
|
*
|
|
500
875
|
* @param {'cancel'} eventName 구독할 이벤트입니다. `cancel` 이벤트로 구매자가 결제를 포기했는지 확인하세요. 구매자가 결제창을 닫으면 결제창이 사라진 뒤에 콜백이 호출돼요. `paymentWindow.destroy()`로 결제창을 닫은 경우에는 호출되지 않아요.
|
|
501
|
-
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다.
|
|
876
|
+
* @param {function} callback 이벤트가 일어나면 호출되는 콜백 함수입니다. 콜백 파라미터는 없어요.
|
|
502
877
|
*
|
|
503
878
|
* @example
|
|
504
879
|
* ```javascript
|
|
@@ -530,6 +905,7 @@ type WidgetPaymentWindowOnCancel = (eventName: 'cancel', callback: () => Promise
|
|
|
530
905
|
* @throws {@link PublicError.Widgets.InvalidSelectorError} selector 가 유효하지 않은 경우
|
|
531
906
|
* @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
532
907
|
* @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
908
|
+
* @throws {@link PublicError.Widgets.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
533
909
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
534
910
|
*/
|
|
535
911
|
type RenderPaymentMethods = (params: {
|
|
@@ -563,6 +939,7 @@ type RenderPaymentMethods = (params: {
|
|
|
563
939
|
* @throws {@link PublicError.Widgets.InvalidVariantKeyError} variantKey 가 유효하지 않은 경우
|
|
564
940
|
* @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
565
941
|
* @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
942
|
+
* @throws {@link PublicError.Widgets.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
566
943
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
567
944
|
*/
|
|
568
945
|
type RenderAgreement = (params: {
|
|
@@ -602,6 +979,7 @@ type RenderAgreement = (params: {
|
|
|
602
979
|
* @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
603
980
|
* @throws {@link PublicError.Widgets.InvalidMetadataError} metadata가 올바르지 않은 경우
|
|
604
981
|
* @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
982
|
+
* @throws {@link PublicError.Widgets.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
605
983
|
* @throws {@link PublicError.Widgets.BelowZeroAmountError} 결제 금액이 0원 미만인 경우
|
|
606
984
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
607
985
|
*/
|
|
@@ -668,6 +1046,7 @@ type RequestPaymentWithRedirection$1 = (paymentRequest: WithRedirection<WidgetPa
|
|
|
668
1046
|
* @throws {@link PublicError.Widgets.InvalidAmountValueError} 결제 금액이 유효하지 않은 경우
|
|
669
1047
|
* @throws {@link PublicError.Widgets.InvalidAmountCurrencyError} 결제 금액의 통화가 유효하지 않은 경우
|
|
670
1048
|
* @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1049
|
+
* @throws {@link PublicError.Widgets.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
671
1050
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
672
1051
|
*/
|
|
673
1052
|
type SetAmount = (amount: Amount) => Promise<void>;
|
|
@@ -693,6 +1072,7 @@ type SetAmount = (amount: Amount) => Promise<void>;
|
|
|
693
1072
|
* @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
694
1073
|
* @throws {@link PublicError.Widgets.InvalidMetadataError} metadata가 올바르지 않은 경우
|
|
695
1074
|
* @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1075
|
+
* @throws {@link PublicError.Widgets.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
696
1076
|
* @throws {@link PublicError.Widgets.BelowZeroAmountError} 결제 금액이 0원 미만인 경우
|
|
697
1077
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
698
1078
|
*/
|
|
@@ -784,6 +1164,7 @@ type RequestPaymentWindowWithRedirection = (paymentRequest: WithRedirection<Widg
|
|
|
784
1164
|
* @throws {@link PublicError.Widgets.InvalidVariantKeyError} variantKey가 유효하지 않은 경우
|
|
785
1165
|
* @throws {@link PublicError.Widgets.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
786
1166
|
* @throws {@link PublicError.Widgets.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1167
|
+
* @throws {@link PublicError.Widgets.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
787
1168
|
* @throws {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
788
1169
|
*/
|
|
789
1170
|
type RenderPaymentWindow = (params?: {
|
|
@@ -962,8 +1343,17 @@ interface BasicCashReceipt {
|
|
|
962
1343
|
registrationNumberType?: 'CASH_RECEIPT_CARD' | 'BUSINESS_REGISTRATION' | 'MOBILE';
|
|
963
1344
|
}
|
|
964
1345
|
interface 소득공제_현금영수증 extends BasicCashReceipt {
|
|
1346
|
+
/**
|
|
1347
|
+
* 현금영수증 발급 용도입니다. `소득공제`, `지출증빙`, `미발행` 중 하나예요.
|
|
1348
|
+
*/
|
|
965
1349
|
type: '소득공제';
|
|
1350
|
+
/**
|
|
1351
|
+
* 현금영수증 발급 번호의 종류입니다. 휴대폰 번호는 `MOBILE`, 현금영수증 카드는 `CASH_RECEIPT_CARD`, 사업자등록번호는 `BUSINESS_REGISTRATION`이에요. `미발행`이면 넣지 않아요.
|
|
1352
|
+
*/
|
|
966
1353
|
registrationNumberType: 'MOBILE' | 'CASH_RECEIPT_CARD';
|
|
1354
|
+
/**
|
|
1355
|
+
* 현금영수증 발급 번호입니다. `미발행`이면 넣지 않아요.
|
|
1356
|
+
*/
|
|
967
1357
|
registrationNumber: string;
|
|
968
1358
|
}
|
|
969
1359
|
interface 지출증빙_현금영수증 extends BasicCashReceipt {
|
|
@@ -1010,6 +1400,7 @@ interface BrandpayRequestPaymentResult {
|
|
|
1010
1400
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1011
1401
|
* @throws {@link PublicError.Brandpay.InvalidMetadataError} metadata가 올바르지 않은 경우
|
|
1012
1402
|
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1403
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1013
1404
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1014
1405
|
*/
|
|
1015
1406
|
type RequestPayment$1 = RequestPaymentWithPromise & RequestPaymentWithRedirection;
|
|
@@ -1078,6 +1469,7 @@ type RequestPaymentWithPromise = (paymentRequest: BrandpayPaymentRequest) => Pro
|
|
|
1078
1469
|
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1079
1470
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1080
1471
|
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1472
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1081
1473
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1082
1474
|
*
|
|
1083
1475
|
* @returns
|
|
@@ -1098,6 +1490,7 @@ type ChangePassword = () => Promise<void>;
|
|
|
1098
1490
|
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1099
1491
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1100
1492
|
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1493
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1101
1494
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1102
1495
|
*
|
|
1103
1496
|
* @returns
|
|
@@ -1118,6 +1511,7 @@ type AddPaymentMethod = () => Promise<void>;
|
|
|
1118
1511
|
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1119
1512
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1120
1513
|
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1514
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1121
1515
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1122
1516
|
*/
|
|
1123
1517
|
type OpenSettings = () => Promise<void>;
|
|
@@ -1136,6 +1530,7 @@ type OpenSettings = () => Promise<void>;
|
|
|
1136
1530
|
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1137
1531
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1138
1532
|
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1533
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1139
1534
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1140
1535
|
*
|
|
1141
1536
|
* @returns
|
|
@@ -1157,6 +1552,7 @@ type ChangeOneTouchPay = () => Promise<void>;
|
|
|
1157
1552
|
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1158
1553
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1159
1554
|
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1555
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1160
1556
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1161
1557
|
*/
|
|
1162
1558
|
type IsOneTouchPayEnabled = () => Promise<{
|
|
@@ -1177,10 +1573,32 @@ type IsOneTouchPayEnabled = () => Promise<{
|
|
|
1177
1573
|
* @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 자동결제 인증창을 닫은 경우
|
|
1178
1574
|
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1179
1575
|
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1576
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1180
1577
|
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1181
1578
|
*/
|
|
1182
1579
|
type RequestBillingAuth$1 = () => Promise<void>;
|
|
1183
1580
|
|
|
1581
|
+
/**
|
|
1582
|
+
* 결제 내역을 안내받을 이메일 주소를 변경합니다
|
|
1583
|
+
*
|
|
1584
|
+
*
|
|
1585
|
+
* @example
|
|
1586
|
+
* ```javascript
|
|
1587
|
+
* brandpay.changeEmail();
|
|
1588
|
+
* ```
|
|
1589
|
+
*
|
|
1590
|
+
* @throws {@link PublicError.Brandpay.UserCancelError} 사용자가 이메일 변경을 취소한 경우
|
|
1591
|
+
* @throws {@link PublicError.Brandpay.NotRegisteredRedirectUrlError} redirectUrl이 등록되지 않은 경우
|
|
1592
|
+
* @throws {@link PublicError.Brandpay.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1593
|
+
* @throws {@link PublicError.Brandpay.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
1594
|
+
* @throws {@link PublicError.Brandpay.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1595
|
+
* @throws {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1596
|
+
*
|
|
1597
|
+
* @returns
|
|
1598
|
+
*
|
|
1599
|
+
*/
|
|
1600
|
+
type ChangeEmail = () => Promise<void>;
|
|
1601
|
+
|
|
1184
1602
|
interface TossPaymentsBrandpay {
|
|
1185
1603
|
/**
|
|
1186
1604
|
* 브랜드페이 결제창을 띄웁니다. [자세히 >](#brandpayrequestpayment)
|
|
@@ -1190,6 +1608,10 @@ interface TossPaymentsBrandpay {
|
|
|
1190
1608
|
* 브랜드페이 결제 비밀번호를 변경하는 창을 띄웁니다. [자세히 >](#brandpaychangepassword)
|
|
1191
1609
|
*/
|
|
1192
1610
|
changePassword: ChangePassword;
|
|
1611
|
+
/**
|
|
1612
|
+
* 결제 내역을 안내받을 이메일 주소를 변경하는 창을 띄웁니다. [자세히 >](#brandpaychangeemail)
|
|
1613
|
+
*/
|
|
1614
|
+
changeEmail: ChangeEmail;
|
|
1193
1615
|
/**
|
|
1194
1616
|
* 브랜드페이에 새로운 결제수단을 추가합니다. [자세히 >](#brandpayaddpaymentmethod)
|
|
1195
1617
|
*/
|
|
@@ -1902,6 +2324,7 @@ type BillingAuthRequest = CardBillingAuthRequest | TransferBillingAuthRequest;
|
|
|
1902
2324
|
* @throws {@link PublicError.Payment.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
1903
2325
|
* @throws {@link PublicError.Payment.InvalidMetadataError} metadata가 올바르지 않은 경우
|
|
1904
2326
|
* @throws {@link PublicError.Payment.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
2327
|
+
* @throws {@link PublicError.Payment.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
1905
2328
|
* @throws {@link PublicError.Payment.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
1906
2329
|
*/
|
|
1907
2330
|
type RequestPayment = RequestCardPaymentWithRedirection & RequestCardPaymentWithPromise & RequestVirtualAccountPaymentWithRedirection & RequestVirtualAccountPaymentWithPromise & RequestTransferPaymentWithRedirection & RequestTransferPaymentWithPromise & RequestMobilePhonePaymentWithRedirection & RequestMobilePhonePaymentWithPromise & RequestGiftCertificatePaymentWithRedirection & RequestGiftCertificatePaymentWithPromise & RequestForeignEasyPayPaymentWithRedirection;
|
|
@@ -2271,6 +2694,7 @@ type RequestForeignEasyPayPaymentWithRedirection = (paymentRequest: WithRedirect
|
|
|
2271
2694
|
* @throws {@link PublicError.Payment.IncorrectFailUrlFormatError} 가맹점에서 유효하지 않은 failUrl을 넘겨준 경우
|
|
2272
2695
|
* @throws {@link PublicError.Payment.InvalidMethodTransactionError} 이미 다른 명령을 수행 중인 경우
|
|
2273
2696
|
* @throws {@link PublicError.Payment.InvalidParametersError} 파라미터가 올바르지 않은 경우
|
|
2697
|
+
* @throws {@link PublicError.Payment.InsecureKeyUsageError} 파라미터에 시크릿 키를 넣은 경우
|
|
2274
2698
|
* @throws {@link PublicError.Payment.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
2275
2699
|
*/
|
|
2276
2700
|
type RequestBillingAuth = (billingAuthRequest: BillingAuthRequest) => Promise<void>;
|
|
@@ -2297,7 +2721,7 @@ interface TossPaymentsSDK {
|
|
|
2297
2721
|
*
|
|
2298
2722
|
* @throw {@link PublicError.Widgets.InvalidClientKeyError} clientKey가 올바르지 않은 경우
|
|
2299
2723
|
* @throw {@link PublicError.Widgets.InvalidCustomerKeyError} customerKey가 올바르지 않은 경우
|
|
2300
|
-
* @throw {@link PublicError.Widgets.InsecureKeyUsageError} customerKey
|
|
2724
|
+
* @throw {@link PublicError.Widgets.InsecureKeyUsageError} customerKey나 파라미터에 시크릿 키를 넣은 경우
|
|
2301
2725
|
* @throw {@link PublicError.Widgets.NotSupportedAPIIndividualKeyError} API 개별 연동 키를 clientKey로 사용한 경우
|
|
2302
2726
|
* @throw {@link PublicError.Widgets.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
2303
2727
|
* @returns 아래 메서드를 호출할 수 있는 결제 객체를 반환합니다.
|
|
@@ -2322,7 +2746,7 @@ interface TossPaymentsSDK {
|
|
|
2322
2746
|
*
|
|
2323
2747
|
* @throw {@link PublicError.Brandpay.InvalidClientKeyError} clientKey가 올바르지 않은 경우
|
|
2324
2748
|
* @throw {@link PublicError.Brandpay.InvalidCustomerKeyError} customerKey가 올바르지 않은 경우
|
|
2325
|
-
* @throw {@link PublicError.Brandpay.InsecureKeyUsageError} customerKey
|
|
2749
|
+
* @throw {@link PublicError.Brandpay.InsecureKeyUsageError} customerKey나 파라미터에 시크릿 키를 넣은 경우
|
|
2326
2750
|
* @throw {@link PublicError.Brandpay.NotSupportedWidgetKeyError} 주문서형, 결제창형 연동 키를 clientKey로 사용한 경우
|
|
2327
2751
|
* @throw {@link PublicError.Brandpay.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
2328
2752
|
* @example
|
|
@@ -2342,7 +2766,7 @@ interface TossPaymentsSDK {
|
|
|
2342
2766
|
*
|
|
2343
2767
|
* @throw {@link PublicError.Payment.InvalidClientKeyError} clientKey가 올바르지 않은 경우
|
|
2344
2768
|
* @throw {@link PublicError.Payment.InvalidCustomerKeyError} customerKey가 올바르지 않은 경우
|
|
2345
|
-
* @throw {@link PublicError.Payment.InsecureKeyUsageError} customerKey
|
|
2769
|
+
* @throw {@link PublicError.Payment.InsecureKeyUsageError} customerKey나 파라미터에 시크릿 키를 넣은 경우
|
|
2346
2770
|
* @throw {@link PublicError.Payment.NotSupportedWidgetKeyError} 주문서형, 결제창형 연동 키를 clientKey로 사용한 경우
|
|
2347
2771
|
* @throw {@link PublicError.Payment.UnknownError} 알 수 없는 오류가 발생한 경우
|
|
2348
2772
|
* @example
|
|
@@ -2356,6 +2780,7 @@ interface TossPaymentsSDK {
|
|
|
2356
2780
|
payment: (params: PaymentInitParams) => TossPaymentsPayment;
|
|
2357
2781
|
}
|
|
2358
2782
|
/**
|
|
2783
|
+
* @throw {@link PublicError.InsecureKeyUsageError} clientKey에 시크릿 키를 넣은 경우
|
|
2359
2784
|
* @example
|
|
2360
2785
|
* ```javascript
|
|
2361
2786
|
* // 스크립트 태그 연동방식
|
|
@@ -2367,9 +2792,11 @@ interface TossPaymentsSDK {
|
|
|
2367
2792
|
* const tossPayments = await loadTossPayments("<WidgetClientKey />");
|
|
2368
2793
|
* ```
|
|
2369
2794
|
*
|
|
2370
|
-
* @param {string} clientKey
|
|
2795
|
+
* @param {string} clientKey 토스페이먼츠가 발급하는 클라이언트 키예요. 개발자센터 [API 키 메뉴](https://developers.tosspayments.com/my/api-keys)에서 확인할 수 있어요. 연동하는 제품에 따라 쓰는 키가 다르고, 맞지 않으면 [에러 코드](/sdk/v2/error-codes)를 받아요.
|
|
2796
|
+
*
|
|
2797
|
+
* • **주문서형, 결제창형(구 결제위젯)** — [주문서형, 결제창형 연동 키](/reference/using-api/api-keys#주문서형-결제창형-연동-키), `test_gck`, `live_gck`로 시작해요.
|
|
2371
2798
|
*
|
|
2372
|
-
*
|
|
2799
|
+
* • **자체창형, 결제창(구버전), 브랜드페이, 자동결제(빌링)** — [API 개별 연동 키](/reference/using-api/api-keys#api-개별-연동-키), `test_ck`, `live_ck`로 시작해요.
|
|
2373
2800
|
*
|
|
2374
2801
|
* @returns
|
|
2375
2802
|
* 아래 메서드를 호출할 수 있는 토스페이먼츠 객체를 반환합니다.
|