가맹점 조회 API

Authorization: Bearer psk_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "as_of": "2026-10-31T09:00:00+09:00",   // 원천을 조회한 시각
  "request_id": "3f2a9c1e-…",              // 문의할 때 알려 줄 번호
  "data": [ … ],                            // 목록이면 배열, 한 건이면 객체
  "next_cursor": null                       // 목록일 때만. null 이면 마지막 쪽
}

CREATE TABLE paysoft_billing (
  contract_id      BIGINT       NOT NULL,   -- Billing.contract_id
  month            CHAR(6)      NOT NULL,   -- Billing.month (YYYYMM)
  member_no        VARCHAR(200),            -- Billing.customer_key (우리 회원번호)
  customer_code    VARCHAR(50)  NOT NULL,   -- Billing.customer_code
  status           VARCHAR(20)  NOT NULL,   -- paid · unpaid · in_progress · canceled · unknown
  status_name      VARCHAR(50),             -- 화면 표시용 한글
  billed_amount    INT          NOT NULL,
  paid_amount      INT          NOT NULL,
  unpaid_amount    INT          NOT NULL,
  review_required  BOOLEAN      NOT NULL,   -- true 면 재청구 금지
  key_shared       BOOLEAN      NOT NULL,   -- Billing.customer_key_shared (true 면 사람이 확인)
  failure_category VARCHAR(20),             -- Billing.failure.category
  auto_retry       BOOLEAN,                 -- Billing.failure.auto_retry
  as_of            TIMESTAMP    NOT NULL,   -- 응답의 as_of
  PRIMARY KEY (contract_id, month)
);

{ "error": { "code": "RANGE_TOO_LONG", "message": "조회 기간은 최대 31일입니다.", "request_id": "3f2a9c1e-…" } }

curl "https://api.paysoft.co.kr/v1/billings?month=202610&status=unpaid" \
  -H "Authorization: Bearer $PAYSOFT_API_KEY"

r = requests.get("https://api.paysoft.co.kr/v1/billings",
                 params={"month": "202610", "status": "unpaid"},
                 headers={"Authorization": f"Bearer {os.environ['PAYSOFT_API_KEY']}"}, timeout=30)
for b in r.json()["data"]:
    print(b["customer_key"], b["contract_id"], b["status_name"], b["unpaid_amount"])

