# 결제창 연동 가이드

출처 https://www.groble.im/help/guides/payment-module

전체 가이드 목록 https://www.groble.im/llms.txt

---

이 문서는 그로블 결제창을 연결하는 분들을 위한 가이드예요.  
결제창이 무엇이고, 어떻게 만들고, 실제로 어떻게 활용하면 되는지 단계별로 안내해 드려요.

---

## 결제창이란?

### 결제창은 **링크 하나로 어디든 붙일 수 있는 결제 페이지**예요.

-   자사몰, SaaS, 랜딩페이지 등 어디든 링크만 붙이면 결제를 받을 수 있어요.
    
-   구매자는 **계정 가입 없이 휴대폰 인증만으로** 결제해요. (앱카드·카카오페이·네이버페이·카드 할부 지원)
    
-   판매 페이지가 '상품을 소개하는 페이지'라면, 결제창은 '결제만 받는 링크'예요. 이미 내 채널에서 상품을 충분히 소개하고 있다면 결제창이 더 간편해요.
    

---

## 기본 연동 (모든 판매자)

> 링크를 만들어 내 채널에 붙이고 테스트하는 기본 흐름이에요. 일반 판매는 이 단계까지면 충분해요.

### STEP 0. 결제창 생성하기

먼저 판매에 활용할 결제창을 만들어요.

1.  **내 스토어 → 상품 관리** 로 이동해요.
    
2.  **\[상품 등록하기\]** 를 눌러 결제창을 만들어요.
    
3.  아래 3단계로 진행돼요.
    
    **① 상품 상세** : 상품명·가격·수량·할인을 입력해요.
    
    **② 결제창 커스텀** : 테마·레이아웃·구매 버튼 등 결제창 디자인을 설정해요.
    
    **③ 판매하기** : 검수 정보(상품 설명)와 **진입·이동 페이지**를 설정해요. (아래 참고)
    

---

### STEP 1. 결제 링크 복사하기

결제창을 만들면 전용 링크가 생겨요.

1.  **내 스토어 → 상품 관리** 로 이동해요.
    
2.  생성한 결제창을 선택하고 **링크 복사** 를 눌러요.
    
3.  이 링크를 아래 채널 어디든 붙이면 돼요.
    

---

### STEP 2. 내 채널에 붙이기

결제창은 **자사몰·랜딩 페이지·SaaS처럼 내가 운영하는 사이트에 붙일 때** 가장 잘 맞아요.  
이미 상품을 소개하는 페이지가 있고, 거기에 '결제'만 연결하면 되니까요.

**1\. 자사몰 (아임웹·카페24·식스샵 등)**

-   가장 많이 쓰는 방식이에요.
    
-   버튼 요소를 추가하고, 버튼 클릭 시 이동할 주소(URL)에 결제 링크를 붙여넣어요.
    
-   기존 '구매하기' 버튼을 결제창 링크로 연결할 수도 있어요.
    

**2\. 랜딩 페이지**

-   상품·서비스를 소개하는 랜딩 페이지의 'CTA 버튼'(신청하기·구매하기 등)에 결제 링크를 연결해요.
    
-   소개를 충분히 한 뒤 바로 결제로 이어지게 만들 수 있어요.
    

**3\. SaaS·웹사이트에 직접 삽입**

-   내 서비스 화면 안에서 결제를 받고 싶다면, 버튼에 결제 링크를 연결해요.
    
-   HTML을 직접 다룰 수 있다면 아래처럼 버튼에 연결할 수 있어요.
    

```html
<a href="결제_링크_주소" target="_blank">구매하기</a>
```

