주요 콘텐츠로 건너뛰기

결제 이벤트 웹훅

플레이어가 주문 결제를 시도할 때 결제가 생성됩니다. Aghanim의 결제 이벤트 webhook는 주문에 연결된 결제의 상태 변경 사항을 게임에 알리며, 분석 및 추적을 위한 모든 가능한 상태에 대한 자세한 정보를 제공합니다.

이 웹훅은 Game → Webhooks에서 선택할 수 있는 결제 이벤트 이벤트를 통해 활성화됩니다.

단일 주문은 플레이어가 결제를 여러 번 시도하였으나 실패했거나 완료되지 않은 경우 여러 결제와 연결될 수 있습니다.

중복 결제 이벤트 처리

결제 이벤트는 초기 이벤트 후 결제 세부 정보(금액, 수수료, 세금)가 업데이트될 때 동일한 결제 ID에 대해 여러 번 전송될 수 있습니다. 결제 상태가 동일하게 유지되더라도 이러한 업데이트는 수익 추적 및 분석에 영향을 미치기 때문에 발생할 수 있습니다.

결제 이벤트 처리 시:

  • 중복 이벤트를 식별하기 위해 idempotency_key를 사용하세요.
  • 중복 이벤트를 무시하거나 최신 결제 정보로 기록을 업데이트하세요.
  • 중복 이벤트로 인한 오류를 발생시키지 마십시오. 이는 재시도 일정에 따라 웹훅 재시도를 유발할 수 있습니다.
  • 동일 주문에 대한 여러 결제 시도는 다른 결제 ID(id 필드)를 가지며, 중복 이벤트가 아닙니다.

결제 상태

다음 결제 상태에 대해 결제 웹훅이 생성될 수 있습니다:

  • succeeded – 결제가 성공적으로 완료되었으며 사용자의 계좌에서 자금이 차감되었습니다
  • canceled – 사용자가 결제 과정에서 결제를 취소했습니다
  • chargeback – 결제 요청이 차지백 요청으로 인해 취소되었습니다
  • declined – 사용자의 결제 수단이 거부되어 결제를 완료할 수 없었습니다
  • dispute – 사용자가 이 결제에 대해 결제 수단과 분쟁을 제기했습니다
  • expired – 결제가 기한 내에 완료되지 않아 만료되었습니다
  • pending – 사용자가 결제를 시작했고 완료를 기다리고 있습니다
  • refunded – 결제가 환불되었고 자금이 사용자에게 반환되었습니다
  • rejected – 결제가 잠재적 사기로 표시되어 처리되지 않았습니다
  • voided – 자금이 이체되기 전에 결제가 무효화되었습니다

요구 사항

Aghanim의 결제 이벤트 웹훅을 사용하려면 웹훅 서버를 다음과 같이 구성해야 합니다:

  • POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
  • Aghanim에서 생성되고 서명된 이벤트를 수신합니다.
  • 웹훅 페이로드에 포함된 idempotency_key를 처리하여 중복 웹훅 처리를 방지합니다.
  • 결제 이벤트가 성공적으로 처리되면 2xx 상태 코드로 응답하고, 거부 또는 오류가 발생하면 4xx 또는 5xx로 응답합니다.

구성

  1. payment.* 웹훅 처리를 위한 함수를 개발합니다.
  2. 엔드포인트를 사용 가능하게 설정하세요.
  3. 게임 → 웹훅 → 새 웹훅에서 결제 이벤트 유형을 선택하여 Aghanim 계정 내에 엔드포인트를 등록하십시오.

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

요청 스키마

아래는 예시입니다 payment.succeeded 웹훅 요청:

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": "payment.succeeded",
  "event_data": {
    "id": "pmt_eFgYpxryeKXpLKfmZstI",
    "order_id": "ord_eCacpFwavzi",
    "receipt_number": "2409051289614565",
    "status": "succeeded",
    "amount": 9499,
    "currency": "USD",
    "payment_method": "cards",
    "created_at": 1725547595,
    "modified_at": 1725547657,
    "metadata": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "checkout.purchase",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

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

EventData 스키마

필드유형설명
idstring결제 고유 식별자
order_idstring연관된 주문의 고유 식별자
receipt_numberstring사람이 읽을 수 있는 영수증 번호
statusenum현재 결제 상태 (성공, 취소됨, 환불, 거절됨, 분쟁, 만료됨, 보류 중, 환불됨, 거절됨, 무효 처리됨)
amountnumber소액 화폐 단위로 표시된 결제 금액
currencystring결제 통화
payment_method문자열사용된 결제 방법 (카드, apple_pay, google_pay, paypal 등)
created_atinteger결제가 생성된 시점의 Unix 타임스탬프
modified_atinteger결제가 마지막으로 수정된 시점의 Unix 타임스탬프
metadataobject\null

이벤트 유형

결제 상태 변경에 따라 다음 이벤트 유형에 대해 웹훅이 트리거됩니다:

  • payment.succeeded
  • payment.canceled
  • payment.chargeback
  • payment.declined
  • payment.dispute
  • payment.expired
  • payment.pending
  • payment.refunded
  • payment.rejected
  • payment.voided

도움이 필요하세요?
통합팀에 문의하십시오 integration@aghanim.com

On this page