결제가 실제 수취 확인 뒤에만 완료되는 이유

MaruPay 결제 화면에서 사용자는 안내에 따라 결제를 제출합니다. 그 순간을 결제 완료로 보면 편하겠지만, MaruPay는 그렇게 하지 않고 고객사 연동도 그러면 안 됩니다.

제출은 결제가 아닙니다

제출된 결제는 주장일 뿐입니다. 사용자는 잘못 입력하고, 중간에 멈추고, 버튼을 두 번 누릅니다. 제출 시점에 주문을 반영하면 이 모든 경우가 고객 문의와 수작업 정정으로 이어집니다. 그래서 MaruPay 결제는 실제 수취가 확인될 때까지 확인 중 상태로 남습니다.

정확히 한 요청, 아니면 확인 대상

확인된 수취는 열려 있는 결제 요청 중 정확히 한 건과 맞을 때만 결제를 완료합니다. 맞는 요청이 없거나 두 요청이 똑같이 맞으면 확인 대상으로 보냅니다. 운영자가 근거를 보고 맞는 결제에 귀속한 뒤에야 payment.completed가 나갑니다.

• 맞는 요청 없음: 수취는 확인 대상에서 기다리고, 고객사에는 아무것도 보내지 않습니다.
• 맞는 요청 둘 이상: 운영자가 맞는 요청을 고를 때까지 보류합니다.
• 요청 만료 후 수취: 만료된 주문을 완료하지 않고 확인 대상으로 보류합니다.

고객사 구매 흐름이 할 일

• 주문은 payment.completed에서만 반영하세요. 돌아오기 주소는 사용자가 돌아왔다는 뜻이지 결제가 완료됐다는 뜻이 아닙니다.
• 확인 중인 동안에는 사용자에게 기다리는 상태를 분명히 보여 주세요. 결제 화면도 그렇게 합니다.
• payment.expired가 오면 주문을 풀어 주세요.
• 확실히 알아야 하면 GET /v1/payments/{id}로 결제 상태를 조회하세요.

흔한 경우엔 몇 초 더 걸리지만, 나머지 모든 경우가 훨씬 조용해집니다. 고객사 전체에서 제출부터 수취 확인까지 중앙값은 38초이고, ‘결제했는데 아무 일도 없어요’로 시작하는 문의는 대부분 사라집니다.