결제 안내
{order.amount.function toLocaleString() { [native code] }()}원
- 입금 은행
- {account.bankName}
- 계좌번호
-
{account.number}
- 예금주
- {account.holder}
- ⭐ 입금자명
-
{order.customerName}
이 이름으로 정확히 이체해 주세요!
- 입금 금액
- {order.amount.function toLocaleString() { [native code] }()}원
{/* 결제 상태 실시간 확인 */}
);
}
```
--------------------------------
### invoice.paid Event Payload Example
Source: https://docs.paysync.kr/api-reference/webhooks/invoice-paid
Example JSON payload for the invoice.paid event. The invoice object matches the Invoice schema and includes id, issuerId, customer, cashReceipt, amount, paid, metadata, issuedAt, and expiresAt. The trigger field indicates the cause of payment completion.
```json
{
"type": "invoice.paid",
"invoice": {
"id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
"issuerId": "acc_x9y8z7w6v5u4t3s2r1q0p9o8",
"bankAccountIds": [],
"customer": {
"name": "홍길동",
"email": "hong@example.com",
"phoneNumber": "01012345678"
},
"cashReceipt": null,
"amount": 50000,
"paid": true,
"metadata": { "orderId": "ORDER-2026-0001" },
"issuedAt": "2026-04-28T03:14:15.926Z",
"expiresAt": "2026-04-29T03:14:15.926Z"
},
"trigger": "AUTOMATIC_MATCHING"
}
```
--------------------------------
### Kotlin: 주문 생성 (Ktor Client)
Source: https://docs.paysync.kr/api-reference/introduction
Kotlin의 Ktor Client를 사용하여 페이싱크 API로 주문을 생성하는 예제입니다. API 키는 환경 변수 PAYSYNC_API_KEY에서 읽어옵니다.
```kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
val client = HttpClient(CIO) {
install(ContentNegotiation) { json() }
}
val response: HttpResponse = client.post("https://api.paysync.kr/v1/invoices") {
bearerAuth(System.getenv("PAYSYNC_API_KEY"))
contentType(ContentType.Application.Json)
setBody(mapOf(
"customer" to mapOf(
"name" to "홍길동",
"email" to "hong@example.com",
"phoneNumber" to "01012345678",
),
"amount" to 50000,
"expireAfter" to "1d",
"metadata" to mapOf("orderId" to "ORDER-2026-0001"),
))
}
println(response.bodyAsText())
```
--------------------------------
### GET /cash-receipts
Source: https://docs.paysync.kr/cash-receipts/list
현금영수증 목록 조회 API 문서입니다. 쿼리 파라미터와 응답, 오류 코드를 포함합니다.
```APIDOC
## [GET] /cash-receipts
### Description
현금영수증 목록을 조회합니다. 다양한 필터 조건(검색어, 발급 상태, 사업자등록번호, 종류, 식별자, 날짜 범위)을 지원하며, 페이지네이션을 위한 offset과 limit 파라미터를 사용합니다.
### Method
GET
### Endpoint
/cash-receipts
### Parameters
#### Query Parameters
- **offset** (integer) - Required - 건너뛸 아이템 수. **0 이상.**
- **limit** (integer) - Required - 한 번에 조회할 아이템 수. **1 이상 100 이하.**
- **search** (string) - Optional - 검색어. **식별자(`identifier`)** 등에서 부분 일치로 검색합니다.
- **status** (string) - Optional - 발급 상태로 필터링. 가능한 값: `PENDING`, `ISSUED`, `FAILED`, `REVOKED`
- **corpNum** (string) - Optional - 발행자 사업자등록번호로 필터링.
- **type** (string) - Optional - 현금영수증 종류로 필터링 (`PERSONAL` / `CORPORATE`).
- **identifier** (string) - Optional - 식별자로 정확히 일치 필터링. 휴대폰 번호 또는 사업자번호.
- **dateAfter** (string) - Optional - 이 날짜 **이후**(포함) 발급된 내역만 조회. `YYYY-MM-DD` 형식.
- **dateBefore** (string) - Optional - 이 날짜 **이전**(포함) 발급된 내역만 조회. `YYYY-MM-DD` 형식.
### Response
#### Success Response (200)
- **code** (string) - Required - 항상 `"OK"`
- **totalItems** (integer) - Required - 필터 조건에 부합하는 **전체** 아이템 수.
- **data** (array) - Required - 현재 페이지의 현금영수증 객체 배열. 각 객체는 현금영수증 단건 조회 응답의 `data` 와 동일한 스키마입니다.
#### Response Example
{
"code": "OK",
"totalItems": 0,
"data": []
}
#### Error Responses
##### 401 UNAUTHORIZED — 인증 실패
- **NOT_AUTHORIZED** - `Authorization` 헤더가 없거나 만료/폐기된 키입니다.
##### 403 FORBIDDEN — 권한 오류
- **LIMIT_EXCEEDS_MAXIMUM** - `limit` 이 100 을 초과했습니다.
##### 422 UNPROCESSABLE_CONTENT — 검증 실패
- **INVALID_OFFSET** - `offset` 이 0 미만입니다.
- **INVALID_LIMIT** - `limit` 이 0 이하입니다.
- **INVALID_DATE_RANGE_FORMAT** - `dateAfter` 또는 `dateBefore` 가 `YYYY-MM-DD` 형식이 아닙니다.
```
--------------------------------
### 200 OK response for get invoice
Source: https://docs.paysync.kr/invoices/get
Successful response with invoice data. The `paid` field indicates payment status.
```json
{
"code": "OK",
"data": {
"id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
"issuerId": "acc_x9y8z7w6v5u4t3s2r1q0p9o8",
"bankAccountIds": [],
"customer": {
"name": "홍길동",
"email": "hong@example.com",
"phoneNumber": "01012345678"
},
"cashReceipt": null,
"amount": 50000,
"paid": false,
"metadata": {
"orderId": "ORDER-2026-0001"
},
"issuedAt": "2026-04-28T03:14:15.926Z",
"expiresAt": "2026-04-29T03:14:15.926Z"
}
}
```
--------------------------------
### Python (Flask) 웹훅 시그니처 검증
Source: https://docs.paysync.kr/api-reference/webhooks/overview
Flask를 사용한 Python 웹훅 검증 예시입니다. raw body를 사용하고, 5분 타임스탬프 윈도우, HMAC-SHA256 서명 검증, hmac.compare_digest로 안전하게 비교합니다. 검증 후 event["type"]으로 분기 처리합니다.
```python
import base64
import hmac
import hashlib
import os
import time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["PAYSYNC_WEBHOOK_SECRET"] # whsec_...
@app.post("/paysync/webhook")
def paysync_webhook():
id_ = request.headers["webhook-id"]
ts = request.headers["webhook-timestamp"]
sig_header = request.headers["webhook-signature"]
body = request.get_data(as_text=True)
if abs(int(time.time()) - int(ts)) > 300:
abort(401, "expired")
key = base64.b64decode(SECRET.removeprefix("whsec_"))
expected = base64.b64encode(
hmac.new(key, f"{id_}.{ts}.{body}".encode(), hashlib.sha256).digest()
).decode()
provided = sig_header.split(",", 1)[1]
if not hmac.compare_digest(expected, provided):
abort(401, "invalid signature")
event = request.get_json()
# event["type"] 으로 분기 처리
return "", 200
```
--------------------------------
### cURL request to get invoice
Source: https://docs.paysync.kr/invoices/get
Fetches invoice details using cURL. Requires an API key in the Authorization header.
```bash
curl https://api.paysync.kr/v1/invoices/ivc_a1b2c3d4e5f6g7h8i9j0k1l2 \
-H "Authorization: Bearer YOUR_API_KEY"
```
--------------------------------
### Java: 주문 생성 (HttpClient)
Source: https://docs.paysync.kr/api-reference/introduction
Java의 java.net.http.HttpClient를 사용하여 페이싱크 API로 주문을 생성하는 예제입니다. API 키는 환경 변수 PAYSYNC_API_KEY에서 읽어옵니다.
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class IssueInvoice {
public static void main(String[] args) throws Exception {
String body = """
{
"customer": {
"name": "홍길동",
"email": "hong@example.com",
"phoneNumber": "01012345678"
},
"amount": 50000,
"expireAfter": "1d",
"metadata": { "orderId": "ORDER-2026-0001" }
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.paysync.kr/v1/invoices"))
.header("Authorization", "Bearer " + System.getenv("PAYSYNC_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse