주요 콘텐츠로 건너뛰기

주문 생성 웹훅

Aghanim의 주문 생성 webhook은 새 주문이 생성되면 게임에 알림을 보냅니다. 플레이어가 구매 버튼을 클릭하고 결제 페이지를 열면 활성화됩니다.

이 웹훅은 주문 생성 이벤트를 통해 활성화되며, 이것은 게임 → 웹훅에서 선택할 수 있습니다.

요구 사항

Aghanim의 주문 생성 웹훅을 사용하려면 웹훅 서버를 다음과 같이 구성해야 합니다:

  • POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
  • Aghanim이 생성하고 서명한 이벤트를 수신합니다.
  • 웹훅 페이로드에 포함된 idempotency_key를 처리하여 중복 웹훅 처리를 방지합니다.
  • 구매한 품목이 성공적으로 적립된 경우 2xx 상태 코드를 응답하고, 거부 또는 오류에 대해서는 4xx 또는 5xx를 응답합니다.

구성

  1. order.created 웹훅 처리를 위한 함수를 개발합니다.
  2. 엔드포인트를 사용 가능하게 설정하세요.
  3. Aghanim 계정에서 엔드포인트를 등록합니다 → 게임 → 웹훅 → 새 웹훅에서 주문 생성 이벤트 유형을 선택합니다.

대안으로, 웹후크 생성 API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

트리거 값

값설명
hub.purchase플레이어가 게임 허브에서 구매를 시작할 때.
testDashboard에서 "Send test event"를 사용할 때.

order.created이 다른 이벤트 유형과 어떻게 관련되는지에 대해서는 전체 이벤트 및 트리거 매트릭스를 참조하세요.

요청 스키마

아래는 예시입니다 order.created 웹훅 요청:

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "order.created",
  "event_data": {
    "amount": 9499,
    "company_id": "com_exTAxmkZQCO",
    "country": "US",
    "created_at": 1725547595,
    "currency": "USD",
    "game_id": "gm_exTAyxPsVwh",
    "id": "ord_eCacpFwavzi",
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "크리스탈",
        "description": "이 거대한 크리스탈 보물로 적들을 제압하세요.",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null
      }
    ],
    "modified_at": 1725547657,
    "player_id": "2D2R-OP3C",
    "receipt_number": "2409051289614565",
    "status": "created",
    "user_id": "usr_eymySUreClx",
    "metadata": null,
    "creator": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.purchase",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트의 유형, order.created 이럴 경우.
event_timenumber유닉스 에포크 시간으로 된 이벤트 날짜.
event_dataEventData이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|null이벤트가 전송된 원인이 된 트리거입니다.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextEventContext|null이벤트에 대한 컨텍스트 정보.

EventContext 스키마

Key유형설명
orderOrderContext|null해당되는 경우 이벤트와 관련된 주문 정보입니다.
playerPlayerContext|null플레이어 정보를 추가하려면 웹훅 설정에서 "플레이어 컨텍스트 추가"를 활성화하세요.
주문 통화 vs. 결제 통화

주문에는 두 쌍의 통화/금액이 있으며, 서로 다를 수 있습니다:

  • currency + amount — 결제 시 사용자가 본 내용(주문 통화와 그 금액).
  • payment_currency + payment_amount — 결제 제공업체가 실제로 청구한 내용.

특정 거래에서 주문 통화가 지원되지 않으면 둘이 달라집니다. 이 경우 금액은 해당 국가에서 결제 수단이 기본으로 사용하는 통화로 환산됩니다. 예를 들어, 세르비아의 플레이어는 결제 시 RSD로 표시된 가격을 보지만 이 거래에서는 RSD가 지원되지 않아 결제가 EUR로 환산되어 청구됩니다. 그 결과 currency = RSD이고 amount은 RSD 기준이며, payment_currency = EUR이고 payment_amount은 EUR 기준입니다.

처리해야 할 두 가지 경우:

  • 가상 화폐 주문: payment_currency는 법정 통화 ISO 4217 코드가 아니라 센티넬 값 VC입니다.
  • 레거시 주문 이 필드가 존재하기 전에 생성된 주문은 payment_currency가 null로 설정됩니다. 일반적으로 이 필드는 선택 사항으로 취급하세요. 이는 하위 호환되는 추가 항목이며 null이거나 없을 수 있습니다.

EventData 스키마

Key유형설명
idstringAghanim에 의해 생성된 주문 ID.
company_idstringAghanim 시스템에서의 귀하의 회사 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
user_idstringAghanim 시스템에서 게임 허브 유저 ID.
player_idstring고유한 플레이어 인증에 선택된 플레이어 ID.
statusstring주문 상태. 가능한 상태: created,captured,paid,canceled,refunded,refund_requested.
amountnumber주문 금액 currency, 단위: 소수 통화 단위.
currencystring결제 시 사용자에게 표시되는 주문 통화(ISO 4217).
payment_amountnumber|null청구된 최종 금액. 통화 단위: payment_currency, 세금 포함, 주요 통화 단위.
payment_currencystring|null결제 제공업체가 청구한 최종 금액의 통화(ISO 4217). 다음과 다를 수 있습니다: currency.
countrystring결제 수단 국가.
created_atnumber유닉스 에포크 시간으로 된 주문 생성 날짜.
modified_atnumber유닉스 에포크 시간으로 된 주문 수정 날짜.
itemsItem[]구매한 아이템 세부사항 포함.
feesFees세금 및 수수료에 대한 정보.
revenue_usdnumber예상 순수익은 예상 외환 환율 및 결제 수단 수수료를 사용하여 USD 센트로 변환됩니다. 최종 수치는 결제 제공업체와의 조정 후 다음 달 10일까지 결정됩니다.
metadataobject|null주문에 대한 추가 정보를 저장하기 위한 키-값 쌍으로 구성된 메타데이터 객체입니다.
creatorCreator|null주문과 연관된 크리에이터에 대한 정보입니다.

아이템 스키마

KeyType설명
idstringAghanim에 의해 생성된 아이템 ID.
namestring아이템 이름.
descriptionstring|null아이템 설명.
skustring게임과 Aghanim 측 모두에서 일치하는 아이템 SKU.
quantitynumber아이템 수량.
pricenumber아이템 가격 소수 통화 단위.
price_decimalnumber소수점 단위로 표시된 아이템 가격입니다.
currencystring항목 가격 통화.
typestring항목 유형. 가능한 값: item, bundle.
nested_itemsNestedItem[]|null번들에 포함된 항목 배열.
fallback_itemItem|null주 아이템을 플레이어에게 제공할 수 없을 경우 백업으로 제공할 수 있는 아이템입니다.
sourcestring아이템이 전달되는 이유를 식별합니다. 가능한 값: order, bonus, bundle, coupon, lootbox, free_item, liveops, daily_reward, loyalty_reward, progression_program, rolling_offer, pick_one_offer.
metadataobject|null귀하 측의 추가 로직을 지원하기 위한 아이템의 사용자 지정 키-값 쌍입니다.

항목 유형 bundle 내부에 여러 중첩된 항목을 포함할 수 있습니다.
번들의 공통 SKU를 처리하거나 각 중첩 항목을 개별적으로 처리할 수 있습니다.

NestedItem 스키마

Key유형설명
idstringAghanim에 의해 생성된 아이템 ID.
namestring아이템 이름.
descriptionstring|null아이템 설명.
skustring게임과 Aghanim 측 모두에서 일치하는 아이템 SKU.
quantitynumber아이템 수량.
fallback_itemItem|null주 아이템을 플레이어에게 제공할 수 없을 경우 백업으로 제공할 수 있는 아이템입니다.
metadataobject|null귀하 측의 추가 로직을 지원하기 위한 아이템의 사용자 지정 키-값 쌍입니다.

PlayerContext 스키마

Key유형설명
player_idstring|null고유한 플레이어 인증에 선택된 플레이어 ID.
playerobject|null복합 인증 사용 시 플레이어 ID 구성 요소.
attributesAttributesAghanim이 기대하는 기본 플레이어 속성.
custom_attributesCustomAttributes사용자 정의 플레이어 속성.

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]

On this page