Skip to main content
Payout webhook은 자체 자금이 Dodo Payments에서 은행 계좌로 이동할 때 이를 알려줍니다. List Payouts endpoint를 polling하지 않고 회계 시스템에서 지급을 조정하려면 이를 사용하세요.

지급 Webhook 이벤트

지급은 lifecycle의 각 단계에서 이벤트를 발생시킵니다. 각 단계는 dashboard에 표시되는 지급 상태와 일치합니다.
payout.created은 이전에 payout.not_initiated로 발생했습니다. 기존 endpoint가 payout.not_initiated를 기준으로 필터링하는 경우, 계속 일치하도록 필터를 payout.created로 업데이트하세요. payload의 status 필드는 이 단계에서도 여전히 not_initiated을 보고합니다.

지급 이벤트 처리

지급은 고객의 자금이 아니라 자체 자금과 관련되므로, 이러한 이벤트는 일반적으로 고객에게 표시되는 flow보다는 장부 기록과 내부 alerting에 사용됩니다.
Handling payout events
처리하기 전에 항상 webhook signature를 확인하세요. 설정 방법은 Webhooks guide를 참조하세요. 위 handler에서는 간결한 설명을 위해 verification을 생략했습니다.
지급 이벤트는 terminal 상태가 아니며 순서가 엄격하게 보장되지도 않습니다. 은행이 transfer를 반환하면 payout.failedpayout.success 이후에 도착할 수 있고, 실패한 지급이 나중에 복구되면 payout.successpayout.failed 이후에 도착할 수 있습니다. 수신한 마지막 이벤트가 최종 상태라고 가정하지 말고 payload의 status 필드를 현재 상태로 처리하세요.

지급 상태

지급 object는 단일 필드를 통해 진행 상태를 보고합니다:
payload의 refunds, chargebackstax은 deprecated되었습니다. 대신 자세한 내역은 payout breakup endpoints를 사용하세요.

관련 문서

Payout Structure

지급이 예약되고 계산되는 방식과 각 지급 상태의 의미를 설명합니다.

Balances & Wallets

wallet 잔액과 각 지급을 뒷받침하는 ledger를 추적합니다.

Webhook Payload 스키마

amount
integer<int64>
필수

The total amount of the payout.

business_id
string
필수

The unique identifier of the business associated with the payout.

chargebacks
integer<int64>
필수
지원 중단

The total value of chargebacks associated with the payout.

created_at
string<date-time>
필수

The timestamp when the payout was created, in UTC.

currency
enum<string>
필수

The currency of the payout, represented as an ISO 4217 currency code.

사용 가능한 옵션:
AED,
ALL,
AMD,
ANG,
AOA,
ARS,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
BMD,
BND,
BOB,
BRL,
BSD,
BWP,
BYN,
BZD,
CAD,
CHF,
CLP,
CNY,
COP,
CRC,
CUP,
CVE,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
ETB,
EUR,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MAD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRU,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
NGN,
NIO,
NOK,
NPR,
NZD,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SEK,
SGD,
SHP,
SLE,
SLL,
SOS,
SRD,
SSP,
STN,
SVC,
SZL,
THB,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
USD,
UYU,
UZS,
VES,
VND,
VUV,
WST,
XAF,
XCD,
XOF,
XPF,
YER,
ZAR,
ZMW
fee
integer<int64>
필수

The fee charged for processing the payout.

payment_method
string
필수

The payment method used for the payout (e.g., bank transfer, card, etc.).

payout_id
string
필수

The unique identifier of the payout.

refunds
integer<int64>
필수
지원 중단

The total value of refunds associated with the payout.

status
enum<string>
필수

The current status of the payout.

사용 가능한 옵션:
not_initiated,
in_progress,
on_hold,
failed,
success
tax
integer<int64>
필수
지원 중단

The tax applied to the payout.

updated_at
string<date-time>
필수

The timestamp when the payout was last updated, in UTC.

name
string | null

The name of the payout recipient or purpose.

payout_document_url
string | null

The URL of the document associated with the payout.

remarks
string | null

Any additional remarks or notes associated with the payout.

마지막 수정일 2026년 8월 6일