const url = new URL("https://api.paysoft.co.kr/v1/billings");
url.search = new URLSearchParams({ month: "202610", status: "unpaid" });
const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.PAYSOFT_API_KEY}` } });
const { data } = await r.json();
data.forEach(b => console.log(b.customer_key, b.contract_id, b.status_name, b.unpaid_amount));

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.paysoft.co.kr/v1/billings?month=202610&status=unpaid"))
    .header("Authorization", "Bearer " + System.getenv("PAYSOFT_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
// JSON 해석은 Jackson·Gson 등 쓰시는 라이브러리로

$ch = curl_init("https://api.paysoft.co.kr/v1/billings?" . http_build_query(["month" => "202610", "status" => "unpaid"]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PAYSOFT_API_KEY")],
    CURLOPT_TIMEOUT => 30,
]);
$body = json_decode(curl_exec($ch), true);
foreach ($body["data"] as $b) {
    echo $b["customer_key"], " ", $b["status_name"], " ", $b["unpaid_amount"], PHP_EOL;
}

{
  "as_of": "2026-10-31T09:00:00+09:00",
  "request_id": "3f2a9c1e-…",
  "data": [
    {
      "month": "202610", "contract_id": 1002, "contract_no": "TEST-ORD-1002",
      "contract_status": "active", "contract_status_name": "정상",
      "account": "TEST", "customer_code": "C0002", "customer_key": "MEM-2",
      "status": "paid", "status_name": "결제 완료", "review_required": false,
      "billed_amount": 30000, "paid_amount": 30000, "unpaid_amount": 0,
      "attempts": 2, "paid_date": "2026-10-15", "last_attempt_date": "2026-10-15",
      "failure": null
    },
    {
      "month": "202610", "contract_id": 1005, "contract_no": "TEST-ORD-1005",
      "contract_status": "active", "contract_status_name": "정상",
      "account": "TEST", "customer_code": "C0005", "customer_key": "MEM-5",
      "status": "unpaid", "status_name": "미납", "review_required": false,
      "billed_amount": 30000, "paid_amount": 0, "unpaid_amount": 30000,
      "attempts": 2, "paid_date": null, "last_attempt_date": "2026-10-15",
      "failure": { "code": "Q301", "category": "잔액부족", "auto_retry": false }
    }
  ],
  "next_cursor": null
}

{
  "month": "202610",
  "total": { "count": 6, "billed_amount": 140000, "paid_amount": 50000, "unpaid_amount": 30000 },
  "by_status": [
    { "status": "paid", "status_name": "결제 완료", "count": 2, "billed_amount": 50000, "paid_amount": 50000, "unpaid_amount": 0 },
    { "status": "unpaid", "status_name": "미납", "count": 1, "billed_amount": 30000, "paid_amount": 0, "unpaid_amount": 30000 },
    …
  ],
  "review_required": 1
}

curl "https://api.paysoft.co.kr/v1/payments?from=2026-10-01&to=2026-10-31&status=failed" \
  -H "Authorization: Bearer $PAYSOFT_API_KEY"

import os, requests

url = "https://api.paysoft.co.kr/v1/payments"
headers = {"Authorization": f"Bearer {os.environ['PAYSOFT_API_KEY']}"}
params = {"from": "2026-10-01", "to": "2026-10-31", "status": "failed"}

items = []
while True:
    r = requests.get(url, headers=headers, params=params, timeout=30)
    r.raise_for_status()                 # 503 이면 '결제 없음'으로 보지 말고 다시 시도
    body = r.json()
    items += body["data"]
    if not body["next_cursor"]:
        break
    params["cursor"] = body["next_cursor"]

const url = new URL("https://api.paysoft.co.kr/v1/payments");
url.search = new URLSearchParams({ from: "2026-10-01", to: "2026-10-31", status: "failed" });
const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.PAYSOFT_API_KEY}` } });
const body = await r.json();

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.paysoft.co.kr/v1/payments?from=2026-10-01&to=2026-10-31&status=failed"))
    .header("Authorization", "Bearer " + System.getenv("PAYSOFT_API_KEY"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

$q = http_build_query(["from" => "2026-10-01", "to" => "2026-10-31", "status" => "failed"]);
$ch = curl_init("https://api.paysoft.co.kr/v1/payments?" . $q);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PAYSOFT_API_KEY")]]);
$body = json_decode(curl_exec($ch), true);

{
  "as_of": "2026-10-31T09:00:00+09:00",
  "request_id": "3f2a9c1e-…",
  "data": [
    {
      "transaction_id": "TEST20261010005",
      "account": "TEST",
      "customer_code": "C0005",
      "customer_key": "MEM-5",
      "member_id": "M0005",
      "payment_kind": "CMS",
      "contract_id": 1005,
      "payment_month": "202610",
      "payment_count": 10,
      "payment_date": "2026-10-10",
      "amount": 30000,
      "paid_amount": null,
      "status": "failed",
      "status_code": "500",
      "review_required": false,
      "failure": { "code": "Q301", "category": "잔액부족", "auto_retry": false, "retryable": true },
      "cancel_kind": null,
      "updated_at": "2026-10-10T18:00:00"
    }
  ],
  "next_cursor": null
}

{
  "from": "2026-10-01", "to": "2026-10-31",
  "total": { "count": 8, "amount": 190000, "paid_amount": 50000, "review_required": 1 },
  "days": [
    { "date": "2026-10-10", "count": 5, "amount": 110000, "paid_amount": 20000, "review_required": 1,
      "by_status": {
        "succeeded": { "status_name": "결제 성공", "count": 1, "amount": 20000, "paid_amount": 20000 },
        "failed":    { "status_name": "결제 실패", "count": 2, "amount": 60000, "paid_amount": 0 },
        …
      } }
  ]
}

curl "https://api.paysoft.co.kr/v1/payments/TEST20261010005" \
  -H "Authorization: Bearer $PAYSOFT_API_KEY"

r = requests.get("https://api.paysoft.co.kr/v1/payments/TEST20261010005", headers=headers, timeout=30)
if r.status_code == 404:
    # '없는 거래'로 단정하지 말 것 — 조회 범위 밖일 수 있다. 재청구 전에 페이소프트에 확인
    ...

curl "https://api.paysoft.co.kr/v1/contracts?customer_key=MEM-1" \
  -H "Authorization: Bearer $PAYSOFT_API_KEY"

r = requests.get("https://api.paysoft.co.kr/v1/contracts", params={"customer_key": "MEM-1"}, headers=headers, timeout=30)
for c in r.json()["data"]:
    print(c["contract_id"], c["status_name"], c["payment_type_name"], c["monthly_amount"])

curl "https://api.paysoft.co.kr/v1/customers?customer_key=MEM-1" \
  -H "Authorization: Bearer $PAYSOFT_API_KEY"

r = requests.get("https://api.paysoft.co.kr/v1/customers", params={"customer_key": "MEM-1"}, headers=headers, timeout=30)
c = r.json()["data"][0]
print(c["auto_debit"]["status_name"], [x["contract_id"] for x in c["contracts"]])

{
  "account": "TEST", "customer_code": "C0001", "customer_key": "MEM-1", "in_use": true,
  "extra_fields": [
    { "no": 1, "name": "회원번호", "value": "MEM-1" },
    { "no": 2, "name": "회원 등급", "value": "VIP" }
  ],
  "auto_debit": {
    "status": "registered", "status_name": "등록 완료",
    "methods": [ { "payment_kind": "CMS", "member_id": "M0001", "status": "registered",
                   "status_name": "등록 완료", "status_code": "900", "recurring": true, "updated_at": "…" } ]
  },
  "contracts": [
    { "contract_id": 1001, "contract_no": "TEST-ORD-1001", "status": "active", "status_name": "정상",
      "payment_type": "CMS", "monthly_amount": 20000, "billing_start": "2026-01-10", "billing_end": "2027-12-10" },
    { "contract_id": 1006, "contract_no": "TEST-ORD-1006", "status": "active", "status_name": "정상",
      "payment_type": "CARD", "monthly_amount": 30000, "billing_start": "2026-01-10", "billing_end": "2027-12-10" }
  ],
  "created_at": "…", "updated_at": "…"
}

[ { "account": "TEST", "customer_key_field": 1,
    "fields": [ { "no": 1, "name": "회원번호", "required": true, "options": null },
                { "no": 2, "name": "회원 등급", "required": false, "options": ["일반", "VIP"] } ] } ]

curl "https://api.paysoft.co.kr/v1/members?size=100" \
  -H "Authorization: Bearer $PAYSOFT_API_KEY"

r = requests.get("https://api.paysoft.co.kr/v1/members", headers=headers, params={"size": 100}, timeout=30)

{
  "as_of": "2026-10-31T09:00:00+09:00",
  "request_id": "9b1c…",
  "data": [
    {
      "account": "TEST", "customer_code": "C0001", "member_id": "M0001",
      "payment_kind": "CMS", "recurring": true,
      "registration_status": "registered", "registration_status_code": "900",
      "updated_at": "2026-10-01T09:00:00"
    }
  ],
  "next_cursor": null
}

{
  "customer_code": "C0001",
  "accounts": ["TEST"],
  "payment_methods": [
    { "account": "TEST", "member_id": "M0001", "payment_kind": "CMS", "recurring": true,
      "registration_status": "registered", "registration_status_code": "900", "updated_at": "…" }
  ]
}

# paysoft_client.py — pip install requests
import os
import time

import requests

BASE = "https://api.paysoft.co.kr/v1"
_session = requests.Session()
_session.headers["Authorization"] = f"Bearer {os.environ['PAYSOFT_API_KEY']}"


class PaysoftError(Exception):
    def __init__(self, status, code, message, request_id):
        super().__init__(f"{status} {code}: {message} (request_id={request_id})")
        self.status, self.code, self.request_id = status, code, request_id


def call(path, params=None, max_tries=4):
    """GET 한 번. 429·503·연결 오류는 기다렸다 다시 시도한다."""
    for attempt in range(1, max_tries + 1):
        try:
            r = _session.get(BASE + path, params=params, timeout=30)
        except requests.RequestException:
            if attempt == max_tries:
                raise
            time.sleep(2 ** attempt)
            continue
        if r.status_code == 200:
            return r.json()
        wait = int(r.headers.get("Retry-After", "0") or 0)
        if r.status_code in (429, 503) and attempt < max_tries and wait <= 60:
            time.sleep(wait or 5)
            continue
        err = r.json().get("error", {}) if "json" in r.headers.get("Content-Type", "") else {}
        raise PaysoftError(r.status_code, err.get("code"), err.get("message"), err.get("request_id"))


def iter_all(path, params):
    """목록 API 의 모든 쪽을 차례로 돌려준다."""
    params = dict(params)
    while True:
        body = call(path, params)
        yield from body["data"]
        if not body["next_cursor"]:
            return
        params["cursor"] = body["next_cursor"]

// paysoftClient.mjs — Node.js 18 이상
const BASE = "https://api.paysoft.co.kr/v1";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export class PaysoftError extends Error {
  constructor(status, code, message, requestId) {
    super(`${status} ${code}: ${message} (request_id=${requestId})`);
    Object.assign(this, { status, code, requestId });
  }
}

export async function call(path, params = {}, maxTries = 4) {
  const url = new URL(BASE + path);
  Object.entries(params).forEach(([k, v]) => v != null && url.searchParams.set(k, v));
  for (let attempt = 1; attempt <= maxTries; attempt++) {
    let r;
    try {
      r = await fetch(url, {
        headers: { Authorization: `Bearer ${process.env.PAYSOFT_API_KEY}` },
        signal: AbortSignal.timeout(30_000),
      });
    } catch (e) {
      if (attempt === maxTries) throw e;
      await sleep(2 ** attempt * 1000);
      continue;
    }
    if (r.ok) return r.json();
    const wait = Number(r.headers.get("Retry-After") || 0);
    if ([429, 503].includes(r.status) && attempt < maxTries && wait <= 60) {
      await sleep((wait || 5) * 1000);
      continue;
    }
    const { error = {} } = await r.json().catch(() => ({}));
    throw new PaysoftError(r.status, error.code, error.message, error.request_id);
  }
}

export async function* iterAll(path, params) {
  let cursor;
  do {
    const body = await call(path, { ...params, cursor });
    yield* body.data;
    cursor = body.next_cursor;
  } while (cursor);
}

// PaysoftClient.java — Java 11 이상. JSON 해석은 Jackson(com.fasterxml.jackson.databind) 사용
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.*;
import java.util.function.Consumer;
import java.util.stream.Collectors;

public class PaysoftClient {
    private static final String BASE = "https://api.paysoft.co.kr/v1";
    private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    private final ObjectMapper json = new ObjectMapper();
    private final String key = System.getenv("PAYSOFT_API_KEY");

    public JsonNode call(String path, Map<String, String> params) throws Exception {
        String q = params.entrySet().stream()
            .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));
        HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + path + (q.isEmpty() ? "" : "?" + q)))
            .header("Authorization", "Bearer " + key).timeout(Duration.ofSeconds(30)).GET().build();
        for (int attempt = 1; ; attempt++) {
            HttpResponse<String> r = http.send(req, HttpResponse.BodyHandlers.ofString());
            if (r.statusCode() == 200) return json.readTree(r.body());
            long wait = r.headers().firstValueAsLong("Retry-After").orElse(0);
            if ((r.statusCode() == 429 || r.statusCode() == 503) && attempt < 4 && wait <= 60) {
                Thread.sleep((wait == 0 ? 5 : wait) * 1000);
                continue;
            }
            throw new IllegalStateException(r.statusCode() + " " + r.body());   // error.code·request_id 를 로그에
        }
    }

    /** 목록 API 의 모든 쪽을 차례로 넘긴다. */
    public void forEach(String path, Map<String, String> params, Consumer<JsonNode> each) throws Exception {
        Map<String, String> p = new LinkedHashMap<>(params);
        while (true) {
            JsonNode body = call(path, p);
            body.get("data").forEach(each);
            JsonNode next = body.get("next_cursor");
            if (next == null || next.isNull()) return;
            p.put("cursor", next.asText());
        }
    }
}

