--- title: Stripe description: Stripe를 NexCMP에 연동하여 카드 결제, Apple Pay, Google Pay, Link 및 Alipay를 지원하세요 (API 키, 웹훅, 도메인 등록 및 테스트 결제). url: https://nexcmp.com/ko/docs/billing/stripe/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Stripe > **관리자 위치:** Finance › Payment channels › Stripe (`/payments/stripe`). 스위치 및 수수료: Finance › Payment channels › Fees & limits (`/payments/fees`). ## 작동 내용 {#what-it-does} Stripe는 크레딧 충전 시 카드 결제를 처리합니다. 동일한 계정을 통해 **Apple Pay**, **Google Pay**, **Link**, **Alipay**를 제공할 수 있으며, 고객이 **자동 충전**을 위해 [카드를 저장](https://nexcmp.com/ko/docs/billing/auto-top-up/)할 수 있도록 허용합니다. 해외 고객을 위한 기본 채널로 사용하세요. ## 요구 사항 {#requirements} | 항목 | 요구 사항 | |---|---| | 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가 이를 자동으로 처리합니다. | | 의존성 | 없음. | ::: info 공유 Stripe 계정 NexCMP는 자체적으로 생성한 결제에 대한 웹훅 이벤트만 처리하므로, 다른 애플리케이션에서도 사용하는 Stripe 계정을 함께 사용할 수 있습니다. ::: ## 인프라 준비 {#prepare-the-infrastructure} Stripe 측 작업: 1. [Stripe Dashboard](https://dashboard.stripe.com)에 로그인합니다. **Test mode**을 켜거나 꺼서 테스트 실행인지 실제 운영인지 결정합니다. 한 모드의 키는 다른 모드에서 절대 작동하지 않습니다. 2. **Developers › API keys**를 엽니다. **Publishable key**을 복사하고 **Secret key**를 표시하여 복사합니다. 시크릿 키는 비공개로 유지하세요. 3. (선택 사항) **Settings › Payment methods**를 열고 제공하려는 경우 **Alipay**를 활성화합니다. 4. 수동으로 웹훅을 만들 필요는 **없습니다**. NexCMP가 자동으로 생성해 줄 수 있습니다(아래 5단계 참조). 수동으로 하려면 **Developers › Webhooks**에서 URL과 이벤트 목록([Webhook](#webhook) 참조)을 사용하여 엔드포인트를 만드세요. ## NexCMP에서 연결 {#connect-in-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:///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](https://nexcmp.com/ko/docs/billing/payment-channels/#switches-and-fees-fees-limits)를 참조하세요. ![모드, 시크릿 키, 퍼블리시드 키가 예시 값으로 채워진 Stripe 페이지](https://nexcmp.com/ko/docs/images/billing/stripe-01-keys.webp) ### 웹훅 {#webhook} "Missing webhook_secret" 빨간색 배너는 서명 비밀이 저장될 때까지 유지됩니다. 이 비밀이 없으면 Stripe에서 돈을 가져갔더라도 Stripe 충전이 **기록되지 않습니다**. | 항목 | 값 | |---|---| | URL | `https:///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 {#apple-pay-google-pay-and-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, Google Pay, Link 상태를 보여주는 지갑 카드](https://nexcmp.com/ko/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay가 비활성화 상태로 유지되는 경우 Apple Pay는 공개 도메인에서 도메인 연결 파일이 HTTP 200으로 응답해야 합니다. Cloudflare나 다른 프록시를 사용하는 경우 `/.well-known/`을(를) 차단하지 마세요. ::: ### Alipay {#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일보다 오래되면 페이지에 경고가 표시됩니다. ## 확인 {#verify} 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**을 클릭하세요(테스트 모드와 라이브 모드의 웹훅은 별개입니다). ## 한도 및 참고 사항 {#limits-notes} - **금액 및 통화:** 지갑 통화는 USD입니다. 카드, 지갑 및 링크 결제는 USD로 청구되며, Alipay는 고객에게 JPY로 표시되고 설정된 환율로 환산됩니다. - **수수료:** Stripe의 실제 수수료는 자동으로 다시 읽어오지 않으며, 설정한 수수료율에 따라 고객에게 표시되는 금액과 지갑에 적립되는 금액이 결정됩니다. 수수료를 추가로 청구하려면 *Fees & limits*에서 **Customer pays top-up fee**를 선택하세요. - **저장된 카드:** 고객이 *Save card for auto top-up*을 체크하면 카드가 내 서버가 아니라 Stripe에 저장됩니다. [Saved payment methods](https://nexcmp.com/ko/docs/billing/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:///v1/billing/stripe/webhook/r/`)을 연결할 수 있습니다. [Resellers](https://nexcmp.com/ko/docs/customers/resellers/)를 참고하세요. ## Troubleshooting {#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**에서 켜고 키를 저장하세요. |