# 서버 연동 개요

import { Callout } from "zudoku/ui/Callout";

가맹점 서버는 결제 세션을 만들고, 결제 승인을 요청하고, 최종 결제 결과를 확인합니다. 결제창은 가맹점 화면이 열지만 결제의 시작과 끝은 모두 가맹점 서버가 결정합니다.

<Callout type="caution" title="point3 API는 서버에서만 호출하세요">
  API 키를 가맹점 화면이나 앱의 코드, URL 또는 로그에 포함하지 마세요.
</Callout>

## 서버가 하는 일

| 순서 | 작업 | 호출 API | 안내 |
| --- | --- | --- | --- |
| 1 | 주문 금액을 확인하고 결제 세션 생성 | `POST /payment/v3/session` | [결제 생성](/payment-creation) |
| 2 | 가맹점 화면에서 결제 승인 준비 신호를 받으면 승인 요청 | `POST /capture/v2/{sessionId}` | [결제 승인](/payment-capture) |
| 3 | 승인 응답이 불확실하면 결제 세션 조회 | `GET /payment/v3/session/{sessionId}` | [결제 승인](/payment-capture#최종-결과-확인) |
| 4 | 승인된 결제의 전부 또는 일부 취소 | `POST /refunds/v1/{sessionId}` | [결제 취소](/payment-cancellation) |
| 선택 | 로그인한 회원이면 결제창을 열기 전에 위임 인증 생성 | `POST /authn/v2/delegation` | [위임 인증 생성](/delegated-creation) |

전체 흐름과 결제 세션 상태는 [결제 흐름과 상태](/payment-flow)에서 한 번에 확인할 수 있습니다.

## API 호출 규칙

### 주소

모든 API는 `https://api.point3.io`를 사용합니다. 별도의 테스트 환경 주소는 제공하지 않습니다.

### 인증

<a href="https://docs.point3.io/dashboard/development/tokens">대시보드 - 개발정보 관리</a>에서 발급받은 API 키를 `Authorization` 헤더에 담아 보냅니다.

```http
Authorization: Bearer {API 키}
Content-Type: application/json
```

브라우저에서 사용하는 `client_id`는 결제창을 열 때 가맹점을 식별하는 값이며, API 키와 다릅니다.

### 재시도

- 결제 승인 API는 같은 `sessionId`로 다시 호출해도 결제가 중복되지 않습니다. 네트워크 오류, 타임아웃, `5xx` 뒤에는 시간을 두고 다시 호출하거나 결제 세션을 조회하세요.
- 결제 취소 API는 `Idempotency-Key` 헤더로 24시간 동안 같은 요청의 중복 처리를 막을 수 있습니다. 자세한 내용은 [결제 취소](/payment-cancellation#선택적-멱등-키)를 참고하세요.
- `400`, `401`, `403`, `404`는 요청을 고치기 전까지 같은 결과가 반환되므로 그대로 재시도하지 마세요.

응답 코드별 처리 기준은 [에러 코드](/error-codes)에서 확인하세요.

### EOB 점검 시간

매일 23:30부터 다음 날 00:30까지(KST)는 점검 시간으로 결제 세션 생성, 결제 진행, 결제 취소가 제한됩니다. 점검 중 응답 형식은 [EOB 점검 시간](/operations#eob-점검-시간)을 참고하세요.