<?php
// paysoft_client.php — PHP 7.4 이상, curl 확장
const PAYSOFT_BASE = "https://api.paysoft.co.kr/v1";

function paysoft_call(string $path, array $params = [], int $maxTries = 4): array {
    $url = PAYSOFT_BASE . $path . ($params ? "?" . http_build_query($params) : "");
    for ($attempt = 1; ; $attempt++) {
        $ch = curl_init($url);
        $headers = [];
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("PAYSOFT_API_KEY")],
            CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
                $p = explode(":", $line, 2);
                if (count($p) === 2) $headers[strtolower(trim($p[0]))] = trim($p[1]);
                return strlen($line);
            },
        ]);
        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($status === 200) return json_decode($body, true);
        $wait = (int)($headers["retry-after"] ?? 0);
        if (in_array($status, [429, 503, 0], true) && $attempt < $maxTries && $wait <= 60) {
            sleep($wait ?: 5);
            continue;
        }
        $err = json_decode((string)$body, true)["error"] ?? [];
        throw new RuntimeException("$status " . ($err["code"] ?? "") . ": " . ($err["message"] ?? "")
            . " (request_id=" . ($err["request_id"] ?? "") . ")");
    }
}

function paysoft_iter_all(string $path, array $params): Generator {
    while (true) {
        $body = paysoft_call($path, $params);
        yield from $body["data"];
        if (empty($body["next_cursor"])) return;
        $params["cursor"] = $body["next_cursor"];
    }
}