> ### **💬 HTML을 잘 모른다면, AI에게 시켜보세요**
>
> ChatGPT·클로드 같은 AI에게 아래처럼 요청하면 버튼 코드를 바로 만들어줘요. **결제 링크 주소만 본인 것으로 바꿔서** 복사해 쓰세요.
>
> > 아래 결제 링크로 이동하는 '구매하기' 버튼 HTML 코드를 만들어줘.
> > 
> > -   결제 링크: `[https://groble.im/payment/내-결제창-주소](https://groble.im/payment/내-결제창-주소)`
> >     
> > -   버튼을 누르면 새 탭에서 열리게 해줘
> >     
> > -   버튼 색은 민트색, 글자는 흰색, 모서리는 둥글게
> >     
> > -   모바일에서도 잘 보이게 해줘 코드만 알려주고, 어디에 붙여넣는지도 설명해줘.
> >     
>
> 만든 코드를 자사몰·랜딩의 'HTML 삽입' 또는 '코드 블록' 영역에 붙여넣으면 돼요. 원하는 디자인(색·문구·크기)이 있으면 프롬프트에 자유롭게 추가하세요.
>
> > ⚠️ AI가 만든 코드에 **결제 링크 주소가 정확히 들어갔는지** 꼭 확인하세요. 주소가 틀리면 결제창이 열리지 않아요.

**4\. 링크 모음 사이트 (링크트리·인포크링크 등)**

-   여러 상품의 결제창을 한 곳에 모을 때 좋아요.
    
-   버튼/블록을 만들고 각 결제 링크를 연결한 뒤, 그 페이지 주소를 프로필 등에 걸어요.
    

**5\. SNS·메신저 (인스타그램·카카오톡 등)**

-   별도 사이트 없이 빠르게 안내하고 싶을 때 써요.
    
-   인스타그램 프로필 링크·스토리 링크 스티커, 카카오톡 채널·오픈채팅 공지 등에 결제 링크를 붙여넣어요.
    

> 💡 SNS·메신저에서 상품을 처음 소개하는 거라면, 결제창보다 **판매 페이지**가 더 잘 맞을 수 있어요. 결제창은 이미 소개가 끝난 곳에 '결제'를 붙이는 데 강해요.

---

### STEP 3. 진입·이동 페이지 설정하기

결제창을 만들 때 **3단계 '판매하기'** 에서 구매자의 이동 경로를 설정해요. 아래 흐름을 참고하세요.

