Xsolla-logo
  • 문서화
  • 계정 생성

Successful payment for order (with payment and transaction details)Webhook POST

엑솔라는 사용자가 주문에 대한 결제를 성공적으로 완료하면 지정된 URL로 order_paid 웹훅을 전송합니다.

order_paid 웹훅에는 구매한 아이템, 결제 데이터 및 거래 세부 정보에 대한 정보가 포함되어 있습니다.

결제가 성공하지 못한 경우 order_paid 웹훅이 전송되지 않습니다. 예:

  • 결제 양식이 열렸지만 사용자가 주문을 결제하지 않았습니다.
  • 결제창이 열렸으나 결제 중 오류가 발생했습니다.

order_paid 웹훅의 처리 시간은 3초 이내로 하는 것이 좋습니다.

응답 섹션에서 예상 답변을 볼 수 있습니다. 다른 응답 코드를 사용할 수도 있습니다. 응답 코드 및 자동 결제 환불 기능 연결에 따른 엑솔라 측의 웹훅 처리 로직은 다음과 같습니다.

응답 코드 자동 결제 환불이 비활성화됨(기본값) 자동 결제 환불이 비활성화됨
400, 401, 402, 403, 404, 409, 422, 415 작업 없음 사용자에게 자동 환불
200, 201, 204 작업 없음 작업 없음
웹훅에 다른 코드 또는 응답 없음 5분 간격으로 2번, 15분 간격으로 7번, 60분 간격으로 10번 등 지정한 시간 간격으로 웹훅을 여러 번 전송합니다. 5분 간격으로 2번, 15분 간격으로 7번, 60분 간격으로 10번 등 지정한 시간 간격으로 웹훅을 여러 번 전송합니다. 모든 웹훅을 전송해도 응답을 성공적으로 받지 못하면 사용자에게 환불이 자동으로 이루어집니다.

자동 환불 기능을 연결하려면 고객 성공 관리자에게 문의하거나 csm@xsolla.com으로 이메일 전송하십시오.

Request
Request Body schema: application/json
notification_type
required
string

알림 유형.

required
Array of version = 1 (object) or version = 2 (object)

사용자가 구매한 아이템 목록입니다.

The set of parameters included in the array depends on the webhook version. Version 2 includes additional parameters: is_free, is_bonus, and is_bundle_content. To switch the version, pass its number in the version parameter in the Update information about webhook settings API call.

Array
One of:
sku
required
string

아이템의 고유 ID입니다. game_key 유형의 아이템은 sku_drm 형식의 값을 사용합니다.

type
required
string

아이템 유형. 가능한 값: virtual_good, virtual_currency, game_key, bundle. 인게임 재화 패키지 등 bundle 유형의 아이템의 경우 아이템 배열에 다음이 표시됩니다.

  • 번들 또는 인게임 재화 패키지의 매개변수
  • 번들에 포함된 아이템 또는 패키지에 포함된 통화
Enum: "virtual_good" "virtual_currency" "game_key" "bundle"
quantity
required
integer

아이템 수량.

amount
required
string

아이템 수량에 따른 총 비용입니다.

required
Array of objects

적용된 프로모션. 프로모션이 적용되지 않은 경우, 매개변수에 빈 배열이 전달됩니다.

Array
amount_with_discount
string

할인이 적용된 아이템의 총 비용.

amount_without_discount
string

할인이 미적용된 아이템의 총 비용.

sequence
integer

프로모션 신청 순서입니다.

is_pre_order
required
boolean

true이면 항목이 사전 판매됩니다.

custom_attributes
object

아이템 특성 및 값이 포함된 JSON 개체입니다.

required
object

주문에 대한 정보입니다.

id
required
integer

엑솔라 측에서 사용자 주문의 고유 식별자입니다.

mode
required
string

결제 모드. 실제 결제에는 default를 사용합니다. 테스트 결제에는 sandbox를 사용합니다.

Enum: "default" "sandbox"
currency_type
required
string

결제 통화 유형. 무료 주문의 경우 unknown 값이 지정됩니다.

Enum: Description
real

실질 화폐