from datetime import date

from paysoft_client import PaysoftError, call, iter_all


def sync_month(month: str, db) -> int:
    """month 예: "202610". 받은 줄 수를 돌려준다."""
    as_of = None
    n = 0
    for b in iter_all("/billings", {"month": month}):
        f = b["failure"] or {}
        db.execute(
            """INSERT INTO paysoft_billing
                 (contract_id, month, member_no, customer_code, status, status_name,
                  billed_amount, paid_amount, unpaid_amount, review_required, key_shared,
                  failure_category, auto_retry, as_of)
               VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s, NOW())
               ON DUPLICATE KEY UPDATE                       -- MySQL 기준. PostgreSQL 은 ON CONFLICT
                 status=VALUES(status), status_name=VALUES(status_name),
                 paid_amount=VALUES(paid_amount), unpaid_amount=VALUES(unpaid_amount),
                 review_required=VALUES(review_required), key_shared=VALUES(key_shared),
                 failure_category=VALUES(failure_category), auto_retry=VALUES(auto_retry), as_of=NOW()""",
            (b["contract_id"], b["month"], b["customer_key"], b["customer_code"], b["status"],
             b["status_name"], b["billed_amount"], b["paid_amount"], b["unpaid_amount"],
             b["review_required"], b["customer_key_shared"], f.get("category"), f.get("auto_retry")))
        n += 1
    db.commit()
    return n


