API 문서

Benta Payments API는 결제 처리 서비스로, 모바일 알림을 통한 은행 입금 확인을 자동화하는 시스템입니다. 이 문서에서는 API의 사용 방법을 상세히 설명합니다.

웹훅 시스템

Benta Payments의 웹훅 시스템은 결제 상태 변경 시 설정된 URI로 알림을 전송합니다.

중요: 웹훅 페이로드 구조

웹훅은 결제 ID만 포함합니다. 전체 결제 정보를 얻으려면 /payments/confirm API를 호출하여 검증해야 합니다.

웹훅 페이로드

결제가 입금 확인되어 PROGRESS 상태가 되면, 설정된 웹훅 URI로 다음과 같은 페이로드가 전송됩니다:

{
  "payment_id": "2f9a7b5c-1d3e-4f8a-9b2c-6d7e8f9a0b1c"
}

참고: 페이로드에는 결제 ID만 포함됩니다. 전체 결제 정보, 금액, 상태 등은 포함되지 않습니다.

웹훅 수신 후 처리 과정

웹훅 수신

서버가 POST 요청으로 {payment_id}를 수신합니다.

결제 검증 API 호출

POST /payments/confirm을 호출하여 결제를 검증합니다.

POST https://api.benta.im/payments/confirm
Content-Type: application/json

{
  "payToken": "2f9a7b5c-1d3e-4f8a-9b2c-6d7e8f9a0b1c",
  "token": "your_api_token"
}

결제 정보 획득 및 처리

API 응답에서 결제 상태, 금액, 메타데이터 등을 확인하고 비즈니스 로직을 처리합니다.

{
  "id": "2f9a7b5c-1d3e-4f8a-9b2c-6d7e8f9a0b1c",
  "status": "COMPLETE",
  "method": "DEPOSIT",
  "paid_amount": 10000,
  "verified_ts": "2023-05-01T12:30:00Z"
}

HTTP 200 응답

처리 완료 후 HTTP 200 상태 코드를 응답하여 웹훅이 성공적으로 처리되었음을 알립니다.

웹훅 헤더

모든 웹훅 요청에는 다음 헤더가 포함됩니다:

헤더명	값	설명
Content-Type	application/json	요청 본문 형식
User-Agent	Benta-Payments-Webhook/1.0	웹훅 식별자
X-Webhook-ID	[웹훅 이벤트 ID]	웹훅 이벤트 고유 ID
X-Retry-Count	[재시도 횟수]	현재 재시도 횟수 (0부터 시작)

재시도 정책

웹훅 전송이 실패할 경우, 시스템은 다음과 같은 간격으로 최대 10회까지 자동 재시도합니다:

시도	대기 시간	누적 시간
시도 1	즉시	00:00:00
시도 2	5초	00:00:05
시도 3	5분	00:05:05
시도 4	30분	00:35:05
시도 5	2시간	02:35:05
시도 6	5시간	07:35:05
시도 7	10시간	17:35:05
시도 8	14시간	31:35:05
시도 9	20시간	51:35:05
시도 10	24시간	75:35:05

10회 재시도 후에도 실패하면 웹훅은 '실패' 상태로 표시되며, 수동 재전송이 필요합니다.

타임아웃 및 특수 동작

타임아웃

웹훅 요청은 10초 타임아웃이 설정되어 있습니다. 10초 내에 응답하지 않으면 실패로 처리되어 재시도 대기열에 추가됩니다.

COMPLETE 상태 결제

이미 COMPLETE 상태인 결제는 웹훅 재전송 시도 시 자동으로 delivered 상태로 표시되며 실제 전송은 하지 않습니다.

멱등성

동일한 payment_id에 대해 여러 번 웹훅이 전송될 수 있으므로, 서버 측에서 멱등성을 보장하도록 구현하세요.