Stripe

관리자 위치: Finance › Payment channels › Stripe (/payments/stripe). 스위치 및 수수료: Finance › Payment channels › Fees & limits (/payments/fees).

작동 내용

Stripe는 크레딧 충전 시 카드 결제를 처리합니다. 동일한 계정을 통해 Apple Pay, Google Pay, Link, Alipay를 제공할 수 있으며, 고객이 자동 충전을 위해 카드를 저장할 수 있도록 허용합니다. 해외 고객을 위한 기본 채널로 사용하세요.

요구 사항

항목	요구 사항
Stripe 계정	USD 단위로 결제를 수락할 수 있는 Stripe 계정입니다. Alipay는 JPY로 청구되며 Stripe에서 계정에 활성화해야 합니다.
키	시크릿 키(sk_live_... 또는 sk_test_...)와 퍼블리시드 키(pk_live_... 또는 pk_test_...)입니다. 양식에서는 이러한 접두사가 있는 키만 허용됩니다.
네트워크	패널이 인터넷을 통해 HTTPS로 접근 가능해야 하며(Stripe가 웹훅을 호출함), 포트 443에서 api.stripe.com에 도달할 수 있어야 합니다.
도메인(지갑 전용)	고객용 도메인은 /.well-known/apple-developer-merchantid-domain-association을(를) 지원해야 하며, NexCMP가 이를 자동으로 처리합니다.
의존성	없음.

공유 Stripe 계정

NexCMP는 자체적으로 생성한 결제에 대한 웹훅 이벤트만 처리하므로, 다른 애플리케이션에서도 사용하는 Stripe 계정을 함께 사용할 수 있습니다.

인프라 준비

Stripe 측 작업:

1. Stripe Dashboard에 로그인합니다. Test mode을 켜거나 꺼서 테스트 실행인지 실제 운영인지 결정합니다. 한 모드의 키는 다른 모드에서 절대 작동하지 않습니다.
2. Developers › API keys를 엽니다. Publishable key을 복사하고 Secret key를 표시하여 복사합니다. 시크릿 키는 비공개로 유지하세요.
3. (선택 사항) Settings › Payment methods를 열고 제공하려는 경우 Alipay를 활성화합니다.
4. 수동으로 웹훅을 만들 필요는 없습니다. NexCMP가 자동으로 생성해 줄 수 있습니다(아래 5단계 참조). 수동으로 하려면 Developers › Webhooks에서 URL과 이벤트 목록(Webhook 참조)을 사용하여 엔드포인트를 만드세요.

NexCMP에서 연결

1. Finance › Payment channels › Stripe(/payments/stripe)를 엽니다.
2. API keys 카드에서 Mode(live 또는 test)를 선택하고 Secret key와 Publishable key를 붙여넣습니다.
3. Save를 클릭합니다. 키는 NexCMP 서비스 계정만 읽을 수 있는 서버의 설정 파일에 기록됩니다. 브라우저로 다시 전송되지 않으며, 이후 페이지에는 마지막 4자만 표시됩니다.
4. Check를 클릭합니다. 대화상자에 연결 상태, 모드, 사용 가능 및 보류 중인 잔액, 계정 ID, 청구 활성화 여부, 웹훅 존재 여부, Alipay 사용 가능 여부가 보고됩니다. 빨간색 선은 해당 부분에 주의가 필요함을 의미합니다.
5. Webhook 카드에서 Create webhook을 클릭하고 확인합니다. NexCMP가 Stripe에 필요한 모든 이벤트가 포함된 엔드포인트 생성을 요청하고 Webhook signing secret(whsec_...)을 자동으로 채웁니다. 필드에 미리 채워진 URL은 https://<your-domain>/v1/billing/stripe/webhook이며(예: https://cloud.example.com/v1/billing/stripe/webhook),
6. Fees & limits(/payments/fees)를 열고 **Card (Stripe)**를 켠 상태로 유지한 다음, Stripe fee % 및 **Stripe fixed fee (cents)**를 실제 요율로 설정하고 Save channels & fees를 클릭합니다. Payment channels를 참조하세요.

