-
Notifications
You must be signed in to change notification settings - Fork 12
/
api_recurring.html
1584 lines (1525 loc) · 78.8 KB
/
api_recurring.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>토스 자동결제 연동 가이드</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="shortcut icon" href="https://static.toss.im/tds/favicon/favicon.ico"/>
<link rel="icon" type="image/png" sizes="16x16" href="https://static.toss.im/tds/favicon/favicon-16x16.png"/>
<link rel="icon" type="image/png" sizes="32x32" href="https://static.toss.im/tds/favicon/favicon-32x32.png"/>
<link rel="icon" type="image/png" sizes="48x48" href="https://static.toss.im/tds/favicon/favicon-48x48.png"/>
<link rel="icon" type="image/png" sizes="196x196" href="https://static.toss.im/tds/favicon/favicon-196x196.png"/>
<link rel="apple-touch-icon" sizes="57x57" href="https://static.toss.im/tds/favicon/apple-touch-icon-57x57.png"/>
<link rel="apple-touch-icon" sizes="72x72" href="https://static.toss.im/tds/favicon/apple-touch-icon-72x72.png"/>
<link rel="apple-touch-icon" sizes="114x114" href="https://static.toss.im/tds/favicon/apple-touch-icon-114x114.png"/>
<link rel="apple-touch-icon" sizes="120x120" href="https://static.toss.im/tds/favicon/apple-touch-icon-120x120.png"/>
<link rel="apple-touch-icon" sizes="144x144" href="https://static.toss.im/tds/favicon/apple-touch-icon-144x144.png"/>
<link rel="apple-touch-icon" sizes="152x152" href="https://static.toss.im/tds/favicon/apple-touch-icon-152x152.png"/>
<meta name="msapplication-TileImage" content="https://static.toss.im/tds/favicon/mstile-144x144.png"/>
<!-- stylesheets -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" integrity="sha512-dTfge/zgoMYpP7QbHy4gWMEGsbsdZeCXz7irItjcC3sPUFtf0kuFbDz/ixG7ArTxmDjLXDmezHubeNikyKGVyQ==" crossorigin="anonymous">
<link rel="stylesheet" type="text/css" href="https://static.toss.im/tds/current/css/tds.min.css">
<link rel="stylesheet" type="text/css" href="css/prism.css" />
<link rel="stylesheet" type="text/css" href="css/tossdev.css" />
<!-- javascript -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js" integrity="sha512-K1qjQ+NcF2TYO/eI3M6v8EiNYZfA95pQumfvcVrTHtwQVDG+aHRqLi/ETn2uB+1JqwYqVG3LIvdm9lj6imS/pQ==" crossorigin="anonymous"></script>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body id="docs" data-spy="scroll" data-target="#guide" oncontextmenu="return false" ondragstart="return false" >
<!-- Google Tag Manager -->
<noscript>
<iframe src="//www.googletagmanager.com/ns.html?id=GTM-TPTMLG" height="0" width="0" style="display:none;visibility:hidden"></iframe>
</noscript>
<script>
(function (w, d, s, l, i) {
w[l] = w[l] || [];
w[l].push({
'gtm.start': new Date().getTime(),
event: 'gtm.js'
});
var f = d.getElementsByTagName(s)[0],
j = d.createElement(s),
dl = l != 'dataLayer' ? '&l=' + l : '';
j.async = true;
j.src =
'//www.googletagmanager.com/gtm.js?id=' + i + dl;
f.parentNode.insertBefore(j, f);
})(window, document, 'script', 'dataLayer', 'GTM-TPTMLG');
</script>
<!-- End Google Tag Manager -->
<div id="guide">
<div class="logo">
<a href="index.html">
<img class="logo-img" src="https://static.toss.im/tds/icon/svg/logo-only-icon.svg" alt="">
<span>결제 연동 가이드</span>
</a>
</div>
<ul class="menu nav">
<h5>자동결제 API</h5>
<li>
<a href="#intro">개요</a>
</li>
<li>
<a href="#flow">자동결제 flow</a>
</li>
<h5>API 목록</h5>
<li>
<a href="#billing-key">빌링키 생성 요청</a>
</li>
<li>
<a href="#resultcallback">빌링키 처리결과 callback</a>
</li>
<li>
<a href="#bill">자동결제 승인 요청</a>
</li>
<li>
<a href="#refunds">자동결제 환불 요청</a>
</li>
<li>
<a href="#status">결제 상태조회</a>
</li>
<li>
<a href="#billing-key/status">빌링키 상태조회</a>
</li>
<li>
<a href="#remove">빌링키 삭제</a>
</li>
<li>
<a href="#errorcode">결제 에러코드</a>
</li>
</ul>
</div>
<div id="api-docs">
<div id="methods">
<div class="languages">
<a class="language selected" data-lang="curl" href="#">curl</a>
<a class="language" data-lang="java" href="#">Java</a>
<a class="language" data-lang="php" href="#">PHP</a>
<a class="language" data-lang="python" href="#">Python</a>
<a class="language" data-lang="ruby" href="#">Ruby</a>
<a class="language" data-lang="aspnet" href="#">ASP</a>
</div>
<div class="method" id="intro">
<div class="method-section clearfix">
<div class="method-description">
<div class="alert alert-warning" role="alert" style="font-size: 14px;">
<i class="fa fa-exclamation-triangle pull-left" aria-hidden="true" style="margin-top:8px;margin-left:6px"></i>
일반적인 토스 결제의 기본적인 흐름은 <strong>토스 결제 공식 가이드 (http://tossdev.github.io/gettingstarted.html#overview/)</strong> 를 참고할 수 있습니다.
</div>
<h3>개요</h3>
<p>빌링키 방식으로 자동결제를 연동할 수 있도록 구현한 API입니다.<br>
토스 결제서버는 가맹점의 빌링키 생성요청에 따라 구매자가 인증할 수 있는 유니크한 '결제 인증 URL'을 생성하고,<br>
가맹점을 통해 구매자는 토스 앱을 통해 인증을 진행할 수 있습니다.<br>
• 사용자의 유니크한 빌링키가 생성되며, 가맹점은 이 빌링키를 관리하고 필요 시 결제 승인 요청을 할 수 있습니다.<br>
• 토스가 제공하는 자동결제는 '토스머니'와 '카드' 결제수단을 제공합니다. 해당 문서는 자동결제 각 API의 기능을 설명합니다.<br>
• 테스트 계정 및 별도의 SDK 파일을 제공하지 않기에, '토스' 앱 설치 후 최신 버전 사용을 권장합니다. <br>
• 결제 도메인은 운영환경으로 제공되며, 결제에서 사용하는 상점 apiKey 속성에 따라 실제 출금 여부를 판단합니다.<br>
• 테스트 키(sk_test_xxx...)는 실제 출금되지 않으니 충분히 테스트할 수 있습니다.<br>
• 양사 간 계약이 완료된 후 전용 상점정보를 전달하며, 그 전까지는 가이드에 기재된 테스트 apiKey로 진행할 수 있습니다.<br>
<strong>각 API의 응답 필드 및 에러코드는 사전 예고 없이 추가될 수 있으니 추가되더라도 오류가 발생하지 않도록 주의가 필요합니다.</strong></p>
</div>
</div>
</div>
<div class="method" id="flow">
<div class="method-section clearfix">
<div class="method-description">
<h3>자동결제 flow</h3>
<p>
<img src="../images/flow.png" alt="자동결제 flow" style="max-width: 100%; height: auto;" />
</p>
</div>
</div>
</div>
<div class="method" id="billing-key">
<div class="method-section clearfix">
<div class="method-description">
<h3>빌링키 생성 요청</h3>
<p>토스 자동결제를 등록하기 위해서는 사용자를 식별할 수 있는 고유한 빌링키를 생성해야 합니다.<br>
API 요청의 응답으로 성공 여부와 함께 토스 앱 인증 URL을 전달합니다.<br>
빌링키 생성 요청 API 사양은 다음과 같습니다.</p>
<div class="info">
<h4>endpoint</h4>
<div class="field clearfix">
<div class="key">
(POST)
</div>
<div class="desc">
https://pay.toss.im/api/v1/billing-key <br/>
</div>
</div>
</div>
<div class="info">
<h4>parameters</h4>
<div class="field clearfix">
<div class="key">
apiKey
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 30</span>
</div>
<div class="desc">
결제 가맹점의 apiKey
<br>
<span class="text-muted">결제 보안상 유의가 필요하며 웹 브라우저에 노출되지 않도록 가맹점의 관리가 필요합니다.</span><br>
<span class="text-muted">테스트용 apiKey: sk_test_w5iNQvNqa5lNQe03nGx (상점 개선이 있을 때만 발송 예정)</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
userId
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
가맹점 사용자 식별 값
<br>
<span class="text-muted">가맹점에 저장된 회원 아이디를 활용할 수 있습니다.</span><br>
<span class="text-muted">추후 결제 승인 정보와 매칭하기 위하여 필요하며 유니크한 값을 사용하길 권장합니다. (결제 주문번호의 개념)</span><br>
<span class="text-muted">최대 50자로 지정하며 숫자, 영문자도 가능하되 특수문자는 _-:.^@= 만 허용합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
displayId
<span class="type">string</span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
다중 빌링키 식별 값
<br>
<span class="text-muted">빌링키의 경우 기본적으로 하나의 가맹점 - 하나의 토스 유저 - 하나의 빌링키만 사용 가능합니다. 만약 동일한 결제수단을 여러 번 등록하고 싶다면, displayId를 사용하여 여러 개의 빌링키를 생성할 수 있습니다.</span><br>
<span class="text-muted">해당 값은 userId와 함께 발급된 빌링키를 특정할 수 있는 값이므로, 유니크한 값을 사용하길 권장합니다.</span><br>
<span class="text-muted">최대 50자로 지정하며 숫자, 영문자도 가능하되 특수문자는 _-:.^@= 만 허용합니다.</span><br>
<span class="text-muted">만약 동일한 결제수단을 여러 번 등록하길 원한다면, displayId를 보내면서 userId를 다르게 보내야 합니다. 토스에서는 가맹점의 서로 다른 유저에 대한 빌링키 등록으로 인식하여 동일한 결제수단을 여러 번 등록할 수 있게 됩니다. (userId를 동일한 값으로 보내는 경우 동일한 결제수단의 등록은 제한됩니다.)</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
productDesc
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 255</span>
</div>
<div class="desc">
자동결제 상품명
<br>
<span class="text-muted">토스 결제창에 표기될 가맹점의 자동결제 상품명</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
resultCallback
<span class="type">String <font color=#c25300>필수</font></span>
<span class="type">Max Length: 500</span>
</div>
<div class="desc">
가맹점 설정 콜백 URL
<br>
<span class="text-muted">사용자가 토스 앱을 통해 인증을 완료한 후, 이 URL에 인증 결과 데이터를 전달합니다.</span><br>
<span class="text-muted">콜백 서버는 보안상의 이유로 HTTPS를 권장하며, 80, 443 이외의 포트 사용은 불가합니다.</span><br>
<span class="text-muted">웹훅 요청에 대한 자세한 설명은 빌링키 처리결과 callback 설명 참고</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
retAppScheme
<span class="type">string</span>
<span class="type">Max Length: 1500</span>
</div>
<div class="desc">
인증완료 후 연결할 가맹점의 앱 스킴
<br>
<span class="text-muted">토스 결제창 기본적으로 양방향 인증방식을 제공하지만 PC 결제에서는 Web(Web) 이라면 입력하지 않아도 됩니다.</span><br>
<span class="text-muted">모바일 사용자의 경우 리다이렉트 이후 가맹점 앱 실행을 위해 앱 스킴을 포함하는 것을 권장합니다. 예시) `tossapp://`</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
returnSuccessUrl
<span class="type">string</span>
<span class="type">Max Length: 1500</span>
</div>
<div class="desc">
인증성공 후 연결할 가맹점 성공 페이지
<br>
<span class="text-muted">retAppScheme 선언되지 않으면 returnSuccessUrl, returnFailureUrl 은 필수로 보내주셔야 합니다.</span><br>
<span class="text-muted">별도 요청이 완료된 URL로 이동시키며, 빌링키(status), 사용자 식별값(userId), 빌링키(billingKey), 실패 에러코드(errorCode)를 query string 파라미터로 함께 보냅니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
returnFailureUrl
<span class="type">string</span>
<span class="type">Max Length: 1500</span>
</div>
<div class="desc">
인증실패 시 연결할 가맹점 실패 페이지
</div>
</div>
<div class="field clearfix">
<div class="key">
encryptedUserCi
<span class="type">string</span>
<span class="type">Max Length: 255</span>
</div>
<div class="desc">
가맹점 유저의 CI값
<br>
<span class="text-muted">가맹점에서 자동결제를 등록하는 사용자의 실명확인을 통해 생성된 사용자 정보를 전달할 수 있습니다.</span><br>
<span class="text-muted">가맹점에서 직접 자동결제를 등록하는 경우 사용하지 않습니다. CI는 경우 특성 상 여러 값이 생성되지 않아 일회성으로 사용하지 않을 것을 권장합니다.(RSA 암호화방식 지원)</span>
</div>
</div>
</div>
<div class="info">
<h4>response</h4>
<div class="field clearfix">
<div class="key">
code
<span class="type">integer</span>
<span class="type">Max Length: 2 </span>
</div>
<div class="desc">
응답코드
<br/>
<br/>
<table class="table">
<tr>
<td>0</td>
<td>성공</td>
</tr>
<tr>
<td>-1</td>
<td>실패 (실패사유는 msg와 errorCode로 제공)</td>
</tr>
</table>
</div>
</div>
<div class="field clearfix">
<div class="key">
errorCode
<span class="type">string</span>
<span class="type">Max Length: 40</span>
</div>
<div class="desc">
에러코드
<br>
<span class="text-muted">code가 -1일 때만 에러코드와 실패 사유를 전달합니다.</span><br>
</div>
</div>
<div class="field clearfix">
<div class="key">
msg
<span class="type">string</span>
<span class="type">Max Length: 120</span>
</div>
<div class="desc">
에러메시지
<br>
<span class="text-muted">상세한 에러 설명</span><br>
</div>
</div>
<div class="field clearfix">
<div class="key">
billingKey
<span class="type">string</span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
생성된 자동결제 사용자 빌링키
<br>
<span class="text-muted">빌링키는 토스 사용자의 고유한 값으로, 한 상점에서 한 개의 빌링키만 허용합니다.<br>
사용자가 한 상점에서 2개 이상의 상점 계정을 사용하는 경우 혹은 그 외의 경우는 userId로 식별해야 합니다.</span><br>
</div>
</div>
<div class="field clearfix">
<div class="key">
checkoutAndroidUri
<span class="type">string</span>
<span class="type">Max Length: 255</span>
</div>
<div class="desc">
Android 구독 인증 URI
<br>
<span class="text-muted">생성된 자동결제를 인증할 앱 URL. <br>
가맹점은 구매자의 디바이스 OS를 구분해서 해당 URL로 보내주면 됩니다.<br>
앱 링크로 전달하는 이유는 토스앱이 미설치된 사용자에게는 설치를 위해 앱 스토어로 이동시키기 위함이며, 생성요청 시점부터 유효시간은 기본이 15분이며 변경이 불가합니다.(유효시간 만료 후 재사용 불가함)</span><br>
<span class="text-muted">URI 형식은 추후 변경될 수 있으니 변경되더라도 오류가 발생하지 않도록 연동이 필요합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
checkoutIosUri
<span class="type">string</span>
<span class="type">Max Length: 255</span>
</div>
<div class="desc">
iOS 구독 인증 URI
<br>
<span class="text-muted">iOS에서 사용되는 구독 인증 URI로, 토스앱이 설치된 사용자가 앱을 통해 인증을 완료할 수 있도록 합니다.</span><br>
</div>
</div>
<div class="field clearfix">
<div class="key">
checkoutUri
<span class="type">string</span>
<span class="type">Max Length: 255</span>
</div>
<div class="desc">
토스 앱 호출 링크
<br>
<span class="text-muted">요청에서 retAppScheme 포함 여부에 따라 기능이 다른 링크를 생성합니다.<br>
• retAppScheme 가 포함된 경우 : 가맹점에서 사용자 OS 구분이 어렵다면 혼용 가능한 onelink 를 제공합니다. 가맹점 앱에서 토스 앱을 호출하는 기능입니다.<br>
• retAppScheme 가 포함되지 않은 경우 : pay Server 에서는 Web 결제로 인식하여 PC에서 호출 가능한 payfront 링크를 제공합니다. 토스 일반결제의 checkoutPage 의 기능과 같습니다.</span><br>
</div>
</div>
</div>
</div>
<div class="method-example">
<div class="title">Definition</div>
<pre><code class="language-bash always-visible">POST https://pay.toss.im/api/v1/billing-key</code></pre>
<div class="title">Example Request</div>
<pre><code class="curl language-bash">curl https://pay.toss.im/api/v1/billing-key \
-H "Content-Type: application/json" \
-d '{
"apiKey": "example_api_key",
"productDesc": "토스 자동결제 상품",
"userId": "TOSS-TEST-1",
"resultCallback": "https://YOUR-SITE.COM/callback",
"retAppScheme": "testshop://",
"returnSuccessUrl": "https://YOUR-SITE.COM/success",
"returnFailureUrl": "https://YOUR-SITE.COM/fail"
}'</code><code class="java language-java">import java.nio.charset.StandardCharsets;
URL url = null;
URLConnection connection = null;
StringBuilder responseBody = new StringBuilder();
try {
url = new URL("https://pay.toss.im/api/v1/billing-key");
connection = url.openConnection();
connection.addRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
connection.setDoInput(true);
org.json.simple.JSONObject jsonBody = new JSONObject();
jsonBody.put("apiKey", "example_api_key");
jsonBody.put("productDesc", "토스 자동결제 상품");
jsonBody.put("userId", "TOSS-TEST-1");
jsonBody.put("resultCallback", "https://YOUR-SITE.COM/callback");
jsonBody.put("retAppScheme", "testshop://");
jsonBody.put("returnSuccessUrl", "https://YOUR-SITE.COM/success");
jsonBody.put("returnFailureUrl", "https://YOUR-SITE.COM/fail");
BufferedOutputStream bos = new BufferedOutputStream(connection.getOutputStream());
<!--bos.write(jsonBody.toJSONString().getBytes());-->
bos.write(jsonBody.toJSONString().getBytes(StandardCharsets.UTF_8));
bos.flush();
bos.close();
<!--BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));-->
BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8));
String line = null;
while ((line = br.readLine()) != null) {
responseBody.append(line);
}
br.close();
} catch (Exception e) {
responseBody.append(e);
}
System.out.println(responseBody.toString());</code><code class="php language-php">$arrayBody = array();
$arrayBody["apiKey"] = "example_api_key";
$arrayBody["productDesc"] = "토스 자동결제 상품";
$arrayBody["userId"] = "TOSS-TEST-1";
$arrayBody["resultCallback"] = "https://YOUR-SITE.COM/callback";
$arrayBody["retAppScheme"] = "testshop://";
$arrayBody["returnSuccessUrl"] = "https://YOUR-SITE.COM/success";
$arrayBody["returnFailureUrl"] = "https://YOUR-SITE.COM/fail";
$jsonBody = json_encode($arrayBody);
$ch = curl_init('https://pay.toss.im/api/v1/billing-key');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($jsonBody))
);
$result = curl_exec($ch);
curl_close($ch);
echo "Response: ".$result;</code><code class="aspnet language-aspnet">Dim data, httpRequest, postResponse
data = "apiKey=example_api_key"
data = data & "&productDesc=토스 자동결제 상품"
data = data & "&userId=TOSS-TEST-1"
data = data & "&resultCallback=https://YOUR-SITE.COM/callback"
data = data & "&retAppScheme=testshop://"
data = data & "&returnSuccessUrl=https://YOUR-SITE.COM/success"
data = data & "&returnFailureUrl=https://YOUR-SITE.COM/fail"
Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP")
httpRequest.Open "POST", "https://pay.toss.im/api/v1/billing-key", False
httpRequest.SetRequestHeader "Content-Type", "application/json"
httpRequest.Send data
postResponse = httpRequest.ResponseText
Response.Write postResponse</code><code class="python language-python">import urllib, urllib2
url = "https://pay.toss.im/api/v1/billing-key"
params = {
"apiKey": "example_api_key",
"productDesc": "토스 자동결제 상품",
"userId": "TOSS-TEST-1",
"resultCallback": "https://YOUR-SITE.COM/callback",
"retAppScheme": "testshop://",
"returnSuccessUrl": "https://YOUR-SITE.COM/success",
"returnFailureUrl": "https://YOUR-SITE.COM/fail"
}
response = urllib.urlopen(url, urllib.urlencode(params))
print(response.read())</code><code class="ruby language-ruby">require 'net/http'
require 'json'
uri = URI.parse("https://pay.toss.im/api/v1/billing-key")
params = {
"apiKey" => "example_api_key",
"productDesc" => "토스 자동결제 상품",
"userId" => "TOSS-TEST-1",
"resultCallback" => "https://YOUR-SITE.COM/callback",
"retAppScheme" => "testshop://",
"returnSuccessUrl" => "https://YOUR-SITE.COM/success",
"returnFailureUrl" => "https://YOUR-SITE.COM/fail"
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request.set_form_data(params)
response = http.request(request)
p JSON.parse(response.body)</code></pre>
<div class="title">Example Response</div>
<pre><code class="language-javascript always-visible">{
"code": 0,
"billingKey": "example-billingKey",
"checkoutAndroidUri": "intent://pay/BillingKey?billingKey=example-billingKey#Intent;scheme=supertoss;package=viva.republica.toss;end",
"checkoutIosUri": "https://ul.toss.im?scheme=supertoss%3A%2F%2Fpay/BillingKey%3FbillingKey%3Dexample-billingKey",
"checkoutUri": "https://toss.onelink.me/3563614660?pid=referral&af_dp=supertoss%3A%2F%2Fpay%2FbillingKey%3FbillingKey%3Dexample-billingKey%26_minVerAos%3D4.64.0%26_minVerIos%3D4.51.0"
}</code>
</pre>
</div>
</div>
</div>
<div class="method" id="resultcallback">
<div class="method-section clearfix">
<div class="method-description">
<h3>빌링키 처리결과 callback</h3>
<p> 사용자가 토스 앱을 통해 빌링 등록을 '성공적'으로 완료한 경우 토스 Server 는 가맹점이 설정한 resultCallback URL 을 통해 결과를 전달합니다.(실패한 경우는 전달하지 않습니다.)<br>
• 토스 쪽에서 삭제가 발생되는 경우 토스 pay Server 에서 삭제(REMOVED) callback 을 보낼 수 있음을 참고해야 합니다.<br>
• callback 에 대한 응답의 http status code 가 200인 경우에만 '정상' 수신으로 간주하며, 그 외의 응답 코드는 미수신으로 실패한 것으로 인식하여 3분 간격으로 최대 4번 접근을 시도합니다.<br>
• 빌링키 생성결과 callback 의 Payload 는 다음과 같습니다.<br>
<font color="#AA1212"><strong>* 사전 예고 없이 field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.</strong></font>
<div class="info">
<h4>response</h4>
<div class="field clearfix">
<div class="key">
action
<span class="type">string</span>
<span class="type">Max Length: 20 </span>
</div>
<div class="desc">
요청 처리에 따른 빌링키 상태
<br>
<span class="text-muted">• ACTIVATED : 빌링키 활성화 완료<br>
빌링키 생성요청에 따라, 토스 -> 가맹점으로 '정상처리'를 알리는 콜백</span><br>
<span class="text-muted">• REMOVED : 빌링키 삭제 완료<br>
토스 -> 가맹점으로 빌링키 삭제를 요청할 수 있다. 그 때, '삭제완료' 상태를 알리는 콜백</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
processedTs
<span class="type">string</span>
<span class="type">Max Length: 20 </span>
</div>
<div class="desc">
상태 처리시간
<br>
<span class="text-muted">action 에 따라 각 상태의 처리시간을 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
userId
<span class="type">string</span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
가맹점이 생성한 사용자 식별 값
<br>
<span class="text-muted">가맹점의 요청 값 그대로를 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
displayId
<span class="type">string</span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
가맹점이 생성한 표시 가능한 빌링키 식별 값
<br>
<span class="text-muted">가맹점의 요청 값 그대로를 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
billingKey
<span class="type">string</span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
활성화/삭제 자동결제 사용자 빌링키
</div>
</div>
<div class="field clearfix">
<div class="key">
payMethod
<span class="type">string</span>
<span class="type">Max Length: 10</span>
</div>
<div class="desc">
사용자가 토스에서 인증한 결제수단
<br>
<span class="text-muted">선택한 결제수단에 따라 토스머니(TOSS_MONEY) 또는 카드(CARD)를 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardMethodType
<span class="type">string</span>
<span class="type">Max Length: 10</span>
</div>
<div class="desc">
승인된 카드의 타입을 구분
<br>
<span class="text-muted">선택한 결제수단에 따라 신용카드(CREDIT) 또는 체크카드(CHECK) 또는 선불카드(PREPAYMENT)를 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardUserType
<span class="type">string</span>
<span class="type">Max Length: 20</span>
</div>
<div class="desc">
카드 사용자 구분
<br>
<span class="text-muted">• PERSONAL : 본인 카드<br>
• PERSONAL_FAMILY : 가족 카드<br>
• CORP_PERSONAL : 법인정 결제계좌 임직원<br>
• CORP_PRIVATE : 법인 공용<br>
• CORP_COMPANY : 법인정 결제계좌 회사(하나카드만)</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardCompanyNo
<span class="type">integer</span>
<span class="type">Max Length: 2</span>
</div>
<div class="desc">
사용자가 선택한 카드의 카드코드
<br>
<span class="text-muted">사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 토스가 정의한 카드코드를 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardCompanyName
<span class="type">string</span>
<span class="type">Max Length: 2</span>
</div>
<div class="desc">
사용자가 선택한 카드의 카드사명
<br>
<span class="text-muted">사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드사명을 함께 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardNumber
<span class="type">string</span>
<span class="type">Max Length: 20</span>
</div>
<div class="desc">
사용자가 선택한 카드의 번호
<br>
<span class="text-muted">카드번호 16자리 중 중간자리는 마스킹</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardNum4Print
<span class="type">string</span>
<span class="type">Max Length: 4</span>
</div>
<div class="desc">
사용자가 선택한 카드의 끝 4자리
<br>
<span class="text-muted">사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드번호를 포함하여 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardBinNumber
<span class="type">string</span>
<span class="type">Max Length: 8</span>
</div>
<div class="desc">
카드사에서 준 카드 빈번호
<br>
<span class="text-muted">카드의 앞에 있을 수 있으며, 100% 신뢰는 불가</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
accountBankCode
<span class="type">string</span>
<span class="type">Max Length: 3</span>
</div>
<div class="desc">
사용자가 선택한 계좌의 은행코드
<br>
<span class="text-muted">사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행코드를 전달합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
accountBankName
<span class="type">string</span>
<span class="type">Max Length: 20</span>
</div>
<div class="desc">
사용자가 선택한 계좌의 은행명
<br>
<span class="text-muted">은행코드 리스트는 가이드 하단에서 확인 가능</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
accountNumber
<span class="type">string</span>
<span class="type">Max Length: 30</span>
</div>
<div class="desc">
사용자가 선택한 계좌번호
<br>
<span class="text-muted">계좌번호는 일부 마스킹을 포함할 수 있습니다.</span>
</div>
</div>
</div>
</div>
<div class="method-example">
<div class="title">Definition</div>
<pre><code class="language-bash always-visible">POST https://YOUR-SITE.COM/callback (결제 생성 시 가맹점에서 설정한 callback URL)
Content-Type application/json;charset=UTF-8</code></pre>
<div class="title">Example Request</div>
<pre><code class="language-bash always-visible">{
"action": "ACTIVATED",
"processedTs" : "2020-04-01 12:34:11",
"userId": "TOSS-TEST-1",
//"displayId": "TEST_SERVICE_1",
"billingKey": "example-billingKey",
"payMethod" : "TOSS_MONEY",
"accountBankCode" : "88",
"accountBankName" : "신한은행",
"accountNumber" : "110******676"
}
</code></pre>
</div>
</div>
<div class="method" id="bill">
<div class="method-section clearfix">
<div class="method-description">
<h3>자동결제(bill) 승인 요청</h3>
<p>빌링키 생성결과 callback 에서 전달받은 빌링키로 가맹점은 승인요청을 할 수 있습니다.<br>
유효시간이나 최대횟수를 제한하지 않으니 승인요청 API 를 활용해서 결제를 진행할 수 있습니다.<br>
자동결제 승인요청 API spec 은 다음과 같습니다.</br>
<font color="#AA1212"><strong>승인 응답은 가맹점에 예고없이 추가될 수 있으니 오류가 발생하지 않도록 연동 부탁드립니다.</strong></font></p>
<div class="info">
<h4>endpoint</h4>
<div class="field clearfix">
<div class="key">
(POST)
</div>
<div class="desc">
https://pay.toss.im/api/v1/billing-key/bill <br/>
</div>
</div>
</div>
<div class="info">
<h4>parameters</h4>
<div class="field clearfix">
<div class="key">
apiKey
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 30</span>
</div>
<div class="desc">
결제 가맹점의 apiKey
<br>
<span class="text-muted">빌링키 생성요청 시 사용된 apiKey 와 동일해야 합니다.<br>
그렇지 않으면 오류가 발생합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
billingKey
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 50</span>
</div>
<div class="desc">
자동결제 사용자 빌링키
<br>
<span class="text-muted">승인할 사용자의 빌링키</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
orderNo
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 50 </span>
</div>
<div class="desc">
결제 주문번호
<br>
<span class="text-muted">가맹점의 상품 주문번호<br>
• 최대 50자로 지정하며 숫자, 영문자도 가능하되 특수문자는 _-:.^@= 만 허용합니다.<br>
• 가맹점의 주문번호는 매회 유니크한 값으로 생성하길 권장드립니다. (테스트와 라이브 환경에서 중복되지 않아야 합니다.)<br>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
productDesc
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 255 </span>
</div>
<div class="desc">
상품 설명
<br>
<span class="text-muted">결제할 상품 설명</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
amount
<span class="type">Integer<font color=#c25300>필수</font></span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
총 결제 요청 금액
<br>
<span class="text-muted">가맹점의 상품 주문번호<br>
• 토스에서 금액과 관련된 모든 필드는 Number 형태로 선언합니다.<br>
• 필수 체크는 총금액(amount) 과 비과세 금액(amountTaxFree) 만 체크합니다. 판매 상품이 과세 상품이라면 amount 와 amountTaxFree 만 포함하면 되고, 이후 계산은 토스 서버에서 자동으로 계산됩니다.<br>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
amountTaxFree
<span class="type">Integer<font color=#c25300>필수</font></span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
요청 금액 중 비과세 금액
<br>
<span class="text-muted">판매하는 상품이 과세 품목이라면 해당 값을 0으로 선언합니다. 그 외의 과세 계산은 토스 서버에서 자동처리 합니다.<br>
• 토스에서 금액과 관련된 모든 필드는 Number 형태로 선언합니다. 필수 체크는 총금액과 비과세 금액만 체크합니다.<br>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
amountTaxable
<span class="type">Integer </span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
요청 금액 중 과세 금액
</div>
</div>
<div class="field clearfix">
<div class="key">
amountVat
<span class="type">Integer </span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
요청 금액 중 부가세
</div>
</div>
<div class="field clearfix">
<div class="key">
amountServiceFee
<span class="type">Integer </span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
요청 금액 중 봉사료
</div>
</div>
<div class="field clearfix">
<div class="key">
spreadOut
<span class="type">Integer </span>
<span class="type">Max Length: 8 </span>
</div>
<div class="desc">
카드 할부개월
<br>
<span class="text-muted">사용자가 선택한 카드 할부개월 (5만원 미만은 기본 일시불 결제)<br>
• 0(일시불) ~ 12개월 까지 숫자형태로 선언합니다.<br>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cashReceipt
<span class="type">Boolean </span>
<span class="type">Max Length: 5 </span>
</div>
<div class="desc">
현금영수증 발급여부
<br>
<span class="text-muted">토스 현금영수증 자동발행 기능을 사용한다면 매회 결제 시 true 값을, 미 사용하는 경우(가맹점 자체 발행) false 로 선언하면 됩니다.<br>
반드시 true 또는 false 값을 전달해주셔야 하고 null과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false로 처리됩니다.<br>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
cashReceiptTradeOption
<span class="type">string</span>
<span class="type">Max Length: 9 </span>
</div>
<div class="desc">
현금영수증 발급타입
<br>
<span class="text-muted">문화비 관련 상품의 경우, 발급타입 설정이 필요합니다.
<br>
• CULTURE : 문화비<br>
• GENERAL : 일반(default)<br>
• PUBLIC_TP : 교통비<br>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
sendFailPush
<span class="type">Boolean</span>
<span class="type">Max Length: 5 </span>
</div>
<div class="desc">
결제실패 푸시알람 사용여부
<br>
<span class="text-muted">빌링키 결제가 실패할 경우, 사용자에게 결제 실패 알람을 발송합니다.(기본값은 true)
<br>
• 같은 빌링키로 다회 요청을 하더라도, 결제 실패 알람은 1시간 최대 1회 발송 가능합니다.<br>
• 고객에게 빌링 결제시 잔액부족 알람 발송을 희망하지 않을경우, 해당 파라미터 값을 false 로 선언합니다.<br>
</span>
</div>
</div>
</div>
<div class="info">
<h4>response</h4>
<div class="field clearfix">
<div class="key">
code
<span class="type">integer</span>
<span class="type">Max Length: 2 </span>
</div>
<div class="desc">
성공여부
<br/>
<br/>
<table class="table">
<tr>
<td>0</td>
<td>성공</td>
</tr>
<tr>
<td>-1</td>
<td>실패 (실패사유는 msg와 errorCode로 제공)</td>
</tr>
</table>
</div>
</div>
<div class="field clearfix">
<div class="key">
mode
<span class="type">string</span>
<span class="type">Max Length: 4</span>
</div>
<div class="desc">
결제환경
<br/>
<br/>
<table class="table">
<tr>
<td>LIVE</td>
<td>실거래용</td>
</tr>
<tr>