Xsolla-logoXsolla Developers
또는
관리자 페이지로

결제Webhook POST

사용자가 결제를 완료하면 엑솔라는 payment 유형이 포함된 웹훅의 결제 세부 정보를 웹훅 URL로 전송합니다.

예상되는 응답 코드는 Responses 섹션에 설명되어 있지만 다른 응답 코드도 사용할 수 있습니다.

응답 코드 설명
200, 201, 204 성공적인 응답입니다.
4xx 오류가 발생했습니다. 예를 들어, 지정된 사용자를 찾을 수 없거나 잘못된 서명이 전달된 경우입니다.
5xx 일시적인 서버 오류입니다. 이 응답이 수신되면 엑솔라는 자동으로 웹훅 전송을 재시도하며, 수신자가 수신을 확인할 때까지 시도 간격을 점차 늘립니다. 최대 재시도 횟수는 12시간 동안 12회입니다.

관리자 페이지에 웹훅 URL을 저장하면 웹훅에서 자세한 정보를 수신할 수 있는 권한을 부여할 수 있습니다. 이렇게 하려면 프로젝트 설정 >웹훅> 고급 설정 섹션의 관리자 페이지에서 필요한 토글을 활성화로 설정하십시오.

참고

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

토글 설명
저장된 결제 계정에 대한 정보 표시 저장된 결제 방식에 대한 정보는 payment_account 사용자 정의 개체에서 전달됩니다.
저장된 결제 방식을 사용한 트랜잭션에 대한 정보 표시

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

  • saved_payment_method:
    • 0 - 저장된 결제 방식이 사용되지 않음
    • 1 - 현재 결제를 진행할 때 결제 방식이 저장됨
    • 2 - 이전에 저장한 결제 방식이 사용됨
  • payment_type:
    • 1 - 일회성 결제
    • 2 - 반복 결제
주문 개체를 웹훅에 추가 주문 관련 정보는 결제 웹훅의 order 개체에서 전달됩니다.
민감한 데이터 없이 필수 사용자 매개 변수만 전송

사용자에 대한 다음 정보만 웹훅에서 전달됩니다.

  • ID
  • 국가
카드 BIN 및 접미사 표시

은행 카드 번호에 대한 다음 정보가 웹훅에서 전달됩니다.

  • card_bin 매개 변수의 처음 6자리
  • card_suffix의 마지막 4자리
카드 브랜드 표시 결제에 사용된 카드의 브랜드. 예: Mastercard 또는 Visa.

참고

웹훅으로 전송되는 필드 세트는

  • 관리자 페이지에서 구성한 고급 설정
  • 엑솔라 측에 구성한 사용자 지정 설정

에 따라 달라집니다. 질문이 있는 경우, 고객 성공 관리자에게 문의하거나 csm@xsolla.com으로 이메일을 보내십시오.

Request
Request Body schema: application/json
notification_type
required
string

알림 유형.

required
object

트랜잭션 데이터 관련 값.

agreement
integer

계약 ID.

dry_run
integer

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

external_id
string

거래 외부 ID. 자세한 내용은 FAQs를 참조해 주세요.

id
integer

트랜잭션 ID.

payment_date
string

결제 날짜.

payment_method
integer

결제 수단 ID.

payment_method_name
string

결제 방식 이름.

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자리 통화 코드입니다.

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

제휴 네트워크 및 인플루언서를 통한 구매에 대해 공제된 사용자 확보 수수료의 총액(대상)입니다.

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

쿠폰 데이터 관련 값(이 트랜잭션에 쿠폰이 사용된 경우).

campaign_code
string

쿠폰 캠페인 코드.

coupon_code
string

쿠폰 코드.

object

기프트 내역 관련 값.

giver_id
string

제공자 ID.

hide_giver_from_receiver
string

수신자에서 제공자 ID를 숨길지 여부.

message
string

제공자로부터 전송된 메시지.

receiver_email
string

기프트 수령인 이메일.

receiver_id
string

기프트 수령인 ID.

object

주문에 대한 정보가 포함된 개체입니다. 이 정보를 받으려면 프로젝트 설정 > 웹훅 > 고급 설정 섹션의 관리자 페이지에서 웹훅에 주문 개체 추가 토글을 온으로 설정해 주세요.

id
integer

주문 ID.

object

아이템에 대한 정보가 포함된 개체.

object

아이템 가격에 대한 정보가 포함된 개체.

amount
number <float>

선택한 통화로 표시된 아이템의 총 가격.

currency
string

아이템 가격의 통화.

quantity
integer

아이템 수량.

sku
string

아이템 SKU.

Array of objects

이 트랜잭션에 적용된 프로모션.

Array
id
integer

프로모션 ID.

technical_name
string

프로모션의 기술명.

object

정기결제 내역 관련 값.

amount
number <float>

구매 금액입니다.

currency
string

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

date_create
string

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

date_next_charge
string

다음 충전 날짜. ISO 8601에 따른 날짜 및 시간.

plan_id
string

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

product_id
string

상품 ID(액세스 토큰으로 보낸 경우).

subscription_id
integer

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

tags
Array of strings

플랜 태그.

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

제공된 정보에 오류가 있는 경우 반환됩니다(예: 필수 매개변수 누락, 인증 실패 등). 이 경우 사용자의 돈은 인출되지만 구매는 실패합니다. 환불을 진행하려면 support@xsolla.com으로 엑솔라 고객 지원에 문의해 주세요.

500

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

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type": "payment",
    "settings": {
      "project_id": 18404,
      "merchant_id": 2340
    },
    "purchase": {
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": 853
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        },
        "order": {
          "id": 1234
          "lineitems": [
          {
            "sku": "com.xsolla.item_1",
            "quantity": 1,
            "price": {
              "currency": "EUR",
              "amount": 6.5
              }
          }
          ]
          }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_name": "PayPal",
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0,
            "percent": 20
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "payout_currency_rate": "1",
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "country_wht": {
            "currency": "USD",
            "amount": 2,
            "percent": 10
        },
        "user_acquisition_fee": {
            "currency": "USD",
            "amount": 2,
            "percent": 1
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": 10
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}'
Response samples
application/json
{
  • "error": {
    }
}
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.