unknown

무료 주문

virtual

인게임 재화

currency
required
string

주문 통화. 가상 화폐는 SKU를 사용하고 실제 화폐는 3글자 ISO 4217 코드를 사용합니다.

amount
required
string

선택한 통화를 기준으로 한 장바구니의 총 비용입니다.

status
required
string

주문 상태.

platform
required
string or null

결제 플랫폼. xsolla 값은 엑솔라를 통한 결제에 사용됩니다. 기타 결제는 게임 퍼블리싱 플랫폼의 이름에 해당하는 값을 사용합니다.

Enum: "xsolla" "playstation_network" "xbox_live" "pc_standalone" "nintendo_shop" "google_play" "app_store_ios" "android_standalone" "ios_standalone" "android_other" "ios_other" "pc_other"
comment
required
string or null

주문에 대한 사용자의 코멘트.

invoice_id
required
string or null

실질 화폐 결제 인보이스 ID. 인게임 재화 결제 또는 무료 아이템은 null 값을 사용합니다.

required
Array of objects

적용된 프로모션. 프로모션이 적용되지 않은 경우, 매개변수에 빈 배열이 전달됩니다.

Array
amount_with_discount
string

할인이 적용된 아이템의 총 비용.

amount_without_discount
string

할인이 미적용된 아이템의 총 비용.

sequence
integer

프로모션 신청 순서입니다.

Array of objects

적용된 쿠폰. 쿠폰을 적용되지 않았으면 배열이 돌아오지 않습니다.

Array
code
string

적용된 쿠폰 코드.

external_id
string

외부 ID.

Array of objects

적용된 프로모션 코드. 프로모션 코드가 적용되지 않았으면 배열이 돌아오지 않습니다.

Array
code
string

적용된 프로모션 코드의 코드.

external_id
string

외부 ID.

required
object

사용자 정보.

external_id
required
string

사용자 ID.

email
required
string

사용자 이메일 주소.

object

거래 및 결제 세부 정보.

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

object

구매 데이터 관련 값.

required
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.

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. 이 매개 변수는 관리자 페이지의 프로젝트 이름 옆에서 확인할 수 있습니다.

custom_parameters
object

추가 정보입니다.

Responses
200

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

400

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

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "order_paid",
    "items": [
      {
        "sku": "com.xsolla.item_1",
        "type": "virtual_good",
        "is_pre_order": false,
        "quantity": 3,
        "amount": "1000",
        "promotions": [
          {
            "amount_without_discount": "6000",
            "amount_with_discount": "5000",
            "sequence": 1
          },
          {
            "amount_without_discount": "5000",
            "amount_with_discount": "4000",
            "sequence": 2
          }
        ],
        "custom_attributes":
          {
            "purchased": 0,
            "attr": "value"
          }
      },
      {
        "sku": "com.xsolla.item_new_1",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "1000",
        "promotions": []
      },
      {
        "sku": "com.xsolla.gold_1",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 1500,
        "amount": "[null]",
        "promotions": []
      }
    ],
    "order": {
      "id": 1,
      "mode": "default",
      "currency_type": "virtual",
      "currency": "sku_currency",
      "amount": "2000",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": "1",
      "promotions": [
        {
          "amount_without_discount": "4000",
          "amount_with_discount": "2000",
          "sequence": 1
        }
      ],
      "promocodes": [
        {
          "code": "promocode_some_code",
          "external_id": "promocode_sku"
        }
      ],
      "coupons": [
        {
          "code": "WINTER2021",
          "external_id": "coupon_sku"
        }
      ]
    },
    "user": {
      "external_id": "id_xsolla_login_1",
      "email": "gc_user@xsolla.com"
    },
    "billing": {
      "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
          },
          "total": {
              "currency": "USD",
              "amount": 200
          },
          "promotions": [{
              "technical_name": "Demo Promotion",
              "id": 853
          }],
          "coupon": {
              "coupon_code": "ICvj45S4FUOyy",
              "campaign_code": "1507"
          },
      "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"
          }
      }
   }
}'
System statusAll services operational

Privacy Settings

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