결제 결과와 거래 기록 처리

결제 완료 판단에는 Wallet API 거래를 기준으로 사용합니다. 네트워크 타임아웃이나 생성 응답 유실이 거래 실패를 의미하지는 않습니다.

거래 ID로 결과 확인

생성 응답에서 withdrawal_id를 받았다면 거래를 직접 조회합니다.

payment_result="$(wallet_request GET "/withdrawals/$PAYMENT_WITHDRAWAL_ID")"
printf '%s\n' "$payment_result" | jq

request_type이 INTERNAL이고 status와 user_status가 모두 COMPLETED일 때만 주문을 결제 완료로 처리합니다.

유실된 생성 응답 복구

백엔드가 withdrawal_id를 받기 전에 요청이 타임아웃되었다면 기존 client_request_id로 조회합니다. 새 ID를 만들어 두 번째 결제를 요청하지 마십시오.

payment_recovery_response="$(
  wallet_request GET "/withdrawals/client-request/$PAYMENT_REQUEST_ID"
)"

export PAYMENT_WITHDRAWAL_ID="$(
  printf '%s' "$payment_recovery_response" | jq -r '.data.withdrawal_id'
)"

wallet_request GET "/withdrawals/$PAYMENT_WITHDRAWAL_ID" | jq

client_request_id는 응답 유실 복구와 업무 멱등 추적에 사용하고, withdrawal_id는 생성된 거래의 상세 상태 조회에 사용합니다.

복구 응답의 success와 withdrawal_id를 확인한 뒤 상세 조회를 실행합니다. WITHDRAWAL_NOT_FOUND가 한 번 반환됐다는 이유만으로 새 결제를 생성하지 마십시오. 원본 요청이 아직 처리 중일 수 있으므로 기존 요청 ID를 유지해 제한된 간격으로 다시 조회하고, 계속 확인되지 않으면 멱등성과 중복 요청 방지에 따라 처리합니다.

결제 기록 저장

최소한 다음 정보를 저장합니다.

필드	용도
고객사 주문 ID	Wallet 거래와 업무 주문 연결
client_request_id	중복 제출 방지와 생성 결과 복구
withdrawal_id	거래의 확정 상태 조회
고객·가맹점 계정 ID	자금 이동 방향 보존
자산·금액·최종 상태	결제 대사
완료 시각	정산과 리포트

완료 후 양쪽 잔액을 정합성 확인용으로 조회합니다.

wallet_request GET "/accounts/$USER_ACCOUNT_ID/balances/$ASSET_TYPE_ID" | jq
wallet_request GET "/accounts/$PAYMENT_ACCOUNT_ID/balances/$ASSET_TYPE_ID" | jq

동시 결제가 있을 수 있으므로 잔액 차이만으로 개별 주문의 성공 여부를 판단하지 마십시오.

다음: 외부 주소로 정산·지급