토스페이 연동가이드

자동 승인 설정을 false로 사용하는 가맹점에서만 처리하는 로직입니다.

구매자 인증 완료 상태(PAY_APPROVED)의 결제 건을 가맹점이 주체가 되어 최종 승인하고 결제를 완료 처리합니다.

결제 승인에 관한 자세한 내용은 아래 문서를 참고하세요. 토스페이 시작하기 > 결제 승인하기

필수 파라미터는 딱 2가지 입니다. '어느 가맹점'에서 '어떤 결제건'을 최종 승인할지 알려주세요. 필요에 따라 결제건의 유효성 검증을 할 수 있습니다.

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

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

요청 파라미터

apiKeystring필수

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

최대 30자

payTokenstring필수

토스페이 토큰 (승인할 결제 건의 토큰값)

최대 30자

orderNostring

가맹점의 상품 주문번호. 주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다. 숫자, 영문자, 특수문자 _-:.^@만 사용 가능하며, 50자 이내여야 합니다.

최대 50자

amountinteger (int64)

결제 금액

응답 파라미터

codeinteger (int32)

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

errorCodestring

에러 코드

msgstring

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

modestring

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

최대 4자

가능한 값:

TESTLIVE

orderNostring

승인된 상품 주문번호

최대 50자

amountinteger (int64)

상품금액. 결제 생성 시 요청된 총 금액

최대 10자

approvalTimestring

결제건의 승인 처리 시간 (yyyy-MM-dd HH:mm:ss)

최대 20자

stateMsgstring

상태 응답 텍스트 값

최대 120자

discountedAmountinteger (int64)

할인된 금액. 할인 적용이 없으면 0. 토스 앱 즉시할인과 토스 포인트 사용금액 포함

최대 10자

paidAmountinteger (int64)

지불수단 승인금액. 총 금액 중 할인금액 제외한 순수 지불금액

최대 10자

payMethodstring

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

최대 10자

가능한 값:

TOSS_MONEYTOSSPAY_MONEYCARDACCOUNTRESELLER_CARDBNPL

payTokenstring

승인된 결제토큰

transactionIdstring

거래 트랜잭션 아이디. 매출전표 호출 또는 환불 시 활용 가능

cashReceiptMgtKeystring

현금영수증 관리번호 식별값. 토스페이 자체 식별 값으로 국세청 승인번호와 다릅니다.

최대 36자

cardCompanyNamestring

승인 카드사명

cardAuthorizationNostring

카드 승인번호

spreadOutinteger (int32)

사용자가 선택한 카드 할부개월. 5만원 미만 또는 일시불은 0

noInterestboolean

카드 무이자 적용 여부. true: 무이자, false: 일반

salesCheckLinkUrlstring

신용카드 매출전표 호출 URL

cardMethodTypestring

카드 타입. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드

가능한 값:

CREDITCHECKPREPAYMENTNONE

cardNumberstring

마스킹된 카드번호

cardUserTypestring

카드 사용자 구분. PERSONAL: 본인 카드, PERSONAL_FAMILY: 가족 카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용

가능한 값:

NONEPERSONALPERSONAL_FAMILYCORP_PERSONALCORP_PRIVATECORP_COMPANYGIFT

cardBinNumberstring

카드 BIN 번호

cardNum4Printstring

사용자가 선택한 카드의 끝 4자리

accountBankCodestring

은행코드

accountBankNamestring

은행명

accountNumberstring

마스킹된 계좌번호

metadatastring

메타데이터. 가맹점에서 관리하는 추가 정보

paidPointinteger (int64)

포인트 사용 금액

cardCompanyCodeinteger (int32)

카드사 코드

가맹점 결제 승인

요청 파라미터

응답 파라미터

요청 예제

응답 예제