if __name__ == "__main__":
    try:
        print(sync_month(date.today().strftime("%Y%m"), db=...))   # 우리 회사 DB 연결
    except PaysoftError as e:
        # 503 이 4번 이어져도 여기로 온다 — 저장된 상태를 지우지 말고 다음 실행을 기다린다
        print("동기화 실패:", e)

import { iterAll, PaysoftError } from "./paysoftClient.mjs";

export async function syncMonth(month, db) {   // month 예: "202610"
  let n = 0;
  for await (const b of iterAll("/billings", { month })) {
    const f = b.failure ?? {};
    await db.query(
      `INSERT INTO paysoft_billing
         (contract_id, month, member_no, customer_code, status, status_name,
          billed_amount, paid_amount, unpaid_amount, review_required, failure_category, auto_retry, as_of)
       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12, now())
       ON CONFLICT (contract_id, month) DO UPDATE SET               -- PostgreSQL 기준
         status = EXCLUDED.status, status_name = EXCLUDED.status_name,
         paid_amount = EXCLUDED.paid_amount, unpaid_amount = EXCLUDED.unpaid_amount,
         review_required = EXCLUDED.review_required, failure_category = EXCLUDED.failure_category,
         auto_retry = EXCLUDED.auto_retry, as_of = now()`,
      [b.contract_id, b.month, b.customer_key, b.customer_code, b.status, b.status_name,
       b.billed_amount, b.paid_amount, b.unpaid_amount, b.review_required, f.category ?? null, f.auto_retry ?? null]);
    n++;
  }
  return n;
}

