API를 통해 SMM 패널 잔액 자동 충전을 설정하는 방법

자동 충전 설정 전 준비할 사항

자동 충전은 SMM 패널 잔액을 결제 서비스 또는 내부 빌링과 연결합니다. 서비스는 잔액을 확인하고, 지정된 임계값에 도달하면 결제를 생성하며, 결제 확인 후에만 자금을 입금합니다. 작업을 위해서는 패널 API 문서, 결제 API 접근 권한, 테스트 환경과 운영 환경용 별도 키, 그리고 모든 거래의 로그가 필요합니다.

개발 전에 패널 API가 잔액을 반환하고, 입금 요청을 받고, 충전 내역을 표시하고, 외부 거래 식별자를 받을 수 있는지 확인하세요. 패널이 API를 통한 입금을 지원하지 않는다면 자동화는 신청서를 생성하거나 운영자에게 알림을 보내는 것만 가능합니다. 이 방식의 단점은 어차피 자금을 수동으로 입금해야 한다는 것입니다.

잔액 확인과 결제 결정을 분리하세요

잔액 확인은 별도의 예약 작업으로 실행하는 것이 좋습니다. 이 작업은 잔액을 가져와 임계값과 비교하고 결과를 충전 처리기에 전달합니다. 현재 진행 중인 미완료 거래를 확인하지 않고 API 응답 시점에 바로 결제를 생성하지 마세요. 병렬 작업이 동일한 낮은 잔액을 보고 여러 건의 결제를 생성할 수 있습니다.

새 결제 전에 처리기는 «생성됨», «결제 대기», «확인 중» 상태의 거래가 있는지 확인해야 합니다. 그러한 기록이 있으면 대사가 완료될 때까지 새 시도를 실행하지 않습니다. 순차 처리의 단점은 외부 API 응답이 오래 걸릴 경우 여러 병렬 요청보다 충전이 늦게 시작될 수 있다는 것입니다.

임계값과 충전 금액 로직을 선택하세요

잔액 임계값은 활성 주문, 공급업체 대기열, 결제 지연을 고려한 여유를 두고 선택합니다. 활동이 불규칙한 채널의 경우 평균 지출만으로 판단하는 것은 위험합니다. 스트리밍, 광고 시작 또는 대량 주문 후에는 차감이 급격히 늘어날 수 있습니다. 별도로 알림이 오지만 결제가 반드시 자동으로 생성되지는 않는 임계 수준을 설정합니다.

충전 금액은 고정이거나 선택한 기간의 지출을 기준으로 계산할 수 있습니다. 고정 금액은 관리와 대사가 더 쉽습니다. 단점은 조용한 기간에는 잔액에 불필요한 자금이 남을 수 있고, 주문이 급증하면 한 번의 충전으로 부족할 수 있다는 것입니다. 계산된 금액은 더 유연하지만 비정상 차감과 환불로부터 통계를 정리해야 합니다.

재무 제한을 임계값과 별도로 설정하세요

임계값은 시스템이 충전 프로세스를 시작할 수 있는 시점에만 답합니다. 제한은 다른 질문에 답합니다. 시스템이 얼마나 차감할 수 있는지입니다. 한 건의 최대 금액, 기간별 총 한도, 입금 후 허용 잔액을 설정하세요. 이러한 규칙은 결제 후가 아니라 결제 생성 전에 확인됩니다.

자동 충전은 거래 및 기간 한도 없이 자금을 차감해서는 안 됩니다. 계산된 금액이 허용치를 초과하면 거래를 수동 검토로 전환하고 알림을 보내는 것이 좋습니다. 엄격한 한도의 단점은 지출이 빠르게 증가할 때 담당 직원이 한도 증액을 확인하기 전에 잔액이 소진될 수 있다는 것입니다.

별도 키를 생성하고 접근을 보호하세요

