-
Notifications
You must be signed in to change notification settings - Fork 13
/
api.html
3628 lines (3508 loc) · 195 KB
/
api.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>토스페이 API</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="#state">결제 상태</a>
</li>
<li>
<a href="#httpResponse">HTTP 응답코드</a>
</li>
<h5>API 목록</h5>
<li>
<a href="#payments">결제 생성</a>
</li>
<li>
<a href="#resultcallback">결제 결과 callback</a>
</li>
<li>
<a href="#execute">가맹점 승인</a>
</li>
<!--
<li>
<a href="#cancel">결제 취소</a>
</li>
-->
<li>
<a href="#refunds">결제 환불</a>
</li>
<li>
<a href="#status">결제 상태 확인</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">
<h3>토스페이 API 소개</h3>
<p>
토스를 통한 결제 서비스를 사용하기 위한 API입니다.<br>
토스페이를 활용한 개발을 처음 시작하신다면, 좀 더 친절한 안내를 먼저 확인해보세요! <br><br>
<strong>토스페이 개발 가이드는 수시로 업데이트 됩니다. 사전 예고없이 업데이트 될 수 있으니 지속적으로 확인해 주시길 부탁드립니다.</strong>
<br>
<br><a href="gettingstarted.html">>> '토스페이 시작하기' 문서로 바로가기</a>
</p>
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-triangle pull-left" aria-hidden="true" style="margin-top:8px;margin-left:6px"></i>
토스페이는 결제 과정 중의 보안을 위해 pay.toss.im의 결제 API HTTPS는 TLS v1.2 이상만을 지원합니다.
SSL은 필수이며 적용이 되어 있지 않은 서버에서는 이용이 불가합니다.
</div>
<p><br><strong>토스페이 서비스를 지원하는 브라우저는 다음과 같습니다.</strong></p>
<p>
PC 브라우저, Android, iOS 모두 TLS 1.2 이상의 환경에서 동작이 가능하며, 디바이스 같은 경우 토스 앱의 최소 지원 버전 기준입니다.<br>
토스 앱 최신버전이 아닌 경우, 결제 진행이 원활하지 않을 수 있으니 가급적 최신 버전의 토스앱을 이용해 주시길 부탁드립니다.
</p>
<ul>
<li>Safari 12, Chrome 64, Firefox 67, Opera 51, Edge 79 부터 지원</li>
<li>Android 6.0 Marshmallow 부터 지원</li>
<li>iOS 15 부터 지원</li>
<li>Java 를 사용하시는 경우, jdk 1.8 이상 버전 사용을 권장합니다</li>
</ul>
<p><br><strong>토스페이는 iframe 방식을 공식적으로 지원하지 않습니다. <br>
iframe 방식을 이용하는 경우 결제가 원활하지 않을 수 있으므로 페이지 전환방식의 연동을 권장드립니다. </strong><br><br>
<strong>또한, 토스페이는 기본적으로 Server to Server 호출 방식을 지향합니다. <br>
웹 브라우저를 통하여 클라이언트 단에서 토스 도메인으로 직접 결제 API를 호출하는 방식을 사용할 경우,<br>
결제와 관련된 데이터가 외부에 노출되어 보안사고가 발생할 수 있으니 유의해 주시길 부탁드립니다. </strong></p>
</div>
</div>
</div>
<div class="method" id="state">
<div class="method-section clearfix">
<div class="method-description">
<h3>결제 상태</h3>
<p>
결제 건이 생성된 후, 결제가 진행됨에 따라 결제 상태가 변경되며, 각 결제 상태마다 판매자 또는 구매자가 요청할 수 있는 행동도 변합니다. 아래는 결제 상태 목록과 각 상태에 대한 설명입니다.
</p>
<div class="info">
<h4>결제 상태 목록</h4>
<div class="field clearfix">
<div class="key">
PAY_STANDBY
</div>
<div class="desc">
결제 대기 중
<br /> 결제 건이 생성되었고, 구매자의 결제 진행을 대기 중인 상태. 이 상태에서 구매자나 가맹점이 결제를 취소할 수 있습니다. 또한 설정한 '만료 기간'이 도래하면 자동으로 취소됩니다.
</div>
</div>
<div class="field clearfix">
<div class="key">
PAY_APPROVED
</div>
<div class="desc">
구매자 인증 완료
<br /> 결제를 위한 구매자 인증 완료되고, 가맹점의 최종 승인을 기다리는 상태.
<br />(결제 생성 시 'autoExecute'를 false로 설정한 경우에만 이 단계를 거칩니다. <br>
이 상태에서도 설정한 결제 '유효기간이 만료'되면 자동으로 취소처리 됩니다.)
</div>
</div>
<div class="field clearfix">
<div class="key">
PAY_CANCEL
</div>
<div class="desc">
결제 취소
<br /> 결제가 완료되기 전에 구매자가 결제를 취소하거나 유효기간이 만료된 거래. (결론적으론 금액의 이동 없이 종료된 건)
</div>
</div>
<div class="field clearfix">
<div class="key">
PAY_PROGRESS
</div>
<div class="desc">
결제 진행 중
<br /> 구매자가 결제를 승인하여 구매자의 계좌에서 결제 금액을 출금 처리 중인 상태입니다.
</div>
</div>
<div class="field clearfix">
<div class="key">
PAY_COMPLETE
</div>
<div class="desc">
결제 완료
<br /> 구매자 및 가맹점의 결제 승인 및 출금이 정상적으로 완료된 상태입니다
</div>
</div>
<div class="field clearfix">
<div class="key">
REFUND_PROGRESS
</div>
<div class="desc">
환불 진행 중
<br /> 전액 또는 부분 환불을 진행 중인 상태로, 완료되기 전 까지 다른 환불을 진행할 수 없습니다.
</div>
</div>
<div class="field clearfix">
<div class="key">
REFUND_SUCCESS
</div>
<div class="desc">
환불 성공
<br /> 전액 또는 부분 환불이 완료되어, 환불 처리한 금액이 구매자의 계좌로 입금 완료된 상태입니다.
</div>
</div>
<div class="field clearfix">
<div class="key">
SETTLEMENT_COMPLETE
</div>
<div class="desc">
정산 완료
<br /> 결제 완료된 금액에 대해 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과)
</div>
</div>
<div class="field clearfix">
<div class="key">
SETTLEMENT_REFUND_COMPLETE
</div>
<div class="desc">
환불 정산 완료
<br />전액 또는 부분 환불에 대한 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과했거나 전액 환불에 대한 정산 완료된 경우)
</div>
</div>
</div>
</div>
<div class="method-example">
<pre>
<code class="curl">
</code>
<code class="java">
</code>
<code class="pho">
</code>
</pre>
</div>
</div>
</div>
<div class="method" id="httpResponse">
<div class="method-section clearfix">
<div class="method-description">
<h3>HTTP 응답 코드</h3>
<div class="info">
<h4>HTTP Response Code</h4>
<div class="field clearfix">
<div class="key">200</div>
<div class="desc">
OK : 정상
</div>
</div>
<div class="field clearfix">
<div class="key">400</div>
<div class="desc">
Bad Request : 파라미터 오류
</div>
</div>
<div class="field clearfix">
<div class="key">401</div>
<div class="desc">
Unauthorized : 가맹점 key 오류
</div>
</div>
<div class="field clearfix">
<div class="key">404</div>
<div class="desc">
Not Found : 존재하지 않는 요청
</div>
</div>
<div class="field clearfix">
<div class="key">50x</div>
<div class="desc">
Server error : 서버 오류
</div>
</div>
</div>
</div>
<div class="method-example">
<pre>
<code class="curl">
</code>
<code class="java">
</code>
<code class="pho">
</code>
</pre>
</div>
</div>
</div>
<div class="method" id="payments">
<div class="method-section clearfix">
<div class="method-description">
<h3>결제 생성</h3>
<p>
결제 건을 생성합니다.
</p>
<p>
결제 생성 완료 후, 구매자의 결제 인증을 얻어 완료처리하는 방법은 아래 문서를 참고하세요.
<br>
<a href="gettingstarted.html#overview-3">토스페이 시작하기 > 3. 구매자 인증 받기</a>
</p>
<div class="info">
<h4>endpoint</h4>
<div class="field clearfix">
<div class="key">
(POST)
</div>
<div class="desc">
https://pay.toss.im/api/v2/payments <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">
가맹점 key
<br>
<span class="text-muted">웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.</span><br>
<font color=#AA1212>테스트가 완료되면 운영 오픈 전 반드시 '실 거래용 Key'로 변경 후 체크해주세요!</font>
</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">주문번호는 50자 이내여야 하고, '숫자, 영문자, 특수문자 _-:.^@'만 사용할 수 있습니다.<br>
주문번호는 매회 유니크한 값으로 활용해 주셔야하며, 구매자 인증완료(PAY_APPROVED) 전의 주문번호는 재사용이 가능합니다.<br>
단, 사용자 인증완료 후에는 재 사용이 불가하며 최초 생성 후 2년이 지난 주문 번호는 재사용이 불가합니다.<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">상품 설명은 공백으로만 설정할 수 없고, 백슬래시(\)와 따옴표(",')를 포함할 수 없으며 총 255자 이내여야 합니다.
이 값에 한글이 포함되었다면 인코딩에 유의해주세요. <br>
<a href="qna.html#faq-2">토스 인코딩 방식 참고사항</a></span>
</div>
</div>
<div class="field clearfix">
<div class="key">
retUrl
<span class="type">string <font color=#c25300>필수</font></span>
<span class="type">Max Length: 255 </span>
</div>
<div class="desc">
구매자 인증완료 후 연결할 가맹점 웹페이지 URL<br>
<span class="text-muted"> 사용자 인증이 완료되는 시점에 인증 데이터와 함께 결제완료 페이지로 이동시킵니다. 이 때, 전달되는 인증 데이터는 아래 링크에서 확인해 보실 수 있습니다. (단, 전달되는 인증 데이터는 결제수단 별로 차이가 있을 수 있습니다.)<br>
<a href="gettingstarted.html#overview-4">구매자 인증완료 참고사항</a></td>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
retCancelUrl
<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">이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고,
구매자는 브라우저나 앱을 강제로 종료하지 않고 가맹점의 취소 페이지로 이동할 수 있습니다. 구매자 편의를 위하여 반드시 활용해주세요!<br>
<font color="#AA1212">
구매자가 결제창을 종료한 경우 즉시 가맹점이 설정한 retCancelUrl로 redirect 되며, 토스 서버에서는 강제로 결제상태를 취소처리 합니다. <br>
상점에서 취소거래 구분이 필요하다면 주문번호를 활용하는 등 자체적으로 거래구분 처리 해주세요.
</font>
</div>
</div>
<div class="field clearfix">
<div class="key">
retAppScheme
<span class="type">string</span>
<span class="type">Max Length: 255 </span>
</div>
<div class="desc">
결제 완료 후 연결할 가맹점 측 앱 스킴 값<br>
<span class="text-muted">가맹점의 결제 구현환경이 App to App인 경우 retAppScheme 값을 선언해 주시면 토스페이 완료 후 가맹점 앱으로 redirect 할 수 있습니다. <br>
<font color="#AA1212">단, 사용자의 진입점이 앱이 아닌 일반 웹브라우저인 경우 retAppScheme가 포함되어 있다면 이전 브라우저가 뜨지 않아 결제가 완료될 수 없으니 반드시 유념해 주세요. </font><br>
<strong>iOS 앱 결제의 경우 필수 구현을 권장합니다. iOS 특성 상, 자동 앱 전환이 되지 않기 때문에 가맹점 앱 스킴 값을 이 곳에 선언해 주셔야 인증 후 가맹점 앱으로 랜딩됩니다.</strong> safari 등 모바일 웹 브라우저에서 자동 전환되지 않는 이슈는 OS 이슈인 점 참고 부탁드립니다. (Ex. testshop://) <br>
<a href="gettingstarted.html#create-3">토스 앱 가이드 참고사항</a></td>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
autoExecute
<span class="type">Max Length: 5 </span>
</div>
<div class="desc">
자동 승인 여부 설정 <br>
<span class="text-muted">가맹점의 판매 상품에 따라 '자동 승인 설정' 을 활용할 수 있습니다. <br>
true 를 선언한 경우 resultCallback 을 필수 값으로 체크합니다. <br>
<a href="gettingstarted.html#create-9">자동 승인 설정 참고사항</a></td>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
resultCallback
<span class="type">Max Length: 500 </span>
</div>
<div class="desc">
결제 결과 callback URL<br>
<span class="text-muted"> 이 값은 autoExecute를 true로 사용하시는 경우에만 필수 값입니다.<br>
토스 서버가 정상 출금 완료 후 이 곳에 입력한 URL로 성공 결과를 전송하기 때문에 가맹점 서버에서 반드시 확인하셔야 합니다.<br> callback 데이터가 수신되지 않았다면 네트워크의 문제일 수 있으니
'<a href="qna.html#faq-1">토스 방화벽 설정</a>' 을 확인해 주세요!
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
callbackVersion
<span class="type">Max Length: 2 </span>
</div>
<div class="desc">
결제 결과 callback 버전<br>
<span class="text-muted"> 이 값은 autoExecute를 true로 사용하시는 경우에만 필수 값입니다. <br>
callback 버전에 따라 전달되는 응답 값이 다를 수 있으니 최신 버전(V2) 이용을 권장합니다. 이 값이 포함되지 않을 경우 기존의 V1 버전의 데이터가 전달됩니다. <br>
V1 : callback 리턴값을 파라미터로 받을 수 있습니다.<br>
V2 : callback 리턴값을 JSON으로 받을 수 있습니다.
</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>
<font color=#AA1212>금액과 관련된 모든 파라미터는 Number 형태로 보내주셔야 에러가 발생하지 않습니다.</font>
</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
amountTaxFree
<span class="type">integer <font color=#c25300>필수</font></span>
</div>
<div class="desc">
결제 금액 중 비과세금액<br>
<span class="text-muted">판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요. 비과세액은 필수 값이니 빈 값으로 보내주시는 경우 에러가 발생합니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
amountTaxable
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
결제 금액 중 과세금액<br>
<span class="text-muted">별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다.</span>
</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">
결제 금액 중 부가세<br>
<span class="text-muted">값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.</span>
</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">
결제 금액 중 봉사료<br>
<span class="text-muted"></span>
</div>
</div>
<div class="field clearfix">
<div class="key">
expiredTime
<span class="type">string</span>
<span class="type">Max Length: 20 </span>
</div>
<div class="desc">
결제 만료 기한 (기본값 15분, 최대 60분 설정 가능)
<br>형식 : 2020-03-03 12:30:20
</div>
</div>
<div class="field clearfix">
<div class="key">
enablePayMethods
<span class="type">string </span>
<span class="type">Max Length: 100 </span>
</div>
<div class="desc">
결제수단 구분변수<br>
<span class="text-muted">가맹점 필요에 따라 결제창에 노출하는 결제수단을 제어할 수 있습니다.
아래 옵션 값에 따라 설정 가능합니다.</span>
<br>
<br>
<table class="table">
<tr>
<td>TOSS_MONEY</td>
<td>결제수단 중 토스머니만 노출</td>
</tr>
<tr>
<td>CARD</td>
<td>결제수단 중 카드만 노출</td>
</tr>
<tr>
<td>null 혹은 그 외의 값</td>
<td>상점에 설정된 기본 결제수단으로 노출</td>
</tr>
</table>
</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 값을 전달해주셔야 하고<br>
null과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false로 처리됩니다.<br>
</div>
</div>
<div class="field clearfix">
<div class="key">
cashReceiptTradeOption
<span class="type">string </span>
<span class="type">Max Length: 10 </span>
</div>
<div class="desc">
현금영수증 발급타입<br>
<span class="text-muted">문화비 관련 상품의 경우, 발급 타입을 설정하여 보내주세요.</span>
<br />
<br />
<table class="table">
<tr>
<td>CULTURE</td>
<td>문화비</td>
</tr>
<tr>
<td>GENERAL</td>
<td>일반(default)</td>
</tr>
<tr>
<td>PUBLIC_TP</td>
<td>교통비</td>
</tr>
</table>
</div>
</div>
<div class="field clearfix">
<div class="key">
cardOptions
<span class="type">object</span>
</div>
<div class="desc">
결제창에 특정 카드만 노출하고 싶다면, options 변수에 토스 카드코드를 추가해 주세요.
예를들어, 삼성카드와 현대카드만 결제가 가능하도록 노출을 제어한다면 아래와 같이 토스 카드코드를 넘겨주시면 됩니다.<br>
"cardOptions": <br>{"options": [{"cardCompanyCode":3},{"cardCompanyCode":5}]}
</div>
</div>
<div class="field clearfix">
<div class="key">
installment
<span class="type">string </span>
<span class="type">Max Length: 10 </span>
</div>
<div class="desc">
할부 제한 타입<br>
<span class="text-muted">신용카드 결제 시, 사용자의 할부 선택을 제한할 수 있습니다.</span>
<br />
<br />
<table class="table">
<tr>
<td>USE</td>
<td>할부 사용(default)</td>
</tr>
<tr>
<td>NOT_USE</td>
<td>할부 미사용</td>
</tr>
</table>
</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>
'<a href="qna.html#faq-1">토스 방화벽 설정</a>' 을 확인해 주세요! <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">
checkoutPage
<span class="type">string</span>
<span class="type">Max Length: 255 </span>
</div>
<div class="desc">
결제를 진행할 수 있는 토스페이 웹페이지 URL<br>
<span class="text-muted">토스가 전달한 값 그대로를 구매자에게 띄워주세요.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
payToken
<span class="type">string</span>
<span class="type">Max Length: 30 </span>
</div>
<div class="desc">
토스페이 토큰<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">
응답이 성공이 아닌 경우 설명 메세지
</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 />
<br />
<table class="table">
<tr>
<td>COMMON_PAY_ERROR</td>
<td>문제가 발생하였습니다.</td>
</tr>
<tr>
<td>COMMON_INVALID_PARAMETER</td>
<td>요청한 값이 바르지 않습니다.</td>
</tr>
<tr>
<td><a href="qna.html#faq-7">그 외의 에러 코드</td>
<td></td>
</tr>
</table>
</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/v2/payments</code></pre>
<div class="title">Example Request</div>
<pre><code class="curl language-bash">curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo":"1",
"amount":10000,
"amountTaxFree":0,
"productDesc":"테스트결제",
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute":true,
"resultCallback":"https://YOUR-SITE.COM/callback",
"callbackVersion":"V2",
"retUrl": "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1",
"retCancelUrl": "http://YOUR-SITE.COM/close"
}'</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/v2/payments");
connection = url.openConnection();
connection.addRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
connection.setDoInput(true);
org.json.simple.JSONObject jsonBody = new JSONObject();
jsonBody.put("orderNo", "1");
jsonBody.put("amount", 10000);
jsonBody.put("amountTaxFree", 0);
jsonBody.put("productDesc", "테스트 결제");
jsonBody.put("apiKey", "sk_test_w5lNQylNqa5lNQe013Nq");
jsonBody.put("autoExecute", true);
jsonBody.put("resultCallback", "http://"http://YOUR-SITE.COM/callback");
jsonBody.put("callbackVersion", "V2");
jsonBody.put("retUrl", "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1");
jsonBody.put("retCancelUrl", "http://YOUR-SITE.COM/close");
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["orderNo"] = "1";
$arrayBody["amount"] = 10000;
$arrayBody["amountTaxFree"] = 0;
$arrayBody["productDesc"] = "테스트 결제";
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
$arrayBody["autoExecute"] = true;
$arrayBody["resultCallback"] = "http://YOUR-SITE.COM/callback";
$arrayBody["callbackVersion"] = "V2";
$arrayBody["retUrl"] = "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1";
$arrayBody["retCancelUrl"] = "http://YOUR-SITE.COM/close";
$jsonBody = json_encode($arrayBody);
$ch = curl_init('https://pay.toss.im/api/v2/payments');
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=sk_test_w5lNQylNqa5lNQe013Nq"
data = data & "&orderNo=1"
data = data & "&amount=10000"
data = data & "&amountTaxFree=0"
data = data & "&productDesc=ASPtestProduct"
data = data & "&autoExecute=true"
data = data & "&resultCallback=http://YOUR-SITE.COM/callback"
data = data & "&callbackVersion=V2"
data = data & "&retUrl=http://YOUR-SITE.COM/ORDER-CHECK?orderno=1"
data = data & "&retCancelUrl=http://YOUR-SITE.COM/close"
Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP")
httpRequest.Open "POST", "https://pay.toss.im/api/v2/payments", 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/v2/payments"
params = {
"orderNo": "1",
"amount": 10000,
"amountTaxFree": 0,
"productDesc":"테스트 결제",
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute": true,
"resultCallback": "http://YOUR-SITE.COM/callback",
"callbackVersion": "V2",
"retUrl": "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1",
"retCancelUrl": "http://YOUR-SITE.COM/close"
}
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/v2/payments")
params = {
"orderNo" => "1",
"amount"=> 10000,
"amountTaxFree"=> 0,
"productDesc" => "테스트 결제",
"apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute" => true,
"resultCallback" => "http://YOUR-SITE.COM/callback",
"callbackVersion" => "V2",
"retUrl": "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1",
"retCancelUrl": "http://YOUR-SITE.COM/close"
}
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><div><code style="border:none;box-shadow:none;" class="language-javascript always-visible">{"code":0,"checkoutPage":"https://pay.toss.im/payfront/auth?payToken=example-payToken","payToken":"example-payToken"}
</code></div></pre>
</div>
</div>
</div>
<div class="method" id="resultcallback">
<div class="method-section clearfix">
<div class="method-description">
<h4>결제 결과 callback (resultCallback)</h4>
<p>
결제 처리가 완료되면 결제 상태가 변경되고, 토스는 가맹점 서버로 변경 사항을 알려드립니다. <br><br>
결제완료 callback을 받았을 때, 결제완료 상태를 변경하시고 재고차감 등의 로직을 처리해 주세요.<br>
자동 승인 설정 시 (autoExecute가 true) 필수적으로 활용해야 합니다.
</p>
<p>
* callback 연동 전, <a href="qna.html#faq-1">방화벽 정보</a>를 반드시 확인해 주세요! <br>
* 생성된 결제 건에 resultCallback 파라미터 값이 있을 경우에만 동작합니다. <br>
* 아래는 callback V2버전이며, 가맹점 측에서는 최신버전의 callback 을 이용해 주시길 부탁드립니다. (callbackVersion 설명참고)<br>
<font color="#AA1212"><strong>* 사전 예고 없이 field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.</strong></font>
</p>
<div class="info">
<h4>parameter</h4>
<div class="field clearfix">
<div class="key">
status
<span class="type">string</span>
<span class="type">Max Length: 20 </span>
</div>
<div class="desc">
PAY_COMPLETE <br>
<span class="text-muted">결제 완료<br>
환불 등 '결제 완료' 이외 상태는 전달되지 않습니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
payToken
<span class="type">string</span>
<span class="type">Max Length: 30 </span>
</div>
<div class="desc">
승인된 결제 토큰
</div>
</div>
<div class="field clearfix">
<div class="key">
orderNo
<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">카드 승인건의 경우, 카드 데이터가 함께 포함되어 전달됩니다.</span>
<br>
<br>
<table class="table">
<tr>
<td>TOSS_MONEY</td>
<td>토스머니</td>
</tr>
<tr>
<td>CARD</td>
<td>카드</td>
</tr>
</table>
</div>
</div>
<div class="field clearfix">
<div class="key">
amount
<span class="type">integer</span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
결제요청된 금액<br>
<span class="text-muted">최초 가맹점에서 결제 요청된 금액이 리턴됩니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
discountedAmount
<span class="type">integer</span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
할인된 금액<br>
<span class="text-muted">할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.</span>
</div>
</div>
<!--
<div class="field clearfix">
<div class="key">
paidPoint
<span class="type">integer</span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
토스 포인트 사용금액<br>
<span class="text-muted">결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0 으로 리턴됩니다.</span>
</div>
</div>
-->
<div class="field clearfix">
<div class="key">
paidAmount
<span class="type">integer</span>
<span class="type">Max Length: 7 </span>
</div>
<div class="desc">
지불수단 승인금액<br>
<span class="text-muted">총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.</span>
</div>
</div>
<div class="field clearfix">
<div class="key">
paidTs
<span class="type">string</span>
<span class="type">Max Length: 20 </span>
</div>
<div class="desc">
결제 완료 처리 시간<br>
형식 : 2020-04-03 14:22:37
</div>
</div>
<div class="field clearfix">