웹훅

"Missing webhook_secret" 빨간색 배너는 서명 비밀이 저장될 때까지 유지됩니다. 이 비밀이 없으면 Stripe에서 돈을 가져갔더라도 Stripe 충전이 기록되지 않습니다.

항목	값
URL	https://<your-domain>/v1/billing/stripe/webhook
이벤트	checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
서명	Stripe Stripe-Signature 헤더, HMAC-SHA256, 300초 허용 오차. 잘못된 서명이 포함된 요청은 HTTP 400을 반환합니다.
멱등성	각 이벤트 ID는 한 번만 저장되므로 중복 전달로 인해 크레딧이 두 번 적립되지 않습니다.

더 적은 수의 이벤트를 등록했던 릴리스에서 업그레이드한 경우 Create webhook을 다시 클릭하세요. 기존 엔드포인트는 유지되므로 나중에 Stripe Dashboard에서 수동으로 삭제해야 합니다.

Webhook 카드의 24h events 및 Latest event 행은 Stripe가 패널에 정상적으로 도달하고 있는지 알려줍니다. 개별 이벤트는 Payment channels › Gateway events(/payments/events, Stripe 탭)에 나열되며, 각 이벤트는 내용 확인(Payload) 또는 재전송(Replay)이 가능합니다.

Apple Pay, Google Pay 및 Link

1. Wallets (Apple Pay · Google Pay · Link) & Alipay 카드의 Customer app Domain registered with Stripe 필드에는 사이트의 호스트 이름(예: cloud.example.com)이 미리 채워집니다.
2. Register / verify domain을 클릭하고 확인합니다. NexCMP가 Stripe의 결제 수단 도메인에 해당 도메인을 등록하고 Stripe에 검증을 요청합니다.
3. 결과 창에 Apple Pay, Google Pay, Link의 상태가 표시됩니다. Apple Pay는 상태가 active일 때만 표시됩니다.
4. Fees & limits에서 Apple Pay · Google Pay · Link를 켭니다.

Apple Pay가 비활성화 상태로 유지되는 경우

Apple Pay는 공개 도메인에서 도메인 연결 파일이 HTTP 200으로 응답해야 합니다. Cloudflare나 다른 프록시를 사용하는 경우 /.well-known/을(를) 차단하지 마세요.

Alipay

Alipay는 선택 사항입니다. Stripe Dashboard › Settings › Payment methods에서 활성화하고, Check를 클릭한 뒤 대화 상자에 Alipay 사용 가능이 표시될 때까지 기다린 다음, **Alipay (Stripe, JPY display)**를 Fees & limits에서 켭니다. Alipay fee %, Alipay fixed fee, ¥/USD rate(50–500) 및 FX spread %(0–20)를 설정합니다. ¥/USD rate를 정기적으로 업데이트하십시오. 7일보다 오래되면 페이지에 경고가 표시됩니다.

확인

1. 테스트 모드에서 테스트 고객으로 포털에 로그인하고, Billing을 열고 Deposit을 클릭한 뒤 Card를 선택하고 Stripe 테스트 카드4242 4242 4242 4242(임의의 미래 날짜, 임의의 CVC)로 최소 금액을 결제하세요.
2. 잔액은 몇 초 안에 충전되며 결제 내역은 상태가 Completed로 표시된 채 Finance › Billing › Top-ups에 나타납니다.
3. Payment channels › Gateway events › Stripe을 엽니다. 처리 시간과 함께 checkout.session.completed 또는 payment_intent.succeeded가 표시되어야 합니다.
4. Stripe 페이지로 돌아가면 24h events가 0보다 큽니다.

라이브로 전환하기 전에 Mode를 live(으)로 전환하고 라이브 키를 붙여넣은 뒤 다시 Create webhook을 클릭하세요(테스트 모드와 라이브 모드의 웹훅은 별개입니다).

한도 및 참고 사항