자동 충전 스크립트에는 최소 권한의 별도 API 키를 사용하세요. 잔액 읽기, 결제 생성, 상태 확인, 확인된 거래 입금 권한입니다. 사용자, 서비스 설정, 주문, 자금 인출에 대한 접근은 이러한 키에 필요하지 않습니다. 서비스가 IP 주소 제한을 지원한다면 연동 서버에서만 접근을 허용하세요.

키는 환경 변수 또는 보안 비밀 저장소에 보관합니다. 브라우저 코드, 로그, 공개 저장소, 오류 메시지에 키를 전달하지 마세요. 각 키에는 소유자와 명확한 교체 절차가 있어야 합니다. 잦은 키 교체의 단점은 모든 운영 프로세스에서 새 비밀을 업데이트하지 않으면 충전이 중단된다는 것입니다.

고유 식별자로 결제를 생성하세요

각 충전에는 결제 API 호출 전에 내부 식별자를 할당합니다. 이를 로그에 저장하고 멱등성 키 또는 외부 거래 번호로 전달합니다. 네트워크 타임아웃 시 동일한 식별자로 동일한 요청을 재시도할 수 있습니다. 결제 서비스는 자금을 다시 차감하는 대신 이미 생성된 거래를 반환해야 합니다.

아래는 일반적인 요청 예시입니다. 필드 이름과 주소는 특정 공급업체 문서의 값으로 교체하세요. PAYMENT_ID 변수에는 미리 생성된 고유 ID가 저장되고, CALLBACK_URL은 웹훅 처리기를 가리킵니다.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

금액과 생성 시간만으로 결제 고유성을 판단하지 마세요. 두 건의 동일한 충전이 정당할 수 있지만, 장애 후 반복 요청은 그렇지 않습니다. 자체 데이터베이스의 외부 ID 단점은 이를 안정적으로 저장하고 거래 취소 후 재사용하지 않아야 한다는 것입니다.

잔액을 확인하고 거래 상태를 저장하세요

잔액 요청은 새 충전 결정 전과 성공적인 입금 후에 실행되어야 합니다. 일반적인 요청은 다음과 같습니다: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". 응답에는 금액뿐만 아니라 확인 시간도 저장하여 오래된 데이터로 결정을 내리지 않도록 하세요.

각 거래에 대해 내부 ID, 공급업체 결제 ID, 금액, 통화, 생성 시간, 상태, API 응답, 오류 원인이 포함된 기록을 유지하세요. 적합한 상태 체인은 «생성됨», «결제 대기», «결제됨», «입금 중», «입금됨», «취소됨», «확인 필요»입니다.

패널 입금은 확인되었고 아직 처리되지 않은 결제에만 허용됩니다. 이력 없이 상태를 덮어쓰지 마세요. 분쟁 시 어떤 요청이 전송되었고 거래가 왜 변경되었는지 보여야 합니다. 상세 로그의 단점은 민감한 데이터가 포함될 수 있으므로 접근을 제한해야 한다는 것입니다.

웹훅을 수신하고 결제 상태를 대사하세요

결제 성공 페이지와 사용자 리디렉션은 자금 수령을 확인하지 않습니다. 확인은 결제 서비스의 웹훅 또는 해당 API를 통한 상태 재확인입니다. 웹훅 수신 시 서명, 전송 시간, 결제 ID, 외부 ID, 금액, 통화를 확인하세요. 그 후에만 거래를 결제 확인 상태로 전환합니다.

웹훅 확인 후 공급업체에 최신 결제 상태를 요청하는 것이 좋습니다. 예: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". 상태를 로그 데이터와 대사한 후 동일한 내부 ID로 SMM 패널에 입금 요청을 보냅니다.

반복 웹훅은 두 번째 입금을 생성해서는 안 됩니다. 처리기는 외부 ID로 거래를 찾고 «입금됨» 상태를 확인한 후 추가 작업 없이 성공 응답을 반환합니다. 웹훅의 단점은 처리기가 사용할 수 없었을 때 지연되거나 도달하지 않을 수 있다는 것입니다.

