pending은 결제 결과가 아직 확정되지 않았다는 뜻이고 failed는 해당 시도가 성공하지 못했다는 뜻입니다. pending 상태에서는 같은 주문을 다시 결제하지 말고 payment hash와 HTLC 상태를 조회하세요. failed라면 인보이스 만료, 네트워크, 송신 아웃바운드·수신 인바운드 유동성, 경로별 수수료·CLTV 제한을 확인한 뒤 새 인보이스가 필요한지 판단합니다.
세 상태를 한 화면 문구로 단정하지 않습니다
라이트닝 결제는 인보이스를 읽은 뒤 경로를 찾고, 각 홉에 HTLC를 추가하고, 수신자가 preimage를 공개하면 역방향으로 정산됩니다. 이 과정이 끝나기 전 지갑은 pending을 표시할 수 있습니다. 앱을 닫거나 화면이 멈췄다는 이유만으로 HTLC가 사라진 것은 아닙니다.
failed는 시도한 경로가 완성되지 않았다는 결과이지만 인보이스 전체가 영구 무효라는 뜻은 아닐 수 있습니다. 다른 경로로 재시도할 수 있고, 반대로 만료·잘못된 payment details처럼 새 인보이스가 필요한 실패도 있습니다. 오류 문구, payment hash, 시도 시각을 함께 기록하세요.
pending 결제에서 가장 먼저 할 일은 다시 보내는 것이 아니라 같은 payment hash의 최종 상태를 확인하는 일입니다.
JOBCOIN 해설
그림은 이 주제의 공통 개념을 단순화한 설명입니다. 아래 항목에서 이 글의 구체적인 조건과 예외를 함께 읽어보세요.
- 세 상태를 한 화면 문구로 단정하지 않습니다
라이트닝 결제는 인보이스를 읽은 뒤 경로를 찾고, 각 홉에 HTLC 를 추가하고, 수신자가 preimage를 공개하면 역방향으로 정산됩니다.
- payment hash로 기존 시도를 먼저 묶습니다
같은 인보이스를 여러 번 눌러도 구현이 동일 payment hash의 중복 결제를 막을 수 있지만 모든 앱과 판매 시스템의 표시가 같지는 않습니다.
- 경로에는 방향별 용량과 정책이 모두 필요합니다
송신자는 첫 채널에서 지급액과 수수료를 내보낼 아웃바운드 유동성 이 필요하고 수신자는 마지막 채널에서 받을 인바운드 유동성이 필요합니다.
AI로 제작한 개념도 · 실제 가격·거래 내역·통계가 아닙니다.
payment hash로 기존 시도를 먼저 묶습니다
같은 인보이스를 여러 번 눌러도 구현이 동일 payment hash의 중복 결제를 막을 수 있지만 모든 앱과 판매 시스템의 표시가 같지는 않습니다. 주문서 화면이 새 인보이스를 발급해도 첫 결제가 뒤늦게 성공할 수 있으므로 송신 지갑의 payment lookup과 수신자 주문 상태를 모두 확인해야 합니다.
성공한 결제에는 수신자가 제공한 preimage가 대응합니다. 사용자는 preimage를 공개 게시판에 올릴 필요는 없지만 분쟁 시 지갑의 성공 기록과 payment hash, 금액, 수신 설명을 보관할 수 있습니다. 탐색기에서 온체인 txid를 찾는 방식으로 라이트닝 완료를 확인하려 해서는 안 됩니다.
| 상태 | 의미 | 다음 행동 |
|---|---|---|
| pending | HTLC 결과 미확정 | 동일 hash 조회·재결제 중단 |
| failed | 해당 시도 실패 | 실패 코드·만료·유동성 점검 |
| succeeded | preimage로 정산 완료 | 주문 반영과 영수 기록 |
| unknown | 로컬 기록 불충분 | 노드·지갑 백엔드 재조회 |
경로에는 방향별 용량과 정책이 모두 필요합니다
송신자는 첫 채널에서 지급액과 수수료를 내보낼 아웃바운드 유동성이 필요하고 수신자는 마지막 채널에서 받을 인바운드 유동성이 필요합니다. 중간 채널도 해당 방향의 잔액, 최소·최대 HTLC, 수수료, CLTV delta 정책을 만족해야 합니다. 총 채널 용량만 보고 경로가 있다고 판단하면 안 됩니다.
BOLT 2는 채널 reserve나 dust 노출을 침범하는 HTLC 제안을 제한합니다. 노드가 온라인이어도 정책과 용량이 맞지 않으면 실패할 수 있습니다. 금액을 임의로 잘게 나누면 MPP 지원과 인보이스 feature 조건이 필요하므로 지갑의 공식 재시도 기능을 우선하세요.
- payment hash와 인보이스 만료 시각을 확인합니다.
- 기존 시도의 pending HTLC가 남았는지 조회합니다.
- 송신 아웃바운드와 수신 인바운드 유동성을 구분합니다.
- 수수료 한도와 최대 CLTV 한도를 확인합니다.
- failed일 때만 지갑의 공식 재시도 또는 새 인보이스를 사용합니다.
시간 초과는 즉시 잔액 손실을 뜻하지 않습니다
HTLC에는 만료 높이가 있어 완료되지 않으면 결국 실패 경로로 해제돼야 합니다. 중간 노드 비가동이나 통신 문제로 UI가 오래 pending이어도 온체인 계약과 채널 상태가 안전하게 정리될 시간을 기다릴 수 있습니다. 지갑이 표시한 보류 잔액과 사용 가능 잔액을 구분하세요.
강제 종료가 함께 발생하면 온체인 timeout 경로와 확인 대기가 필요할 수 있습니다. 단순 결제 pending 단계에서 앱 데이터를 삭제하거나 오래된 채널 백업을 덮어쓰면 진단이 더 어려워집니다. 로그를 보존하고 사용 중인 구현의 복구 절차를 따르세요.
재시도는 실패 원인에 맞춰 범위를 줄입니다
인보이스가 만료됐다면 수신자에게 새 인보이스를 요청합니다. 유동성 부족이면 더 작은 금액 또는 다른 채널·경로가 도움이 될 수 있지만 주문 금액을 임의 변경해서는 안 됩니다. 수수료 한도가 너무 낮다면 예상 최대 비용을 확인하고 지갑 제한을 조정합니다.
수신자 offline 또는 잘못된 payment details라면 반복 시도는 성공 가능성을 높이지 않고 개인정보와 라우팅 실패만 더 남길 수 있습니다. 재시도 횟수와 간격에 상한을 두고 같은 오류가 반복되면 중단하세요. 자동화는 무한 재시도 대신 명확한 실패 상태와 사용자 확인 경로를 제공해야 합니다.
운영 로그는 시도와 주문을 분리합니다
한 주문에 여러 routing attempt가 있을 수 있고 한 인보이스 결제는 여러 부분 결제로 구성될 수도 있습니다. 시도 건수와 실제 지급 건수를 같은 지표로 세면 실패율과 중복 결제를 잘못 계산합니다. 주문 ID 아래 invoice, payment hash, attempt, 최종 settlement를 계층적으로 저장하세요.
지원 담당자는 사용자의 시드나 macaroon을 요구하지 않고 시간, 금액, payment hash와 비밀을 제거한 오류 코드만 받아야 합니다. successful 기록과 주문 미반영 문제는 라우팅 장애가 아니라 판매자 애플리케이션 정합성 문제일 수 있으므로 담당 범위를 구분합니다.
자주 묻는 질문
pending이면 돈이 사라진 건가요?
결과가 아직 확정되지 않은 상태입니다. 사용 가능 잔액에서 잠시 빠져 보일 수 있으나 같은 payment hash의 최종 상태를 먼저 확인하세요.
failed 뒤 같은 인보이스를 다시 써도 되나요?
만료 전이고 실패 원인이 재시도 가능한 경로 문제라면 지갑이 재시도할 수 있습니다. 만료·수신자 오류라면 새 인보이스가 필요합니다.
온체인 탐색기에서 결제 txid를 찾을 수 있나요?
일반 라이트닝 결제는 채널 밖 개별 txid로 나타나지 않습니다. 지갑의 payment hash와 preimage 기반 기록을 사용하세요.
더 깊이 읽기
본문에서 다룬 개념과 확인 절차를 다음 글에서 이어서 살펴보세요.
