토스페이 연동가이드

생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있습니다. 상황에 따라, 승인 혹은 환불 응답을 수신하지 못한 경우에도 활용 가능합니다.

각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.

POSThttps://pay.toss.im/api/v2/status

요청 파라미터

apiKeystring필수

가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.

최대 30자

payTokenstring

토스페이 토큰. payToken 또는 orderNo 중 하나를 필수로 전달해야 합니다.

최대 50자

orderNostring

가맹점 주문번호. payToken 또는 orderNo 중 하나를 필수로 전달해야 합니다.

최대 50자

응답 파라미터

modestring필수

결제환경. LIVE: 실거래용, TEST: 테스트용

가능한 값:

TESTLIVE

payTokenstring필수

토스페이 토큰

최대 30자

orderNostring필수

토스페이와 연계된 상점 주문번호

최대 50자

payStatusstring필수

결제 상태. PAY_STANDBY: 결제 대기 중, PAY_APPROVED: 구매자 인증 완료, PAY_CANCEL: 결제 취소, PAY_PROGRESS: 결제 진행 중, PAY_COMPLETE: 결제 완료, REFUND_PROGRESS: 환불 진행 중, REFUND_SUCCESS: 환불 성공, SETTLEMENT_COMPLETE: 정산 완료, SETTLEMENT_REFUND_COMPLETE: 환불 정산 완료

가능한 값:

PAY_STANDBYPAY_APPROVEDPAY_COMPLETEPAY_CANCELREFUND_SUCCESSPAY_PROGRESSSETTLEMENT_COMPLETESETTLEMENT_REFUND_COMPLETEPAY_FAILREFUND_PENDINGREFUND_PROGRESSESCROW_REQUESTESCROW_RELEASEESCROW_DENYESCROW_AGREE

payMethodstring필수

결제수단. TOSS_MONEY: 토스머니, CARD: 카드

가능한 값:

TOSS_MONEYTOSSPAY_MONEYCARDACCOUNTRESELLER_CARDBNPL

amountinteger (int64)필수

가맹점이 토스로 전달한 결제 총 금액

discountedAmountinteger (int64)필수

할인된 금액. 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.

discountAmountV2integer (int64)필수

즉시 할인 적용 금액. 토스페이 창에서 자동으로 적용된 즉시할인 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.

paidPointV2integer (int64)필수

토스 포인트 사용금액. 결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0으로 리턴됩니다.

paidAmountinteger (int64)필수

지불수단 승인금액. 가맹점이 요청한 총 금액(amount) 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다.

refundableAmountinteger (int64)필수

환불 가능 잔액. 환불 성공 후 남은 환불 가능 금액

amountTaxableinteger (int64)필수

총 결제 금액 중 적용된 과세 금액

amountTaxFreeinteger (int64)필수

총 결제 금액 중 적용된 비과세 금액

amountVatinteger (int64)필수

총 결제 금액 중 적용된 부가세 금액

amountServiceFeeinteger (int64)필수

총 결제 금액 중 적용된 봉사료

disposableCupDepositinteger (int64)필수

일회용 컵 보증금

accountBankCodestring

은행 코드. 사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.

accountBankNamestring

은행 명

accountNumberstring

계좌번호. 계좌번호는 일부 마스킹을 포함하고 있습니다.

transactionsTransaction[]필수

거래 트랜잭션

createdTsstring (date-time)필수

사용자 최초 결제 요청 시간 (결제 생성 시간)

paidTsstring (date-time)필수

결제 완료 처리 시간

codeinteger (int32)

응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)

errorCodestring

에러 코드

msgstring

응답이 성공이 아닌 경우 설명 메시지

결제 상태 확인

요청 파라미터

응답 파라미터

요청 예제

응답 예제