4. 인증 결과 처리하기
이 단계에서는 인증을 마치고 돌아온 구매자를 처리해요. 구매자가 결제 비밀번호를 입력해 인증을 완료하면, 토스는 2단계에서 결제 생성 시 전달한 retUrl로 구매자를 보내요.
retUrl로 전달되는 파라미터 확인하기
토스는 구매자를 retUrl로 보내면서 인증 결과를 쿼리 스트링 파라미터로 함께 전달해요.
- 모든 결제에는 인증 결과(
status), 주문번호(orderNo), 결제 수단(payMethod)이 전달돼요. - 카드 결제에는 카드사 코드(
cardCompany)와 카드 BIN 번호(cardBinNum)가 추가돼요. - 토스머니·계좌 결제에는 은행 코드(
bankCode)가 추가돼요.
실제로 전달되는 URL은 다음과 같은 형태예요.
// 카드 결제
https://example-shop.com/payments/complete?status=PAY_COMPLETE&orderNo=2026-0712-000001&payMethod=CARD&cardCompany=1&cardBinNum=123456
// 토스머니·계좌 결제
https://example-shop.com/payments/complete?status=PAY_COMPLETE&orderNo=2026-0712-000001&payMethod=TOSS_MONEY&bankCode=004status 값으로 분기하기
status 값은 결제 생성 시 설정한 autoExecute 값에 따라 달라져요.
| autoExecute | status | 의미 |
|---|---|---|
true | PAY_COMPLETE | 결제가 이미 완료됐어요. 토스가 인증 완료와 동시에 자동으로 승인했어요. |
false | PAY_APPROVED | 구매자 인증만 완료된 대기 상태예요. 가맹점이 승인 API를 호출해야 결제가 완료돼요. |
retUrl은 화면 이동용이에요. retUrl 파라미터만 보고 주문을 완료 처리하지 마세요. 결제 완료의 최종 확인은 다음 단계에서 다루는 콜백 수신 또는 결제 상태 확인 API로 해야 안전해요.
네이티브 앱에서 연동하는 경우 (App to App)
가맹점 자체 앱(iOS/Android)에서 결제하는 경우, 결제 생성 시 retAppScheme 파라미터에 앱 스킴 값(예: testshop://)을 함께 전달하면 인증 완료 후 가맹점 앱으로 복귀시킬 수 있어요. iOS는 자동으로 앱 전환이 되지 않아서 retAppScheme 구현을 권장해요.
이때 두 파라미터의 역할이 달라요.
retUrl은 App to App 환경에서도 여전히 필수예요.autoExecute값과 무관하게 항상 호출되고,status값만 다르게 전달돼요.retAppScheme은 가맹점 앱을 포그라운드로 복귀시키는 용도예요. 결제 결과 정보는 담고 있지 않아요.
승인 처리는 retUrl 기준으로 한 번만 트리거하세요. 웹뷰로 결제창을 감싼 구조에서는 인증 완료 시 retAppScheme과
retUrl이 각각 독립적으로 호출될 수 있어요. autoExecute: false로 승인 API를 직접 호출하는 가맹점이 retAppScheme
호출 시점에도 승인을 트리거하면, 동일 주문에 승인 요청이 중복 발생할 수 있어요.
다음 단계
인증까지 끝났으니 이제 결제를 완료하는 마지막 관문이 남았어요. 5. 결제 승인과 콜백 처리하기에서 autoExecute 설정별 완료 처리 방법을 알아봐요.