PaysoftClient client = new PaysoftClient();
String month = java.time.YearMonth.now().format(java.time.format.DateTimeFormatter.ofPattern("yyyyMM"));

client.forEach("/billings", Map.of("month", month), b -> {
    JsonNode f = b.get("failure");
    billingRepository.upsert(                          // (contract_id, month) 기준으로 덮어쓰기
        b.get("contract_id").asLong(), b.get("month").asText(),
        b.get("customer_key").asText(null), b.get("customer_code").asText(),
        b.get("status").asText(), b.get("status_name").asText(),
        b.get("billed_amount").asInt(), b.get("paid_amount").asInt(), b.get("unpaid_amount").asInt(),
        b.get("review_required").asBoolean(),
        f.isNull() ? null : f.get("category").asText(),
        f.isNull() ? null : f.get("auto_retry").asBoolean());
});

<?php
require "paysoft_client.php";

$pdo = new PDO(/* 우리 회사 DB */);
$stmt = $pdo->prepare(
    "INSERT INTO paysoft_billing (contract_id, month, member_no, customer_code, status, status_name,
       billed_amount, paid_amount, unpaid_amount, review_required, failure_category, auto_retry, as_of)
     VALUES (?,?,?,?,?,?,?,?,?,?,?,?, NOW())
     ON DUPLICATE KEY UPDATE status=VALUES(status), status_name=VALUES(status_name),
       paid_amount=VALUES(paid_amount), unpaid_amount=VALUES(unpaid_amount),
       review_required=VALUES(review_required), failure_category=VALUES(failure_category),
       auto_retry=VALUES(auto_retry), as_of=NOW()");

foreach (paysoft_iter_all("/billings", ["month" => date("Ym")]) as $b) {
    $f = $b["failure"] ?? [];
    $stmt->execute([$b["contract_id"], $b["month"], $b["customer_key"], $b["customer_code"],
        $b["status"], $b["status_name"], $b["billed_amount"], $b["paid_amount"], $b["unpaid_amount"],
        (int)$b["review_required"], $f["category"] ?? null, isset($f["auto_retry"]) ? (int)$f["auto_retry"] : null]);
}

from paysoft_client import iter_all

GUIDE = {
    "잔액부족": "결제 계좌의 잔액이 부족해 이번 달 이용료가 출금되지 않았습니다.",
    "한도초과": "결제 한도를 넘어 이번 달 이용료가 결제되지 않았습니다.",
    "계좌상태": "결제 계좌를 사용할 수 없습니다. 결제 계좌를 바꿔 주세요.",
    "카드상태": "결제 카드를 사용할 수 없습니다. 결제 카드를 바꿔 주세요.",
    "카드사확인": "카드사에서 결제를 거절했습니다. 카드사에 문의해 주세요.",
}