타임아웃, 재시도, 중단된 결제를 처리하세요

결제 생성 후 타임아웃 시 다른 ID로 새 요청을 보내지 마세요. 먼저 내부 식별자로 거래를 찾거나 동일한 멱등성 키로 요청을 반복하세요. 공급업체가 원래 요청을 수락했다면 기존 결제를 반환합니다. 이는 연결 끊김 시 이중 차감을 방지합니다.

지정된 시간 내에 웹훅이 오지 않으면 백그라운드 작업이 API를 통해 결제 상태를 요청합니다. 반복 확인은 API와 로그에 과부하를 주지 않도록 증가하는 간격과 제한된 시도 횟수로 수행합니다. 오랫동안 대기 상태로 남아 있는 거래는 대사 없이 취소된 것으로 간주하지 않고 수동 검토로 전환합니다.

일시적인 네트워크 오류 또는 API 사용 불가 응답 시 재시도가 허용됩니다. 결제 거부, 잘못된 금액, 유효하지 않은 웹훅 서명, 한도 초과 시에는 자동으로 요청을 반복하지 않는 것이 좋습니다. 재시도의 단점은 상태 로직을 복잡하게 만들고 공급업체의 대규모 장애 시 추가 부하를 생성할 수 있다는 것입니다.

확인된 결제를 SMM 패널에 입금하세요

입금 전에 처리기는 다시 한 번 확인합니다. 금액이 한도를 초과하지 않고, 통화가 일치하며, 거래가 취소되지 않았고 상태가 아직 «입금됨»이 아닌지 확인합니다. 요청에는 금액과 결제의 외부 식별자를 전달합니다. 패널 API가 멱등성 키를 지원하면 동일한 내부 거래 ID를 사용하세요.

일반적인 요청 형태: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

패널 응답 후 잔액을 다시 요청하고 결과를 로그에 저장하세요. 결제 서비스에서 자금이 차감되었지만 패널 API가 오류를 반환한 경우 새 결제를 생성하지 마세요. 거래는 입금 재시도 또는 수동 대사까지 «확인 필요» 상태로 유지됩니다. 이러한 신중한 방식의 단점은 잔액이 일시적으로 자동 충전되지 않을 수 있다는 것입니다.

알림, 스위치, 시작 확인을 추가하세요

알림은 이상 상황에 필요합니다. 잔액이 임계 수준 아래로 떨어짐, 결제 거부, 웹훅 미수신, 한도 초과, API 사용 불가, 거래 수동 검토 필요 등입니다. 메시지에는 내부 ID, 상태, 원인을 표시하면 충분합니다. API 키, 웹훅 서명, 결제 정보를 포함하지 마세요.

연동을 삭제하지 않고 자동 충전을 위한 별도 스위치를 남겨두세요. 공급업체 변경, 기술 작업, 오류 의심, 지출 급변 시 필요합니다. 스위치의 단점은 명백합니다. 작업 후 다시 켜지 않으면 활성 주문 중에 잔액이 소진될 수 있습니다.

자동 충전 활성화 전 체크리스트

• 미완료 거래가 있는 동안 잔액 확인이 결제를 생성하지 않습니다.
• 각 결제에 고유한 내부 ID와 멱등성 키가 생성됩니다.
• 한 건 및 선택한 기간에 대한 한도가 설정되어 있습니다.
• 웹훅은 서명, 금액, 통화, 식별자로 확인됩니다.
• 웹훅이 없으면 API를 통한 상태 재대사가 시작됩니다.
• 타임아웃 시 첫 번째 결제 확인 전에 두 번째 결제가 생성되지 않습니다.
• 패널 입금은 한 번만 수행되고 로그에 기록됩니다.
• 테스트 모드에서 성공, 거부, 웹훅 중복, API 사용 불가 상황을 확인했습니다.