![image.png](https://image.groble.im/article/2026/06/bf1dc600-7d5a-4859-8e09-a1f2b1111dab_image.png)

**진입 페이지 (필수)**

-   결제창을 붙일 페이지 주소예요.
    
-   구매자가 결제창에서 **뒤로가기를 누르거나 결제 완료 화면을 닫으면 이 페이지로 돌아가요.**
    
-   입력한 주소는 그로블 검수에도 활용돼요.
    

**이동 페이지 (선택)**

-   결제를 마친 구매자가 이동할 페이지예요.
    
-   입력하면 결제 완료 화면에 **'주문조회' 대신 이동 버튼**이 표시돼요.
    
-   비워두면 기본 '주문조회'가 유지돼요.
    

**이동 버튼 문구**

-   이동 페이지를 입력하면 나타나요.
    
-   결제 완료 화면의 버튼에 표시될 문구예요. (예: 쇼핑 계속하기)
    

---

### STEP 4. 연결 후 꼭 테스트하기

판매를 시작하기 전에 한 번만 확인해주세요.

1.  **모바일에서** 결제 링크를 직접 열어봐요. (구매자 대부분이 모바일로 접속해요)
    
2.  결제창이 잘 뜨는지, 상품명·가격이 맞는지 확인해요.
    
3.  뒤로가기·결제 완료 시 설정한 페이지로 이동하는지 확인해요.
    
4.  `?ref=`를 사용한다면, 테스트 결제 후 **웹훅에 참조값이 그대로 도착하는지** 확인해요. (개발자라면 결제 진행 시 주문 생성 응답의 `sellerReference` 필드로도 수용 여부를 바로 확인할 수 있어요 — 폐기됐다면 `null`로 표시돼요)
    

---

## 심화 연동 (SaaS·회원제 서비스 판매자)

> SaaS나 회원제 서비스를 운영하는 분들을 위한 선택 단계예요. 일반 판매는 STEP 5까지면 충분해요.

SaaS나 회원제 서비스를 운영한다면, 결제한 구매자를 서비스의 회원이나 주문과 연결해야 할 수 있어요. 결제 링크에 `?ref=`로 참조값을 추가하면, 결제 완료 웹훅에서 같은 값을 받아 자동으로 연결할 수 있어요.

### 회원·주문 연동하기 (?ref=)

결제한 구매자를 서비스의 회원이나 주문과 연결해야 할 수 있어요. 결제 링크에 `?ref=`로 참조값을 추가하면, 결제 완료 웹훅에서 같은 값을 받아 자동으로 연결할 수 있어요.

### 연동 방식

1.  내 서버에서 회원 또는 주문에 대응하는 참조값을 생성하고, 관련 정보를 함께 저장해요.
    
2.  결제창 링크 뒤에 `?ref=참조값`을 붙인 상태로 구매자를 이동시켜요.
    
3.  구매자가 결제를 완료하면 웹훅의 `data.object.sellerReference` 필드로 참조값이 전달돼요.
    
4.  내 서버에 저장된 정보와 참조값을 대조해 결제 결과를 반영해요.
    

정기결제 상품은 최초 결제뿐 아니라 이후 갱신 결제 웹훅에도 같은 참조값이 전달돼요.

```text
https://groble.im/payment/내-상품-ID?ref=ord_9f1c2e7a4b6d
```

### 참조값 입력 규칙

-   **영문 대소문자와 숫자,** `**-**`**,** `**_**`**,** `**.**`**,** `**:**`**,** `**=**`**,** `**~**`**만 사용할 수 있어요.**
    
-   길이는 1자 이상 128자 이하여야 해요.
    
-   **허용되지 않은 문자가 포함되거나 128자를 초과**하면 참조값 전체가 폐기돼요. 결제는 정상적으로 진행되지만 웹훅에는 `sellerReference`가 포함되지 않아요.
    
-   값을 인코딩해야 한다면 표준 base64 대신 **base64url**을 사용하세요. 표준 base64에서 생성될 수 있는 `+`, `/`는 허용되지 않아요.
    

### 안전한 참조값 만들기

참조값은 구매자의 주소창에 노출되고 직접 변경될 수 있어요. **따라서** `**user_5**`**와 같은 순번 ID나 이메일·전화번호 같은 개인정보를 그대로 넣지 마세요.**

UUID나 추측하기 어려운 랜덤 토큰을 사용하고, 해당 값이 어떤 회원 또는 주문을 가리키는지는 내 서버에서 관리하는 방식을 권장해요.

### 연동 확인하기

연동 후에는 테스트 결제를 한 건 진행해 참조값이 정상적으로 전달되는지 확인해 주세요.

-   주문 생성 응답의 `sellerReference`가 전달한 값과 같은지 확인해요. 형식에 맞지 않아 폐기된 경우 `null`로 표시돼요.
    
-   결제 완료 웹훅의 `data.object.sellerReference`에도 같은 값이 포함되는지 확인해요.
    
-   결제 완료 여부는 서명 검증을 통과한 웹훅을 기준으로 처리해요.
    

웹훅 수신 주소 등록, 서명 검증 방법과 참조값의 상세 규격은 [웹훅 연동 가이드](https://groble.im/help/guides/webhook)에서 확인해 주세요.

---

## 자주 묻는 질문

**Q. 구매자도 그로블 계정이 필요한가요?**

아니요. 구매자는 휴대폰 인증만으로 결제해요. 별도 가입이 필요 없어요.

**Q. 어떤 결제 수단을 쓸 수 있나요?**

앱카드, 카카오페이, 네이버페이를 지원해요.

**Q. 결제한 사람이 우리 서비스의 어떤 회원인지 알 수 있나요?**

네. 결제 링크에 `?ref=`로 참조값을 추가하면 결제 완료 웹훅으로 같은 값을 받아 회원과 자동으로 연결할 수 있어요.

**Q. 환불은 어떻게 처리하나요?**

구매자는 구매 후 7일 이내 취소를 요청할 수 있고, 판매자가 승인·반려를 처리해요. 정산 전이라면 판매자가 직접 환불할 수도 있어요.