def unpaid_targets(month):
    for b in iter_all("/billings", {"month": month, "status": "unpaid"}):
        f = b["failure"] or {}
        if b["review_required"] or f.get("auto_retry"):
            continue                       # 페이소프트 확인·자동 재결제 대기 — 안내하지 않음
        if b["customer_key_shared"]:
            continue                       # 고객키가 다른 고객과 겹침 — 사람이 확인 후 안내
        yield {
            "member_no": b["customer_key"],          # 우리 회원번호 → 우리 DB 에서 연락처를 찾는다
            "contract_id": b["contract_id"],
            "amount": b["unpaid_amount"],
            "message": GUIDE.get(f.get("category"), "이번 달 이용료가 결제되지 않았습니다. 고객센터로 문의해 주세요."),
        }

import { iterAll } from "./paysoftClient.mjs";

const GUIDE = {
  잔액부족: "결제 계좌의 잔액이 부족해 이번 달 이용료가 출금되지 않았습니다.",
  한도초과: "결제 한도를 넘어 이번 달 이용료가 결제되지 않았습니다.",
  계좌상태: "결제 계좌를 사용할 수 없습니다. 결제 계좌를 바꿔 주세요.",
  카드상태: "결제 카드를 사용할 수 없습니다. 결제 카드를 바꿔 주세요.",
  카드사확인: "카드사에서 결제를 거절했습니다. 카드사에 문의해 주세요.",
};

export async function unpaidTargets(month) {
  const out = [];
  for await (const b of iterAll("/billings", { month, status: "unpaid" })) {
    const f = b.failure ?? {};
    if (b.review_required || f.auto_retry) continue;   // 안내하지 않음
    if (b.customer_key_shared) continue;                // 고객키가 겹침 — 사람이 확인
    out.push({ memberNo: b.customer_key, contractId: b.contract_id, amount: b.unpaid_amount,
               message: GUIDE[f.category] ?? "이번 달 이용료가 결제되지 않았습니다. 고객센터로 문의해 주세요." });
  }
  return out;
}

RETRYABLE_CATEGORIES = {"잔액부족", "한도초과", "일시장애"}
FAILED = {"unpaid", "failed"}            # Billing.status / Payment.status 의 실패 값


def can_recharge(item: dict) -> tuple[bool, str]:
    """item: Billing 또는 Payment 객체. (다시 청구해도 되는가, 이유)"""
    if item.get("review_required"):
        return False, "확인 필요 — 페이소프트 확인을 기다립니다"
    if item.get("status") not in FAILED:
        return False, f"실패 상태가 아님({item.get('status')})"
    f = item.get("failure") or {}
    if f.get("auto_retry"):
        return False, "자동 재결제 대상 — 페이소프트가 다시 청구합니다"
    if "retryable" in f:                  # Payment 에만 있음
        ok = f["retryable"]
    else:                                 # Billing 은 분류로 판단
        ok = f.get("category") in RETRYABLE_CATEGORIES
    return (True, "고객 안내 후 다시 청구 가능") if ok else (False, f"고객 조치 필요({f.get('category')})")

const RETRYABLE_CATEGORIES = new Set(["잔액부족", "한도초과", "일시장애"]);
const FAILED = new Set(["unpaid", "failed"]);

/** item: Billing 또는 Payment. { ok, reason } */
export function canRecharge(item) {
  if (item.review_required) return { ok: false, reason: "확인 필요 — 페이소프트 확인을 기다립니다" };
  if (!FAILED.has(item.status)) return { ok: false, reason: `실패 상태가 아님(${item.status})` };
  const f = item.failure ?? {};
  if (f.auto_retry) return { ok: false, reason: "자동 재결제 대상" };
  const ok = "retryable" in f ? f.retryable : RETRYABLE_CATEGORIES.has(f.category);
  return ok ? { ok: true, reason: "고객 안내 후 다시 청구 가능" }
            : { ok: false, reason: `고객 조치 필요(${f.category})` };
}

static final Set<String> RETRYABLE_CATEGORIES = Set.of("잔액부족", "한도초과", "일시장애");
static final Set<String> FAILED = Set.of("unpaid", "failed");

