준비하기

SDK 설치

Node.js·Python 공식 SDK와 OpenAPI 규격. 10줄이면 결제 링크가 발급됩니다.

SDK 저장소: github.com/GOATHEAVEN-Inc/cari-pay-sdk

cari-pay-sdk/
├── openapi.yaml            # 결제 게이트웨이 API 규격 (Swagger UI·클라이언트 생성기용)
├── billing-openapi.yaml    # 청구서 API 규격 (가맹점 토큰)
├── node/                   # JavaScript / TypeScript SDK  (의존성 0개, Node 18+)
└── python/                 # Python SDK                    (표준 라이브러리만, 3.9+)

Node.js / TypeScript

Shell

npm install github:GOATHEAVEN-Inc/cari-pay-sdk

JavaScript

import { CariPay, CariPayBilling } from "@caripay/sdk";

// 결제 링크 API — CARIPAY_MODE / CARIPAY_PLATFORM_CODE / CARIPAY_STORE_CODE / CARIPAY_API_KEY
const pay = CariPay.fromEnv();

// 청구서 API — 가맹점 계정으로 로그인(토큰 자동 갱신)
const billing = await CariPayBilling.login({
  email: process.env.CARIPAY_BILLING_EMAIL,
  password: process.env.CARIPAY_BILLING_PASSWORD,
});

타입 정의(index.d.ts)가 포함돼 TypeScript에서 바로 자동완성됩니다. 전체 서버 예제는 node/example-express.mjs(생성·콜백·폴링·멱등 처리)를 보세요. 셀프체크: cd node && npm test.

Python

Shell

pip install "git+https://github.com/GOATHEAVEN-Inc/cari-pay-sdk.git#subdirectory=python"

Python

import os
from caripay import CariPay, CariPayBilling

pay = CariPay.from_env()
billing = CariPayBilling.login(email=os.environ["CARIPAY_BILLING_EMAIL"], password=os.environ["CARIPAY_BILLING_PASSWORD"])

셀프체크: cd python && python3 test_caripay.py && python3 test_billing.py.

환경변수

변수	용도
`CARIPAY_MODE`	`test`(기본) / `live`. 게이트웨이 주소를 고릅니다
`CARIPAY_PLATFORM_CODE` · `CARIPAY_STORE_CODE` · `CARIPAY_API_KEY`	결제 링크 API
`CARIPAY_BILLING_EMAIL` · `CARIPAY_BILLING_PASSWORD`	청구서 API 로그인(권장)
`CARIPAY_BILLING_ACCESS_TOKEN`	청구서 API 접근 토큰(직접 관리할 때)
`CARIPAY_BILLING_BASE_URL`	청구 API 주소를 바꿀 때만(기본 `https://api.dev.caripay.co.kr`)

그 외 언어

서명 규칙만 맞추면 어떤 언어든 됩니다. openapi.yaml로 클라이언트를 생성하거나 curl 규격 그대로 호출하세요.

Shell

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g java -o ./client
npx @redocly/cli preview-docs openapi.yaml     # 브라우저로 규격 열람

SDK가 해 주는 것 / 하지 않는 것

해 주는 것	하지 않는 것
서명 생성, `TRANS_AT` 계산, 거래번호 채번(`newTransSeqno`)	금액 결정 — 금액은 귀사 서버 카탈로그에서 정합니다
`RESULT_CODE` 판정, 오류를 `CariPayError`로 변환	콜백 수신 서버 — 귀사가 구현합니다
`confirmCallback()` 이중확인, `waitForPayment()` 폴링	자동 재시도 — 청구서 발송은 같은 `requestId`로만 재시도하세요
청구서 API 토큰 로그인·자동 갱신	브라우저·앱에서의 실행 — 서버 전용입니다

문서에 없는 내용이나 오류는 bellight@goatheaven.com 또는 지원 문의로 알려주세요.