백엔드 API 통해 구매 수행

이벤트 구매를 수신하고 플레이어의 권한을 트래킹하는 자체 백엔드를 구현합니다.

읽는 시간 7분

최근 업데이트: 2달 전

게임에서 서버 권한 권한을 사용하는 경우 다음을 수행하는 백엔드 시스템을 구현합니다.

Webhook 이벤트(JWT) 확인
이벤트 파스.
시스템의 자격 또는 인벤토리를 이벤트 유형에 따라 업데이트합니다.
주문을 완료된 것으로 표시합니다.
이벤트 응답 반환

이렇게 하면 시스템과 Unity IAP가 모두 동기화됩니다.

중요

백엔드가 플레이어에게 권한을 부여하더라도 모든 유료 주문을 완료된 것으로 표시해야 합니다. 플레이어는 어쨌든 자격을 유지하지만, 순서가

paid

상태로 유지되면 Unity IAP 주문 추적 및 분석이 불완전합니다. SDK와 웹후크를 혼합하는 하이브리드 설정에서 승인되지 않은 주문은 시스템 간에 순서 상태가 움직일 수도 있습니다.

JWT(Webhook Event) 확인

확인을 활성화하기 위해 Unity IAP는 JWT(JSON 웹 토큰)로 웹후크 요청에 서명합니다. 백엔드에서 이 토큰에 대한 다음 정보를 확인하여 이벤트가 유효한지 확인합니다.

인증 헤더
SIGNATURE 비공개 키로 서명됨. 다음을 확인하기 위해 **JWKS(공용 키)**를 가져와 캐시합니다.
```
https://services.api.unity.com/webhooks/.well-known/jwks.json
```

발급자:

https://services.api.unity.com/webhooks/

고객 요구 사항(배열):
```
upid
```
(Unity 프로젝트 ID),
```
envId
```
(환경 ID)
토큰 만료일:
```
exp
```
( 만료일)가 통과되지 않았는지 확인합니다.

JWT를 검증하는 데 사용할 수 있는 대부분의 언어 라이브러리가 있습니다.

Webhook 이벤트 셰이프

Unity IAP는 지원되는 모든 결제 제공업체의 이벤트를 이 일관된 포맷으로 정규화합니다. 다음 예를 참고하십시오.


