Xsolla-logo
또는
관리자 페이지로

환불Webhook POST

결제가 취소되면 엑솔라는 취소된 거래 내역을 refund 유형의 웹훅으로 웹훅 URL로 전송합니다.

웹훅 재시도 메커니즘은 환불을 시작한 사람에 따라 달라집니다:

  • 환불이 귀하 측에서 요청된 경우 웹훅은 재전송되지 않습니다. 웹훅에 대한 응답 여부와 관계없이 결제 금액은 사용자에게 환불됩니다.
  • 제3자(예: 결제 시스템 또는 엑솔라 고객 지원팀)가 환불을 요청했고 웹훅에 대한 응답으로 5xx 상태 코드가 반환된 경우, 웹훅은 점점 더 빠른 간격으로 재전송됩니다. 재시도 횟수는 첫 번째 시도 후 48시간 이내에 최대 12회입니다.

환불 절차에 대한 자세한 내용은 지침을 참조하세요.

주의

다음 조건을 모두 충족하는 경우에도 사용자에게 결제가 환불됩니다:

  • 환불이 엑솔라 측에서 요청한 경우.
  • 웹훅에 대한 응답으로, 4xx 상태 코드가 반환되거나 모든 재시도 후 응답을 받지 않거나 5xx 상태 코드가 반환된 경우.

관리자 페이지에서 웹훅 URL을 저장할 때 웹훅을 통해 추가 정보를 수신하도록 설정할 수도 있습니다.

참고

2025년 1월 22일 또는 그 이전에 관리자 페이지에 등록한 경우, 설정 >웹훅 > 테스트 > 결제 > 고급 설정 섹션에서 토글을 찾을 수 있습니다.

토글 설명
저장된 결제 방식을 사용한 트랜잭션에 대한 정보 표시

정보는 웹훅의 다음 사용자 정의 매개 변수에서 전달됩니다.

  • saved_payment_method:
    • 0 - 저장된 결제 방식이 사용되지 않음
    • 1 - 현재 결제를 진행할 때 결제 방식이 저장됨
    • 2 - 이전에 저장한 결제 방식이 사용됨
  • payment_type:
    • 1 - 일회성 결제
    • 2 - 반복 결제

환불 코드:

코드 환불 이유 설명
1 사용자 요청/게임 요청에 의한 취소 관리자 페이지에서 취소가 요청된 경우 사용됩니다.
2 지불 거절 거래 지불 거절 요청되었습니다.
3 연동 오류 엑솔라와 게임 사이의 연동에 문제가 있을 경우 사용됩니다.
권장 사항: 사용자를 차단 목록에 추가하지 마세요.
4 잠재적 사기 부정 결제가 의심됩니다.
권장사항: 사용자를 차단 목록에 추가하세요.
5 테스트 결제 테스트 트랜잭션인 경우 사용되며 이후 취소로 이어집니다.
권장 사항: 사용자를 차단 목록에 추가하지 마세요.
6 사용자 인보이스 만료 후불 결제 방식에 의해 트랜잭션이 이뤄진 경우 사용됩니다.
7 PS에서 전송된 사기 참고 결제 시스템에서 결제가 거부되었습니다. PS에서 잠재적 사기를 감지했습니다.
권장 사항: 사용자를 차단 목록에 추가하세요.
8 PS 요청에 의한 취소 결제시스템이 취소를 요청한 경우 사용됩니다.
권장사항: 사용자를 차단 목록에 추가하지 마세요.
9 사용자 요청에 의한 취소 사용자의 요청에 의한 환불 사유입니다. 어떤 이유로 사용자가 게임 또는 구매에 만족하지 못한 못하였음을 의미합니다.
권장 사항: 사용자를 차단 목록에 추가하지 마세요.
10 게임 요청에 의한 취소 게임을 통해 취소를 요청한 경우 사용됩니다.
권장 사항: 사용자를 차단 목록에 추가하지 마세요.
11 계정 소유자가 사기 신고를 위해 전화한 경우 계정 소유자가 본인 미사용 결제로 신고한 경우입니다.
12 지불 거절 사기 우호적인 부정결제에 대한 메시지를 수신했을 때 사용됩니다.
13 복제 동일 인보이스에 대하여 거래 복제.
Request
Request Body schema: application/json
notification_type
required
string

알림 유형.

required
object

트랜잭션 데이터 관련 값입니다.

agreement
integer

계약 ID입니다.

dry_run
integer

테스트 트랜잭션(거래). 테스트 트랜잭션의 경우 매개변수는 1개 값을 갖습니다. 또는, 트랜잭션(거래)이 실제로 이루어지는 경우 매개변수가 전송되지 않습니다.

external_id
string

트랜잭션 외부 ID 입니다.

id
integer

트랜잭션 ID.

payment_method_order_id
string

결제 시스템의 결제 ID.

required
object

결제 내역 관련 값입니다.

object

직접 원천징수세.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

percent
number <float>

직접 원천징수세율

object

게임유저 결제 데이터 관련 값입니다.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object

결제 방식 수수료율입니다.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object

결제 방법에서 청구된 금액에 대한 데이터가 포함된 값입니다.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object

지급 내역 관련 값입니다.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