/** item: Billing 또는 Payment(JsonNode). true 일 때만 다시 청구한다. */
static boolean canRecharge(JsonNode item) {
    if (item.path("review_required").asBoolean(false)) return false;
    if (!FAILED.contains(item.path("status").asText())) return false;
    JsonNode f = item.path("failure");
    if (f.isMissingNode() || f.isNull()) return false;
    if (f.path("auto_retry").asBoolean(false)) return false;
    if (f.has("retryable")) return f.get("retryable").asBoolean();      // Payment
    return RETRYABLE_CATEGORIES.contains(f.path("category").asText()); // Billing
}

from paysoft_client import call


def member_billing_view(member_no: str, month: str) -> dict:
    customers = call("/customers", {"customer_key": member_no})["data"]
    if not customers:
        return {"registered": False}
    c = customers[0]
    billings = {b["contract_id"]: b for b in call("/billings", {"month": month, "customer_key": member_no})["data"]}
    return {
        "registered": True,
        "auto_debit": c["auto_debit"]["status_name"],              # 예: 등록 완료
        "contracts": [
            {
                "contract_id": k["contract_id"],
                "contract_status": k["status_name"],                 # 예: 정상
                "monthly_amount": k["monthly_amount"],
                "this_month": billings.get(k["contract_id"], {}).get("status_name", "청구 없음"),
            }
            for k in c["contracts"]
        ],
    }

import { call } from "./paysoftClient.mjs";

export async function memberBillingView(memberNo, month) {
  const { data: customers } = await call("/customers", { customer_key: memberNo });
  if (!customers.length) return { registered: false };
  const c = customers[0];
  const { data: rows } = await call("/billings", { month, customer_key: memberNo });
  const billings = new Map(rows.map((b) => [b.contract_id, b]));
  return {
    registered: true,
    autoDebit: c.auto_debit.status_name,
    contracts: c.contracts.map((k) => ({
      contractId: k.contract_id, contractStatus: k.status_name, monthlyAmount: k.monthly_amount,
      thisMonth: billings.get(k.contract_id)?.status_name ?? "청구 없음",
    })),
  };
}

아래 "페이소프트 가맹점 조회 API" 문서를 읽고 연동 코드를 만들어 줘.

[우리 환경]
- 언어/프레임워크: (예: Python 3.12 + Django / Java 17 + Spring Boot / PHP 8 + Laravel / Node.js 20)
- DB: (예: MySQL 8 / PostgreSQL 16 / Oracle)
- 우리 회원번호 컬럼: (예: members.member_no) — 페이소프트 고객키(customer_key)와 같은 값
- 실행 방식: (예: 매일 10시·15시 cron / Spring @Scheduled)

[만들 것]
1. 공통 호출 모듈: Authorization: Bearer 키(환경변수 PAYSOFT_API_KEY), 429·503 은 Retry-After 만큼 기다렸다 재시도, next_cursor 로 모든 쪽 넘기기
2. 이번 달 /v1/billings 를 받아 (contract_id, month) 기준으로 우리 DB 에 덮어쓰는 동기화 작업
3. 미납(status=unpaid) 회원 목록 조회 함수
4. 테스트 코드 (테스트 키의 가상 데이터 기준: 1001 paid, 1002 paid(재출금), 1003 unknown, 1004 canceled, 1005 unpaid, 1006 in_progress)

[반드시 지킬 것]
- 이 API 는 조회만 한다. 결제·취소 호출을 만들지 마.
- status 가 unknown 이거나 review_required 가 true 면 재청구 대상에서 빼.
- failure.auto_retry 가 true 면 재청구 대상에서 빼.
- customer_key_shared 가 true 면 다른 고객과 고객키가 겹친 것이니 자동 안내·자동 처리에서 빼고 따로 표시해.
- 503 을 '결제 없음'으로 저장하지 말고, 호출이 실패하면 기존 저장값을 지우지 마.
- 문서에 없는 필드나 엔드포인트를 지어내지 마. 모르는 응답 필드는 무시해.
- API 키를 코드에 쓰지 마.

[문서]
(여기에 /portal/docs.md 내용을 붙여 넣기)

{ "error": { "code": "RANGE_TOO_LONG", "message": "조회 기간은 최대 31일입니다.", "request_id": "…" } }