토스페이 연동가이드
API 레퍼런스일반 결제 API

결제 결과 callback (resultCallback)

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

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

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

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

파라미터

statusstring

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

최대 길이: 20
payTokenstring

승인된 결제 토큰. 승인된 결제 토큰입니다.

최대 길이: 30
orderNostring

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

최대 길이: 50
payMethodstring

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

최대 길이: 10
가능한 값:
TOSS_MONEY토스머니
CARD카드
amountinteger

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

최대 길이: 10
discountedAmountinteger

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

최대 길이: 10
paidAmountinteger

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

최대 길이: 10
paidTsstring

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

최대 길이: 20
transactionIdstring

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

최대 길이: 36
cardCompanyCodeinteger

승인된 카드사 코드. 승인된 카드사 코드입니다. [카드 코드](/guide/card-code)를 참조해주세요.

최대 길이: 2
cardAuthorizationNostring

카드 승인번호. 카드 승인번호입니다.

최대 길이: 8
spreadOutstring

사용자가 선택한 카드 할부개월. 5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.

최대 길이: 8
noInterestboolean

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

최대 길이: 5
가능한 값:
true무이자
false일반
cardMethodTypestring

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

최대 길이: 10
가능한 값:
CREDIT신용카드
CHECK체크카드
PREPAYMENT선불카드
cardNumberstring

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

최대 길이: 20
cardUserTypestring

카드 사용자 구분. 카드 사용자 구분입니다.

최대 길이: 20
가능한 값:
PERSONAL본인 카드
PERSONAL_FAMILY가족 카드
CORP_PERSONAL법인지정 결제계좌 임직원
CORP_PRIVATE법인 공용
CORP_COMPANY법인지정 결제계좌 회사(하나카드만)
cardBinNumberstring

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

최대 길이: 8
cardNum4Printstring

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

최대 길이: 4
salesCheckLinkUrlstring

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

최대 길이: 255
accountBankCodestring

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

최대 길이: 3
accountBankNamestring

은행 명. 은행 명입니다. [은행코드 리스트](/guide/bank-code)

최대 길이: 20
accountNumberstring

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

최대 길이: 30

HTTP 응답 코드

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

예제

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 응답 코드예제