payout_currency_rate
string

결제 통화를 지급 통화로 환전할 때의 환율입니다.

object

본국 송금 비용에 대한 데이터가 있는 오브젝트. 타사가 엑솔라에 부과.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object

판매세(대상; 미국과 캐나다만).

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

percent
number <float>

판매세율.

object

VAT 세율입니다(유럽연합만 해당).

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

percent
number <float>

부가가치세율.

object

엑솔라 잔액에서 청구된 금액에 대한 데이터가 포함된 값입니다.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object

엑솔라 수수료 요율입니다.

amount
number <float>

총계.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

custom_parameters
object

사용자 정의 매개 변수입니다.

object

구매 데이터 관련 값입니다.

required
object

구매 총 가격 데이터와 관련된 값입니다.

amount
number <float>

총 구매 금액입니다.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object

결제 파라미터 데이터와 관련된 값입니다.

amount
number <float>

구매 금액입니다.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object
Deprecated

게임 키에 대한 데이터가 포함된 배열입니다.

object

업그레이드 데이터가 있는 객체입니다.

amount
number <float>
Deprecated

구매 금액입니다.

currency
string
Deprecated

통화. ISO 4217에 따른 3자리 통화 코드입니다.

object
Deprecated

사용자가 업그레이드 한 패키지의 데이터가 있는 객체입니다.

DRM
string
Deprecated

게임 DRM플랫폼.

digital_content
string
Deprecated

판매자 계정으로 설정된 게임의 SKU입니다.

object
Deprecated

사용자가 업그레이드를 적용한 패키지의 데이터가 있는 객체입니다.

DRM
string
Deprecated

게임 DRM플랫폼.

digital_content
string
Deprecated

판매자 계정으로 설정된 게임의 SKU입니다.

object

정기결제 세부 정보(오브젝트).

amount
number <float>

구매 금액입니다.

currency
string

통화. ISO 4217에 따른 3자리 통화 코드입니다.

date_create
string

정기결제 생성 날짜입니다. ISO 8601에 따른 날짜 및 시간입니다.

plan_id
string

요금제 ID(API를 통해 생성된 경우, 외부 ID).

subscription_id
integer

엑솔라 시스템 내의 정기결제 ID입니다.

tags
Array of strings

플랜 태그.

object
Deprecated

구매 게임머니 데이터와 관련된 값입니다.

amount
number <float>
Deprecated

구매 금액입니다.

currency
string
Deprecated

통화. ISO 4217에 따른 3자리 통화 코드입니다.

name
string
Deprecated

게임머니 이름.

quantity
number <float>
Deprecated

가상 항목의 수량입니다.

object
Deprecated

게임 아이템 구매 데이터와 관련된 값입니다.

amount
number <float>
Deprecated

구매 금액입니다.

currency
string
Deprecated

통화. ISO 4217에 따른 3자리 통화 코드입니다.

Array of objects
Deprecated
Array
amount
number <float>
Deprecated

아이템 수량입니다.

sku
string
Deprecated

아이템 ID입니다.

object

환불 세부 정보(오브젝트).

author
string

환불 시작자. 필드 값이 다음 표에 따라 전달됩니다.

환불 시작자 필드 값
게임(API를 통해). API
게시자 계정 사용자(자동 환불). 사용자 이메일
게시자 계정 사용자(엑솔라 고객 지원의 도움을 받아). support@xsolla.com
엑솔라(엑솔라 고객 지원의 도움을 받아). support@xsolla.com
code
integer

코드 ID.

reason
string

환불 이유입니다.

object

사용자 정의 프로젝트 설정(개체)입니다.

merchant_id
integer

판매자 ID입니다.

project_id
integer

프로젝트 ID. 이 매개 변수는 관리자 페이지의 프로젝트 이름 옆에서 확인할 수 있습니다.

object

사용자 세부 사항(개체)입니다.

id
required
string

사용자 ID.

country
string

사용자의 국가. ISO 3166-1 alpha-2 standard에 따른 2자로 된 국가 코드를 사용합니다.

email
string

사용자 이메일.

ip
string

유저 IP 주소입니다.

name
string

사용자 이름.

phone
string

유저 전화 번호입니다(국제 형식).

zip
string

우편번호.

Responses
204

성공적인 처리 표시를 반환합니다.

400

제공된 정보에 오류가 있는 경우 반환합니다(예: 필수 매개변수 누락, 인증 실패 등).

500

서버에 일시적인 오류가 있음을 표시하려면 돌아가세요.

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "refund",
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "purchase": {
            "virtual_currency": {
                "name": "Coins",
                "quantity": 10,
                "currency": "USD",
                "amount": 100
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "virtual_items": {
                "items": [
                    {
                        "sku": "com.xsolla.item1",
                        "amount": 1
                    }
                ],
                "currency": "USD",
                "amount": 50
            },
            "total":{
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1
        },
        "refund_details": {
            "code": 4,
            "reason": "Potential fraud"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": 10
            }
        }
    }
}'
Response samples
application/json
{
  • "error": {
    }
}

Privacy Settings

Privacy PolicyEnd User License Agreement
System statusAll services operational
© 2006–2025 Xsolla Inc.