• 금액 및 통화: 지갑 통화는 USD입니다. 카드, 지갑 및 링크 결제는 USD로 청구되며, Alipay는 고객에게 JPY로 표시되고 설정된 환율로 환산됩니다.
• 수수료: Stripe의 실제 수수료는 자동으로 다시 읽어오지 않으며, 설정한 수수료율에 따라 고객에게 표시되는 금액과 지갑에 적립되는 금액이 결정됩니다. 수수료를 추가로 청구하려면 Fees & limits에서 Customer pays top-up fee를 선택하세요.
• 저장된 카드: 고객이 Save card for auto top-up을 체크하면 카드가 내 서버가 아니라 Stripe에 저장됩니다. Saved payment methods를 참고하세요.
• 환불: 카드로 환불하는 과정은 2단계로 이루어집니다. 관리자가 완료된 결제에 대해 환불 요청을 생성하고(Finance › Billing › Top-ups에서 해당 결제의 환불 작업 실행) Finance › Payouts › Card refunds(/billing/payouts)에서 이를 승인합니다. Alipay 환불은 비동기식이며, 실패한 환불(refund.failed)은 보류된 금액을 지갑으로 돌려줍니다.
• 분쟁: charge.dispute.created NexCMP에서는 고객의 계정을 차단하고 선불 서비스를 중지하며(삭제되는 것은 없음) 관리자 알림을 보냅니다. 분쟁에서 승소한 경우(charge.dispute.closed), 해당 금액이 지갑으로 다시 적립됩니다.
• 대기 중인 결제: 웹훅이 도착하지 않는 경우, NexCMP는 10분 이상 대기 상태로 유지된 결제를 Stripe와 자체적으로 대조하여 완료 처리합니다. 7일이 지난 결제는 무시됩니다.
• Resellers는 자신의 Stripe 계정(웹훅 https://<their-domain>/v1/billing/stripe/webhook/r/<id>)을 연결할 수 있습니다. Resellers를 참고하세요.

Troubleshooting

증상	원인	해결 방법
"Secret key는 sk_live_/sk_test_로 시작해야 합니다"	잘못된 키가 붙여넣어짐	Developers › API keys에서 시크릿 키를 복사하여 붙여넣으세요.
"Secret key가 라이브/테스트 모드와 일치하지 않습니다"	모드와 키가 일치하지 않음	Mode이(가) 키의 접두사와 일치하도록 만드세요.
"Publishable key는 pk_로 시작해야 합니다"	Wrong key	공개 키를 사용하세요.
연결에 실패했습니다	잘못된 키, 폐기된 키 또는 서버가 api.stripe.com에 도달할 수 없음	키를 다시 붙여넣고 서버에서 curl -I https://api.stripe.com(으)로 테스트하세요.
빨간색 배너 "Missing webhook_secret"	서명 비밀키가 저장되지 않음	Create webhook을(를) 클릭하거나 Stripe 대시보드에서 whsec_... 비밀키를 붙여넣은 후 Save을(를) 클릭하세요.
금액은 출금되었으나 잔액이 변경되지 않음	웹훅이 전달되지 않았거나 서명 검증에 실패함	URL이 /v1/billing/stripe/webhook(으)로 끝나고, 비밀키가 엔드포인트와 일치하는지 확인한 후 Gateway events에서 이벤트를 다시 재생하세요. Stripe에서 엔드포인트를 열고 전송 시도 내역을 확인하세요(HTTP 400은 서명 비밀키가 잘못되었음을 의미합니다).
"Create webhook" fails	URL이 HTTPS가 아니거나 접근할 수 없음	공개 https:// 도메인을 사용하세요.
Apple Pay 상태가 활성화되지 않음	Domain not validated	도메인 연결 파일이 200 응답을 반환한 후 Register / verify domain을(를) 다시 클릭하세요.
확인 대화상자에 Alipay가 표시되지 않음	Not activated at Stripe	Stripe 대시보드에서 활성화한 후 Check을(를) 클릭하세요.
고객에게 카드 양식이 표시되지 않음	**Card (Stripe)**이(가) 꺼져 있거나 비밀키가 없음	Fees & limits에서 켜고 키를 저장하세요.