API 문서
Benta Payments API는 결제 처리 서비스로, 모바일 알림을 통한 은행 입금 확인을 자동화하는 시스템입니다. 이 문서에서는 API의 사용 방법을 상세히 설명합니다.
개요
Benta 마인크래프트 스토어는 마인크래프트 서버 운영자가 게임 내 상품을 판매할 수 있는 플랫폼입니다.
대시보드에서 상품을 등록하면 유저가 스토어에서 결제를 진행할 수 있으며,
결제 완료 시 metadata.minecraft_product 필드를 통해
어떤 상품이 결제되었는지 확인하여 자동으로 상품을 지급할 수 있습니다.
중요
metadata.minecraft_product 필드는 Benta 마인크래프트 스토어를 통해 결제된 건에 대해서만 응답에 포함됩니다.
일반 결제 API를 통해 생성된 결제에는 이 필드가 포함되지 않습니다.
연동 단계
상품 등록
Benta 대시보드에서 마인크래프트 스토어에 상품을 추가합니다.
- Benta 대시보드에 로그인합니다.
- 애플리케이션 > 스토어 연동 메뉴로 이동합니다.
- Benta 마인크래프트 스토어 섹션에서 상품을 추가합니다.
- 상품명, 가격, 설명 등의 정보를 입력합니다.
- 저장 시 고유한 상품 ID가 생성됩니다.
결제 진행
마인크래프트 스토어에서 유저가 결제를 진행합니다.
- 유저가 마인크래프트 스토어에서 상품을 선택합니다.
- 결제 정보를 입력하고 결제를 진행합니다.
- 결제가 시작되면 서버로 결제 상태가 PROGRESS로 변경됩니다.
- 이 시점에서 Webhook이 설정되어 있다면 알림이 전송됩니다.
결제 완료 처리
Polling 또는 Webhook 방식으로 결제를 완료하고 상품을 지급합니다.
- Polling: GET /callback/rest API를 주기적으로 호출하여 완료된 결제를 확인합니다.
- Webhook: 설정된 URL로 결제 알림을 수신하고 POST /payments/confirm으로 검증합니다.
- 응답의 metadata.minecraft_product 필드에서 결제된 상품 ID를 확인합니다.
- 상품 ID를 대시보드에 등록된 상품과 매칭하여 해당 상품을 유저에게 지급합니다.
결제 완료 응답 예시
마인크래프트 스토어에서 결제가 완료된 경우에만 다음과 같이 metadata.minecraft_product 필드가 포함된 응답을 받게 됩니다.
{
"id": "2f9a7b5c-1d3e-4f8a-9b2c-6d7e8f9a0b1c",
"identifier": "{minecraft_user_uuid}",
"status": "COMPLETE",
"method": "DEPOSIT",
"paid_amount": 5000,
"verified_ts": "2023-05-01T12:30:00Z",
"metadata": {
"minecraft_product": "{product_id}",
"items": [
{
"name": "다이아몬드 검",
"price": 5000,
"count": 1
}
]
}
}상품 ID 매칭
| 필드 | 설명 | 조건 |
|---|---|---|
metadata.minecraft_product | 대시보드에서 등록한 상품의 고유 ID | 마인크래프트 스토어 결제만 |
metadata.items | 결제된 상품의 상세 정보 (이름, 가격, 수량) | 일반 결제 |
Tip: 대시보드에서 상품을 등록할 때 생성되는 상품 ID를 서버에 미리 저장해두면,
결제 완료 시 minecraft_product 값과 비교하여
어떤 상품을 지급해야 하는지 빠르게 확인할 수 있습니다.