결제 웹훅

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

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

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

중복 결제 이벤트 처리

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

결제 이벤트 처리 시:

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

결제 상태

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

succeeded – 결제가 성공적으로 완료되었으며 사용자의 계좌에서 자금이 차감되었습니다. 이 이벤트는 이전에 분쟁이 있던 결제가 판매자에게 유리하게 해결되거나 보류 중인 환불이 처리될 수 없는 경우에도 발생합니다. 초기 성공과 이러한 복구 시나리오를 구분하려면 페이로드의 refund 및 chargeback 하위 객체를 확인하세요.
abandoned – 사용자가 결제를 취소했습니다.
chargeback – 차지백 분쟁이 플레이어에게 유리하게 해결된 후 결제가 취소되었습니다.
declined – 사용자의 결제 수단이 거부되어 결제를 완료할 수 없었습니다
dispute – 사용자가 이 결제에 대해 결제 수단과 분쟁을 제기했습니다
expired – 결제가 기한 내에 완료되지 않아 만료되었습니다
pending – 사용자가 결제를 시작했고 완료를 기다리고 있습니다
refunded – 결제가 환불되었고 자금이 사용자에게 반환되었습니다
rejected – 결제가 잠재적 사기로 표시되어 처리되지 않았습니다
voided – 자금이 이체되기 전에 결제가 무효화되었습니다

요구 사항

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

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

구성

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

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

요청 스키마

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

HTTP
cURL

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": 94,
    "amount_decimal": 94.99,
    "currency": "USD",
    "payment_method": "cards",
    "created_at": 1725547595,
    "modified_at": 1725547657,
    "metadata": null,
    "decline_reason_code": null,
    "decline_reason": null,
    "three_d_secure_result": "authenticated",
    "three_d_secure_flow": "challenge"
  },
  "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"
}
            

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "payment.succeeded",
      "event_data": {
        "id": "pmt_eFgYpxryeKXpLKfmZstI",
        "order_id": "ord_eCacpFwavzi",
        "receipt_number": "2409051289614565",
        "status": "succeeded",
        "amount": 94,
        "amount_decimal": 94.99,
        "currency": "USD",
        "payment_method": "cards",
        "created_at": 1725547595,
        "modified_at": 1725547657,
        "metadata": null,
        "decline_reason_code": null,
        "decline_reason": null,
        "three_d_secure_result": "authenticated",
        "three_d_secure_flow": "challenge"
      },
      "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_id`	`string`	Aghanim에 의해 생성된 고유 이벤트 ID.
`game_id`	`string`	Aghanim 시스템에서의 귀하의 게임 ID.
`event_type`	`string`	이벤트의 유형, `payment.succeeded` 이럴 경우.
`event_time`	`number`	The time the event was sent, in Unix epoch time. May differ across duplicate deliveries of the same event.
`event_data`	`EventData`	이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
`idempotency_key`	`string`	웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다.
`request_id`	`string\|null`	이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
`sandbox`	`boolean`	이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
`trigger`	`string\|null`	이벤트가 전송된 원인이 된 트리거입니다.
`transaction_id`	`string`	Aghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
`context`	`object\|null`	이벤트에 대한 컨텍스트 정보.

EventData 스키마

필드	유형	설명
`id`	string	결제 고유 식별자
`order_id`	string	연관된 주문의 고유 식별자
`receipt_number`	string	사람이 읽을 수 있는 영수증 번호
`status`	enum	현재 결제 상태 (succeeded, abandoned, chargeback, declined, dispute, expired, pending, refunded, rejected, voided)
~~`amount`~~	integer	[Deprecated] 주요 화폐 단위로 표시된 결제 금액(정수로 절사). 정확한 금액은 `amount_decimal`을 사용하세요.
`amount_decimal`	number\	null
`currency`	string	결제 통화
`payment_method`	문자열	사용된 결제 방법 (카드, apple_pay, google_pay, paypal 등)
`created_at`	integer	결제가 생성된 시점의 Unix 타임스탬프
`modified_at`	integer	결제가 마지막으로 수정된 시점의 Unix 타임스탬프
`metadata`	object\	null
`decline_reason`	string\	null
`decline_reason_code`	string\	null
`three_d_secure_result`	string\	null
`three_d_secure_flow`	string\	null

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