refund.created, refund.updated, dispute.created, dispute.updated, dispute_alert.created에 대한 웹훅을 구독하면 폴링 없이 상태 변경을 조정할 수 있습니다.환불
환불은 성공한 결제를 되돌립니다. Whop은 원래의 결제 프로세서를 통해 환불을 처리합니다. 해당 멤버십 상태는 자동으로 업데이트됩니다.환불 발행
환불은 refunds 리소스에서 직접 생성하는 것이 아니라 결제에 대해 생성합니다.payments.refund({ id })를 호출하세요. 전액 환불이면 partial_amount를 생략하고, 부분 환불이면 이 값을 전달하세요.
import { WhopClient } from "@whop/sdk";
const client = new WhopClient({ token: process.env.WHOP_API_KEY });
// Full refund
const fullRefund = await client.payments.refund({ id: "pay_xxxxxxxxxxxxx" });
// Partial refund
const partialRefund = await client.payments.refund({
id: "pay_xxxxxxxxxxxxx",
partial_amount: 5.0, // in payment currency, e.g. 5 USD
});
import os
from whop_sdk import Whop
client = Whop(token=os.environ["WHOP_API_KEY"])
# Full refund
full_refund = client.payments.refund("pay_xxxxxxxxxxxxx")
# Partial refund
partial_refund = client.payments.refund(
"pay_xxxxxxxxxxxxx",
partial_amount=5.0,
)
require "whop_sdk"
client = Whop_sdk::Client.new(token: ENV.fetch("WHOP_API_KEY"))
# Full refund
full_refund = client.payments.refund(id: "pay_xxxxxxxxxxxxx")
# Partial refund
partial_refund = client.payments.refund(
id: "pay_xxxxxxxxxxxxx",
partial_amount: 5.0,
)
use whop_sdk::prelude::*;
let config = ClientConfig {
token: Some(std::env::var("WHOP_API_KEY").unwrap()),
..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");
// Full refund
let full_refund = client
.payments
.refund(&"pay_xxxxxxxxxxxxx".to_string(), &RefundPaymentsRequest::default(), None)
.await?;
// Partial refund
let partial_refund = client
.payments
.refund(
&"pay_xxxxxxxxxxxxx".to_string(),
&RefundPaymentsRequest {
partial_amount: Some(5.0), // in payment currency, e.g. 5 USD
},
None,
)
.await?;
import (
"context"
"log"
"os"
whopsdk "github.com/whopio/whopsdk-go/v2"
"github.com/whopio/whopsdk-go/v2/client"
"github.com/whopio/whopsdk-go/v2/option"
)
client := client.NewWhop(option.WithToken(os.Getenv("WHOP_API_KEY")))
// Full refund
_, err := client.Payments.Refund(context.TODO(), &whopsdk.RefundPaymentsRequest{
ID: "pay_xxxxxxxxxxxxx",
})
if err != nil {
log.Fatal(err)
}
// Partial refund
_, err = client.Payments.Refund(context.TODO(), &whopsdk.RefundPaymentsRequest{
ID: "pay_xxxxxxxxxxxxx",
PartialAmount: whopsdk.Float64(5.0), // in payment currency, e.g. 5 USD
})
if err != nil {
log.Fatal(err)
}
Payment 객체입니다. refunded_amount 필드는 누적 환불 총액을 반영합니다. 하나의 결제에 대해 전체 금액까지 refund를 여러 번 호출할 수 있습니다.
필요한 권한:
payment:manage. 앱을 게시하기 전에 권한 가이드에서 추가하세요.환불 조회
나중에 환불을 조회해야 하는 경우를 위해 환불에는 별도의 리소스가 있습니다.const refund = await client.refunds.retrieve({ id: "ref_xxxxxxxxxxxxx" });
const refunds = await client.refunds.list({
account_id: "biz_xxxxxxxxxxxxx",
});
for await (const item of refunds) {
console.log(item);
}
refund = client.refunds.retrieve("ref_xxxxxxxxxxxxx")
for item in client.refunds.list(account_id="biz_xxxxxxxxxxxxx"):
print(item)
refund = client.refunds.retrieve(id: "ref_xxxxxxxxxxxxx")
client.refunds.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
puts item
end
let refund = client
.refunds
.retrieve(&"ref_xxxxxxxxxxxxx".to_string(), None)
.await?;
let refunds = client
.refunds
.list(
&RefundsListQueryRequest {
account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
..Default::default()
},
None,
)
.await?;
for item in refunds.data {
println!("{item:?}");
}
refund, err := client.Refunds.Retrieve(context.TODO(), &whopsdk.RetrieveRefundsRequest{
ID: "ref_xxxxxxxxxxxxx",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(refund)
page, err := client.Refunds.List(context.TODO(), &whopsdk.ListRefundsRequest{
AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
log.Fatal(err)
}
iter := page.Iterator()
for iter.Next(context.TODO()) {
fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
분쟁
분쟁(차지백)은 구매자의 은행이 결제에 이의를 제기할 때 시작됩니다. 은행이 결정을 내리기 전에 증거로 대응할 수 있는 기간이 주어집니다. Whop이 분쟁을 여러분에게 전달하면, 여러분이 증거를 제출하고, 은행이 판정을 내린 뒤 분쟁이 종료됩니다.수신되는 분쟁 확인
구독해야 할 세 가지 이벤트:| 이벤트 | 의미 |
|---|---|
dispute_alert.created | 정식 분쟁 이전의 분쟁 알림입니다. 일부 프로세서는 사전 알림을 제공합니다. 모든 알림이 분쟁으로 이어지지는 않습니다. |
dispute.created | 정식 분쟁이 시작되었습니다. 대응 기간이 시작됩니다. |
dispute.updated | 상태 변경(예: needs_response에서 under_review로, 이후 won 또는 lost로). |
목록 조회 및 단건 조회
const disputes = await client.disputes.list({
account_id: "biz_xxxxxxxxxxxxx",
});
for await (const item of disputes) {
console.log(item);
}
const dispute = await client.disputes.retrieve({ id: "dspt_xxxxxxxxxxxxx" });
for item in client.disputes.list(account_id="biz_xxxxxxxxxxxxx"):
print(item)
dispute = client.disputes.retrieve("dspt_xxxxxxxxxxxxx")
client.disputes.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
puts item
end
dispute = client.disputes.retrieve(id: "dspt_xxxxxxxxxxxxx")
let disputes = client
.disputes
.list(
&DisputesListQueryRequest {
account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
..Default::default()
},
None,
)
.await?;
for item in disputes.data {
println!("{item:?}");
}
let dispute = client
.disputes
.retrieve(&"dspt_xxxxxxxxxxxxx".to_string(), None)
.await?;
page, err := client.Disputes.List(context.TODO(), &whopsdk.ListDisputesRequest{
AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
log.Fatal(err)
}
iter := page.Iterator()
for iter.Next(context.TODO()) {
fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
dispute, err := client.Disputes.Retrieve(context.TODO(), &whopsdk.RetrieveDisputesRequest{
ID: "dspt_xxxxxxxxxxxxx",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(dispute)
증거로 대응
분쟁 대응은 두 단계로 이루어집니다.disputes.update로 증거를 준비한 다음 disputes.submit으로 제출합니다. update는 멱등적입니다. 제출하기 전까지 필드를 수정할 수 있습니다.
// Stage evidence (call as many times as needed)
await client.disputes.update({
id: "dspt_xxxxxxxxxxxxx",
evidence: {
customer_name: "Jane Doe",
customer_email_address: "jane@example.com",
product_description: "Annual subscription to Acme Pro, purchased 2026-01-15.",
service_date: "2026-01-15",
refund_policy_disclosure: "Customer agreed to no-refunds policy at checkout.",
notes: "Customer used the product 47 times across 8 sessions before disputing.",
},
});
// Submit evidence to the processor. After this, you can no longer edit.
await client.disputes.submit({ id: "dspt_xxxxxxxxxxxxx" });
client.disputes.update(
"dspt_xxxxxxxxxxxxx",
evidence={
"customer_name": "Jane Doe",
"customer_email_address": "jane@example.com",
"product_description": "Annual subscription to Acme Pro, purchased 2026-01-15.",
"service_date": "2026-01-15",
"refund_policy_disclosure": "Customer agreed to no-refunds policy at checkout.",
"notes": "Customer used the product 47 times across 8 sessions before disputing.",
},
)
client.disputes.submit("dspt_xxxxxxxxxxxxx")
# Stage evidence (call as many times as needed)
client.disputes.update(
id: "dspt_xxxxxxxxxxxxx",
evidence: {
customer_name: "Jane Doe",
customer_email_address: "jane@example.com",
product_description: "Annual subscription to Acme Pro, purchased 2026-01-15.",
service_date: "2026-01-15",
refund_policy_disclosure: "Customer agreed to no-refunds policy at checkout.",
notes: "Customer used the product 47 times across 8 sessions before disputing.",
},
)
# Submit evidence to the processor. After this, you can no longer edit.
client.disputes.submit(id: "dspt_xxxxxxxxxxxxx")
// Stage evidence (call as many times as needed)
client
.disputes
.update(
&"dspt_xxxxxxxxxxxxx".to_string(),
&UpdateDisputesRequest {
evidence: Some(DisputesUpdateDisputesRequestEvidence {
customer_name: Some("Jane Doe".to_string()),
customer_email_address: Some("jane@example.com".to_string()),
product_description: Some(
"Annual subscription to Acme Pro, purchased 2026-01-15.".to_string(),
),
service_date: Some("2026-01-15".to_string()),
refund_policy_disclosure: Some(
"Customer agreed to no-refunds policy at checkout.".to_string(),
),
notes: Some(
"Customer used the product 47 times across 8 sessions before disputing.".to_string(),
),
..Default::default()
}),
},
None,
)
.await?;
// Submit evidence to the processor. After this, you can no longer edit.
client
.disputes
.submit(&"dspt_xxxxxxxxxxxxx".to_string(), None)
.await?;
// Stage evidence (call as many times as needed)
_, err := client.Disputes.Update(context.TODO(), &whopsdk.UpdateDisputesRequest{
ID: "dspt_xxxxxxxxxxxxx",
Evidence: &whopsdk.UpdateDisputesRequestEvidence{
CustomerName: whopsdk.String("Jane Doe"),
CustomerEmailAddress: whopsdk.String("jane@example.com"),
ProductDescription: whopsdk.String("Annual subscription to Acme Pro, purchased 2026-01-15."),
ServiceDate: whopsdk.String("2026-01-15"),
RefundPolicyDisclosure: whopsdk.String("Customer agreed to no-refunds policy at checkout."),
Notes: whopsdk.String("Customer used the product 47 times across 8 sessions before disputing."),
},
})
if err != nil {
log.Fatal(err)
}
// Submit evidence to the processor. After this, you can no longer edit.
if _, err := client.Disputes.Submit(context.TODO(), &whopsdk.SubmitDisputesRequest{
ID: "dspt_xxxxxxxxxxxxx",
}); err != nil {
log.Fatal(err)
}
증거 필드
모든 필드는 선택 사항이지만, 더 많이 제공할수록 대응이 강력해집니다. 자주 사용하는 필드:| 필드 | 입력할 내용 |
|---|---|
customer_name / customer_email_address | 보유하고 있는 고객 식별 정보 |
product_description | 고객이 구매한 항목을 쉬운 말로 설명 |
service_date | 서비스를 제공한 날짜(국제표준화기구(ISO) 8601) |
billing_address | 결제 시 사용된 주소 |
customer_communication_attachment | 고객이 참여했음을 보여주는 이메일 또는 채팅 스레드 |
cancellation_policy_attachment / cancellation_policy_disclosure | 취소 정책 및 고객이 이에 동의했다는 증거 |
refund_policy_attachment / refund_policy_disclosure | 환불에 대해 동일 |
refund_refusal_explanation | 환불하지 않은 이유(예: 반품 기간 이후의 사용) |
access_activity_log | 고객이 상품을 사용했음을 증명하는 로그인 또는 사용 로그 |
uncategorized_attachment | 그 밖의 관련 자료 |
{ id: file.id } 형식으로 받습니다. 먼저 Files API를 통해 업로드하세요.
분쟁 상태
분쟁은 상태 머신을 따라 진행됩니다. 두 단계가 있습니다: 조기 경고 단계(warning_ 접두사가 붙은 상태로, dispute_alert.created를 통해 표시됨)와 정식 분쟁 단계입니다. SDK가 반환할 수 있는 모든 상태:
| 상태 | 단계 | 의미 |
|---|---|---|
warning_needs_response | 알림 | 분쟁 알림이 열려 있습니다. 확대되기 전에 환불이나 대응으로 선제 조치할 수 있습니다. |
warning_under_review | 알림 | 알림에 대응했으며, 프로세서가 확대 여부를 결정하는 중입니다. |
warning_closed | 알림 | 정식 분쟁으로 이어지지 않고 알림이 해결되었습니다. |
needs_response | 분쟁 | 정식 분쟁이 열려 있습니다. 대응 기간이 끝나기 전에 증거를 제출하세요. |
under_review | 분쟁 | 증거를 제출했으며, 프로세서가 결정하는 중입니다. |
won | 분쟁 | 자금이 여러분에게 남습니다. |
lost | 분쟁 | 자금이 구매자에게 반환됩니다. Whop이 원래 결제를 취소합니다. |
prevented | 분쟁 | 판정 전에 고객에게 환불되었습니다. lost와 동일하게 정산됩니다. |
분쟁에서 패소하면 Whop은 Refund 레코드를 자동으로 생성하지 않으며, 직접 생성할 수도 없습니다.
payments.refund는 분쟁 중인 결제에 대한 호출을 This payment has been disputed. Therefore, it cannot be refunded. 메시지와 함께 거부합니다. 패소한 분쟁을 기준 정보로 추적하고, refund.created 이벤트를 기대하지 마세요.권한
| 작업 | 필요한 권한 |
|---|---|
| 환불 생성 | payment:manage |
| 환불 조회 / 목록 조회 | payment:basic:read |
| 분쟁 조회 / 목록 조회 | payment:dispute:read |
| 증거 업데이트 또는 제출 | payment:dispute |
다음 단계
결제 받기
나중에 환불하거나 방어하게 될 결제를 생성하는 흐름입니다.
웹훅 수신
서버 측에서 환불 및 분쟁 이벤트에 대응하세요.
파일 업로드
분쟁 대응을 위한 증거 첨부 파일을 업로드하세요.
Disputes API 레퍼런스
전체 리소스: 필드, 상태 및 모든 엔드포인트.

