결제 결과 callback (resultCallback)

결제 처리가 완료되면 결제 상태가 변경되고, 토스는 가맹점 서버로 변경 사항을 알려드립니다.

결제완료 callback을 받았을 때, 결제완료 상태를 변경하시고 재고차감 등의 로직을 처리해 주세요. 자동 승인 설정 시 (autoExecute가 true) 필수적으로 활용해야 합니다.

callback 연동 전, 방화벽 정보를 반드시 확인해 주세요!
생성된 결제 건에 resultCallback 파라미터 값이 있을 경우에만 동작합니다.
아래는 callback V2버전이며, 가맹점 측에서는 최신버전의 callback 을 이용해 주시길 부탁드립니다. (callbackVersion 설명참고)

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

파라미터

statusstring

maxLen: 20

결제 상태

PAY_COMPLETE 결제 완료 환불 등 '결제 완료' 이외 상태는 전달되지 않습니다.

payTokenstring

maxLen: 30

승인된 결제 토큰

승인된 결제 토큰입니다.

orderNostring

maxLen: 50

결제생성 구간에서 전달된 가맹점 주문번호

결제 생성 시 전달된 가맹점 주문번호입니다.

payMethodstring

maxLen: 10

승인된 결제수단

승인된 결제수단입니다.
카드 승인 건의 경우, 카드 데이터가 함께 포함되어 전달됩니다.

값	설명
TOSS_MONEY	토스머니
CARD	카드

amountinteger

maxLen: 7

결제요청된 금액

최초 가맹점에서 결제 요청된 금액이 반환됩니다.

discountedAmountinteger

maxLen: 7

할인된 금액

할인된 금액이 반환되며, 할인 적용이 없으면 0으로 반환됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용 금액이 포함됩니다. 결제 상점에 따라 할인 조건은 차이가 있을 수 있습니다.

paidAmountinteger

maxLen: 7

지불수단 승인금액

총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.

paidTsstring

maxLen: 20

결제 완료 처리 시간

결제 완료 처리 시간입니다. 형식: YYYY-MM-DD HH:MM:SS (예: 2020-04-03 14:22:37)

transactionIdstring

maxLen: 36

거래 트랜잭션 아이디

결제의 거래 구분을 위하여 토스 서버에서 유니크한 값을 생성하여 전달드립니다.

cardCompanyCodeinteger

maxLen: 2

승인된 카드사 코드

승인된 카드사 코드입니다.

cardAuthorizationNostring

maxLen: 8

카드 승인번호

카드 승인번호입니다.

spreadOutstring

maxLen: 8

사용자가 선택한 카드 할부개월

5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.

noInterestboolean

maxLen: 5

카드 무이자 적용 여부

카드 무이자 적용 여부입니다.

값	설명
true	무이자
false	일반

cardMethodTypestring

maxLen: 10

카드 타입

승인된 카드의 타입을 구분할 수 있습니다.

값	설명
CREDIT	신용카드
CHECK	체크카드
PREPAYMENT	선불카드

cardNumberstring

maxLen: 20

마스킹된 카드번호

카드번호 16자리 중 중간자리는 마스킹됩니다.

cardUserTypestring

maxLen: 20

카드 사용자 구분

카드 사용자 구분입니다.

값	설명
PERSONAL	본인 카드
PERSONAL_FAMILY	가족 카드
CORP_PERSONAL	법인지정 결제계좌 임직원
CORP_PRIVATE	법인 공용
CORP_COMPANY	법인지정 결제계좌 회사(하나카드만)

cardBinNumberstring

maxLen: 8

카드 BIN 번호

카드사에서 제공한 카드 BIN 번호입니다 (마스킹되어 있을 수 있습니다). 100% 신뢰는 불가합니다.

cardNum4Printstring

maxLen: 4

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

사용자가 선택한 카드의 끝 4자리입니다. 사용자가 선택한 결제수단(payMethod)이 'CARD'인 경우 카드번호 끝 4자리를 전달합니다 (카드사에 따라 마스킹이 포함되어 있을 수 있습니다).

salesCheckLinkUrlstring

maxLen: 255

신용카드 매출전표 호출 URL

승인된 카드 결제 건의 매출전표를 확인할 수 있는 URL입니다.

accountBankCodestring

maxLen: 3

은행 코드

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

accountBankNamestring

maxLen: 20

은행 명

은행 명입니다. 은행코드 리스트

accountNumberstring

maxLen: 30

계좌번호

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

Example Response

POST https://pay.toss.im/payfront/demo/callback (결제 생성 시 가맹점에서 설정한 callback URL)
Content-Type application/json;charset=UTF-8
{
 "status": "PAY_COMPLETE",
 "payToken": "example-payToken",
 "orderNo": "1",
 "payMethod": "CARD",
 "amount": 3000,
 "discountedAmount": 600,
 "paidAmount": 2300,
 "paidTs": "2020-04-03 14:22:37",
 "transactionId" : "dc3b951a-9781-462e-ab5a-b8a0bea0222a",
 "cardCompanyCode": 3,
 "cardAuthorizationNo": "87654321",
 "spreadOut": 0,
 "noInterest": false,
 "cardMethodType": "CREDIT",
 "cardUserType": "PERSONAL",
 "cardNumber": "654321******1234",
 "cardBinNumber": "654321",
 "cardNum4Print": "1234",
 "salesCheckLinkUrl": "https://pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=2da1ca05-d91d-410f-976d-7a610242da8a",
 //"paidPoint": 0, // 2020.08.06 이후 fadeout 된 레거시 포인트 금액으로 0원으로 나감
}

HTTP 응답 코드

코드	설명
200	OK : 정상
400	Bad Request : 파라미터 오류
401	Unauthorized : 가맹점 API Key 오류
404	Not Found : 존재하지 않는 요청
50x	Server error : 서버 오류
xxx	Server error : 기타 등등

결제 생성 가맹점 결제 승인