{  "id": "018d5e5e-5e5e-7e5e-5e5e-5e5e5e5e5e5e",  "version": "1.0.0",  "eventType": "order.paid",  "time": "2024-01-15T14:30:00Z",  "projectId": "018d5e5e-1111-7e5e-5e5e-111111111111",  "environmentId": "018d5e5e-2222-7e5e-5e5e-222222222222",  "dataType": "order",  "data": {    "id": "018d5e5e-3333-7e5e-5e5e-333333333333",    "playerId": "player_12345",    "paymentProvider": "stripe",    "paymentProviderResourceId": "cs_test_a1b2c3d4e5f6",    "url": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6",    "lineItems": [      {        "sku": "com.game.coins_100",        "productType": "소모품",        "price": {          "amountMicros": 4990000,          "currency": "USD"        }      }    ],    "total": {      "amountMicros": 4990000,      "currency": "USD",      "refundedAmountMicros": 0    },    "status": "paid",    "customReferenceId": "order_xyz_789",    "metadata": {      "campaign": "summer_sale",      "platform": "iOS"    },    "createdAt": "2024-01-15T14:25:00Z",    "updatedAt": "2024-01-15T14:30:00Z",    "paidAt": "2024-01-15T14:30:00Z",    "fulfilledAt": null  }}

Webhook 이벤트의 다음 필드를 참조하십시오.

id

string

필수

웹후크 이벤트의 고유 식별자입니다.

version

string

필수

Webhook 이벤트 스키마의 버전입니다.

eventType

string

필수

이벤트 유형입니다. 가능한 값은 이벤트 타입을 참조하십시오.

time

string

필수

이벤트가 생성된 시간입니다(ISO 8601 형식).

projectId

string

필수

이 순서가 속한 Unity 프로젝트 ID입니다.

environmentId

string

필수

이 주문이 발생한 Unity 환경의 ID입니다.

dataType

string

필수

이벤트의 데이터 유형입니다.

data

object

필수

구매에 대한 세부 정보가 포함된 주문 데이터 오브젝트입니다.

id

string

필수

주문의 고유 식별자입니다.

playerId

string

필수

Unity Authentication 플레이어 ID입니다.

paymentProvider

string

필수

주문을 처리한 결제 제공업체(예:

stripe

또는

coda

)

paymentProviderResourceId

string

필수

결제 제공업체가 리소스에 할당한 고유 ID입니다.

url

string

필수

주문의 체크아웃 URL입니다.

lineItems

object array

필수

주문 시 구매한 상품 목록입니다.

sku

string

필수

제품의 고유 식별자입니다.

productType

string

필수

제품 유형(예:

Consumable

)입니다.

price

object

필수

제품의 가격입니다.

amountMicros

integer

필수

마이크로미터 단위(1,000,000마이크로미터와 $1.00)입니다. 이 값은 사용자에게 표시된 값입니다.

currency

string

필수

3개의 글자 ISO 4217 통화 코드입니다.

total

object

필수

총 주문 금액입니다.

amountMicros

integer

필수

전체 주문 금액(마이크로)입니다.

currency

string

필수

3개의 글자 ISO 4217 통화 코드입니다.

refundedAmountMicros

integer

필수

환불된 총 금액(마이크로)입니다. 부분 환불의 경우, 이는

amountMicros

보다 작을 수 있습니다.

status

string

필수

순서의 상태입니다. 가능한 값:

created

paid

failed

fulfilled

revoked

customReferenceId

string

주문에 대한 선택적인 커스텀 레퍼런스 ID입니다.

metadata

object

구매 플로 중에 전달된 커스텀 메타데이터를 포함하는 키-값 오브젝트입니다.

createdAt

string

필수

순서가 생성된 시점의 타임스탬프입니다(ISO 8601 형식).

updatedAt

string

필수

순서가 마지막으로 업데이트된 시점의 타임스탬프입니다(ISO 8601 형식).

paidAt

string

주문이 지급된 시점의 타임스탬프입니다(ISO 8601 형식).

fulfilledAt

string

주문이 완료되었을 때의 타임스탬프 또는 아직 완료되지 않은 경우의

null

입니다.

revokedAt

string

주문이 취소되었을 때의 타임스탬프 또는 취소되지 않은 경우의

null

입니다.

이벤트 유형

Unity IAP는 다음과 같은 웹후크 이벤트 타입을 전송합니다.

order.paid

플레이어가 구매를 성공적으로 완료하면 Unity IAP가

order.paid

이벤트를 전송합니다. 이 이벤트를 수신하면 플레이어에게 구매한 자격 또는 화폐를 부여하고 주문이 완료된 것으로 표시합니다.

order.updated

Unity IAP는 주문이 업데이트될 때마다

order.updated

이벤트를 전송합니다. 여기에는 다음과 같은 변경 사항이 포함됩니다.

완료된 것으로 표시되는 순서입니다.
처리 중인 환불입니다.
기타 순서 수정.

data.total

의

refundedAmountMicros

필드는 현재 환불된 총액을 나타냅니다.

환불은 개발자가 시작합니다. 예를 들어 결제 제공업체의 대시보드를 통해 플레이어에게 환불을 보낼 수 있습니다.

환불이 발생하면 Unity IAP는 자동으로 권한을 취소하지 않습니다. 환불된 자격을 취소하려는 경우 이 이벤트를 수신하고 자격 시스템에서 처리할 수 있습니다.

order.revoked

주문 상태가

revoked

로 변경되면 Unity IAP가

order.revoked

이벤트를 전송합니다. 이 이벤트를 수신하면 플레이어의 원래 구매에 허용된 자격 또는 재화를 취소합니다.

충전은 플레이어가 시작합니다. 예를 들어 플레이어는 신용 카드 회사 또는 은행을 통해 비용에 대해 논쟁할 수 있습니다.

인보이스 충돌이 종료되고 플레이어가 이기면 Unity IAP는 자동으로 주문을 취소하고 이 이벤트를 전송합니다. 환불과 달리, Unity IAP는 과금에 대한 권한을 취소합니다.

API 통해 실행된 주문 표시

백엔드에서 권한을 부여한 후 Orders API 사용하여 순서를 완료된 것으로 표시합니다. 이렇게 하면

fulfilledAt

타임스탬프가 업데이트되고 주문 상태가 올바르게 추적됩니다.

Authentication

이러한 엔드포인트를 호출하려면 다음 방법 중 하나를 사용하여 인증해야 합니다.

서비스 계정 Unity Dashboard에서 서비스 계정을 생성하고 이를 사용하여 백엔드 서버를 인증합니다. 자세한 내용은 서비스 계정 인증을 참고하십시오.
Cloud Code 프로젝트를 대신하여 인증할 수 있는 Cloud Code 스크립트 또는 모듈에서 엔드포인트를 호출합니다. 자세한 내용은 구매를 위해 Cloud Code 모듈 사용을 참고하십시오.

주문 가져오기

주문을 검색하려면

GET

엔드포인트를 호출합니다.


GET https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/{orderId}

주문 상태

상태	설명
`created`	주문이 생성되었지만 결제가 완료되지 않았습니다. `paid` , `failed` 또는 `cancelled` 로 전환할 수 있습니다.
`paid`	지급 공급자가 지급을 수령하고 확인했습니다. `fulfilled` 또는 `revoked` 로 전환 가능
`fulfilled`	주문이 이행되고 플레이어에게 보상이 제공됩니다. `전환 가능한 상태` revoked`
`failed`	순서 실패。 이는 터미널 상태입니다.
`revoked`	주문이 취소되었습니다. 이는 터미널 상태입니다.
`cancelled`	결제 전에 주문이 취소되었습니다. 이는 터미널 상태입니다.

응답 예시

GET

및

PATCH

엔드포인트 모두 전체 주문 객체를 반환합니다.


{  "id": "018d5e5e-3333-7e5e-5e5e-333333333333",  "projectId": "018d5e5e-1111-7e5e-5e5e-111111111111",  "environmentId": "018d5e5e-2222-7e5e-5e5e-222222222222",  "playerId": "player_12345",  "paymentProvider": "stripe",  "paymentProviderResourceId": "cs_test_12345",  "url": "https://checkout.stripe.com/pay/cs_test_12345",  "lineItems": [    {      "sku": "com.game.coins_100",      "productType": "Consumable"    }  ],  "status": "paid",  "fulfilledAt": null,  "revokedAt": null,  "customReferenceId": "order_xyz_789",  "metadata": {    "campaign": "summer_sale"  },  "createdAt": "2024-01-15T14:25:00Z",  "updatedAt": "2024-01-15T14:30:00Z"}

주문 업데이트

주문 상태를 업데이트하려면

PATCH

엔드포인트를 호출합니다.


PATCH https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{environmentId}/orders/{orderId}

요청 본문


{  "status": "fulfilled"}

status

string

필수

순서에 대해 설정할 새 상태입니다. 허용된 값: .

```
fulfilled
```
: 플레이어에게 권한을 부여한 후 설정합니다.
```
paid
```
주문 시에만 설정할 수 있습니다.
```
revoked
```
: 을 설정하면 플레이어의 권한이 취소됩니다(예: 환불 후).
```
paid
```
또는
```
fulfilled
```
주문 시에만 설정할 수 있습니다.
```
cancelled
```
: 주문을 취소하도록 설정합니다.
```
created
```
주문(지급 전)에만 설정할 수 있습니다.

주문이

revoked

또는

cancelled

이면 해당 상태는 변경할 수 없습니다.

HTTP 응답 상태 코드는 IAP 클라이언트 API 문서를 참조하십시오.

이벤트 응답 반환

이벤트 리스폰스를 반환하여 이벤트 처리의 성공 여부를 나타내야 합니다.

"response": 성공적인 이벤트 처리를 나타냅니다.
비
2xx
응답: 실패를 나타냅니다. Unity IAP는 리플레이 정책에 따라 이벤트를 재생합니다.

이벤트 리플레이 동작

Webhook 엔드포인트가 비

2xx

응답을 반환하면 Unity IAP가 이벤트 전송을 자동으로 재시도합니다. 리플레이된 이벤트가 중복된 자격으로 이어지지 않도록 웹후크 핸들러가 고정된 상태여야 합니다.

다음 단계

이 페이지는 IAP를 사용하여 D2C(Direct-to-Consumer) 결제 제공업체를 설정하는 워크플로의 일부입니다. 이 워크플로를 계속하려면 다음 옵션 중 하나를 선택합니다.

Integrate D2C payment providers

Integrate D2C payment providers with IAP 워크플로 페이지로 돌아갑니다.

Test your integration

워크플로의 다음 단계로 이동하여 D2C 결제 제공업체를 설정합니다.

백엔드 API 통해 구매 수행

JWT(Webhook Event) 확인

Webhook 이벤트 셰이프

id

version

eventType

time

projectId

environmentId

dataType

data

data properties

id

playerId

paymentProvider

paymentProviderResourceId

url

lineItems

lineItems properties

sku

productType

price

price properties

amountMicros

currency

total

total properties

amountMicros

currency

refundedAmountMicros

status

customReferenceId

metadata

createdAt

updatedAt

paidAt

fulfilledAt

revokedAt

이벤트 유형

order.paid

order.updated

order.revoked

API 통해 실행된 주문 표시

Authentication

주문 가져오기

주문 상태

상태

설명

응답 예시

주문 업데이트

요청 본문

status

이벤트 응답 반환

이벤트 리플레이 동작

다음 단계