Members Only — 개발자 문서

Members Only API 문서

RESTful JSON API로 결제, 멤버, 구독을 제어합니다. 모든 요청은 TLS로 암호화되며 표준 HTTP 상태 코드와 구조화된 에러를 반환합니다.

Base URL: https://api.membersonly.fun/v1

모든 예제는 테스트 키를 사용합니다. 운영 환경에서는 서버 환경 변수로 비밀키를 안전하게 로드하세요.

Quickstart

가장 빠른 시작: 멤버 생성 후 결제를 생성합니다.

1) SDK 설치

npm install @monly/sdk

pnpm add @monly/sdk

yarn add @monly/sdk

2) 멤버 생성

curl -X POST \
  https://api.membersonly.fun/v1/members \
  -H "Authorization: Bearer $MONLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "tier": "basic"
  }'

import membersOnly from '@monly/sdk';

const member = await membersOnly.members.create({
  email: 'user@example.com',
  tier: 'basic',
});

3) 결제 생성

curl -X POST \
  https://api.membersonly.fun/v1/payments \
  -H "Authorization: Bearer $MONLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sponsorship",
    "amount": 50000,
    "currency": "KRW",
    "memberId": "mem_123"
  }'

import membersOnly from '@monly/sdk';

const payment = await membersOnly.payments.create({
  type: 'sponsorship',
  amount: 50000,
  currency: 'KRW',
  memberId: 'mem_123',
});

Authentication

모든 API 요청은 Bearer 토큰을 사용해 인증합니다. 대시보드에서 발급한 비밀 키를 헤더에 추가하세요.

Authorization: Bearer sk_test_123...

비밀 키는 클라이언트에 노출하지 마세요. 서버 사이드 환경 변수에 저장하세요.

API Reference

Members

멤버 생성, 조회, 업데이트, 삭제.

# Create
curl -X POST https://api.membersonly.fun/v1/members \
  -H "Authorization: Bearer $MONLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

# Retrieve
curl https://api.membersonly.fun/v1/members/mem_123 \
  -H "Authorization: Bearer $MONLY_API_KEY"

const member = await membersOnly.members.retrieve('mem_123');
await membersOnly.members.update('mem_123', { tier: 'premium' });

Payments

일회성 결제 생성 및 상태 조회.

curl https://api.membersonly.fun/v1/payments/pay_123 \
  -H "Authorization: Bearer $MONLY_API_KEY"

const payment = await membersOnly.payments.retrieve('pay_123');

Subscriptions

구독 생성, 갱신, 취소 및 청구 주기 관리.

curl -X POST https://api.membersonly.fun/v1/subscriptions \
  -H "Authorization: Bearer $MONLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memberId":"mem_123","plan":"pro_monthly"}'

await membersOnly.subscriptions.create({
  memberId: 'mem_123',
  plan: 'pro_monthly',
});

Webhooks

결제 완료, 환불, 구독 이벤트 등 상태 변경을 실시간으로 수신합니다.

엔드포인트를 HTTPS로 구성하고, 요청 서명을 검증하세요.

예제 페이로드

{
  "id": "evt_123",
  "type": "payment.succeeded",
  "created": 1710000000,
  "data": {
    "object": {
      "id": "pay_123",
      "amount": 50000,
      "currency": "KRW",
      "status": "succeeded"
    }
  }
}

서명 검증

import crypto from 'node:crypto';

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret).update(payload, 'utf8').digest('hex');
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(signature));
}

SDKs

가장 인기 있는 런타임과 프레임워크를 지원합니다.

JavaScript/TypeScript (Node.js, Edge)
React, Next.js 미들웨어
REST API (모든 언어)

Errors

에러 응답은 다음 형식을 따릅니다.

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "Required parameter 'amount' is missing"
  }
}

Errors

에러 응답은 다음 형식을 따릅니다.

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "Required parameter 'amount' is missing"
  }
}

주요 에러 유형 예시:

invalid_request: 잘못된 파라미터, 형식 오류, 필수값 누락
authentication_error: 잘못된/누락된 API 키, 권한 불충분
rate_limit_exceeded: 호출 한도 초과
payment_error: 결제 실패(카드 거절 등). code로 세부 사유 제공
internal_error: 일시적 서버 오류. 재시도 전략 적용 권장

Rate limits

기본 한도는 초당 10 요청입니다. 초과 시 429를 반환하며, 지수 백오프로 재시도하세요.

Environments

테스트와 운영 환경을 분리하여 안전하게 개발하세요.

Test: 테스트 키로만 호출 가능. 실제 청구 없음.
Live: 운영 키로 호출. 실제 청구 및 멤버 데이터 반영.

환경 별 API 키를 구분하여 보관하고, 서버 환경변수로 주입하세요. 클라이언트에 비밀 키를 절대 노출하지 마세요.

Pagination & Filtering

모든 목록 API는 커서 기반 페이지네이션을 사용하며, 표준 필터 파라미터를 지원합니다.

curl "https://api.membersonly.fun/v1/members?limit=50&cursor=abc123&status=active" \
  -H "Authorization: Bearer $MONLY_API_KEY"

const list = await membersOnly.members.list({
  limit: 50,
  cursor: 'abc123',
  status: 'active',
  expand: ['latestPayment']
});

추가 파라미터: createdFrom, createdTo, email, tier. 연관 리소스는 expand로 인라인 확장할 수 있습니다.

Idempotency

결제·멤버 생성 등 변경 연산은 멱등 키를 사용하여 안전한 재시도를 보장합니다.

curl -X POST https://api.membersonly.fun/v1/payments \
  -H "Authorization: Bearer $MONLY_API_KEY" \
  -H "Idempotency-Key: 9f4e2a9a-56b7-4f5e-8b0a-..." \
  -H "Content-Type: application/json" \
  -d '{"type":"sponsorship","amount":50000,"currency":"KRW","memberId":"mem_123"}'

await membersOnly.payments.create(
  { type: 'sponsorship', amount: 50000, currency: 'KRW', memberId: 'mem_123' },
  { idempotencyKey: crypto.randomUUID() }
);

같은 멱등 키로 24시간 내 재시도 시 최초 결과가 재현됩니다.

Versioning

하위 호환성을 유지하면서 새로운 기능을 지속적으로 추가합니다.

베이스 URL: /v1
중요한 비호환 변경 발생 시 메이저 버전 업(예: /v2)
필드 추가는 선택적(optional)로만 진행

Security

API 키는 서버 환경 변수에 보관하고, 저장소에 커밋하지 마세요.
TLS(HTTPS) 강제. HSTS 권장.
웹훅은 서명 검증을 반드시 수행하세요.
PII/민감정보는 필요 최소한만 수집·보관하세요.

Best Practices

네트워크 오류에 대비한 지수 백오프 재시도
서버 타임아웃(예: 10s) 및 클라이언트 취소 처리
웹훅 수신 엔드포인트는 200 OK를 빠르게 반환하고, 비동기로 후처리
페이지네이션을 사용하여 대량 데이터 점진적 처리

Examples

가장 흔한 사용 시나리오 예제입니다.

1) 멤버 생성 후 첫 결제

const member = await membersOnly.members.create({ email: 'user@example.com', tier: 'basic' });
const payment = await membersOnly.payments.create({ type: 'sponsorship', amount: 10000, currency: 'KRW', memberId: member.id });

curl -X POST https://api.membersonly.fun/v1/members \
  -H "Authorization: Bearer $MONLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","tier":"basic"}'

curl -X POST https://api.membersonly.fun/v1/payments \
  -H "Authorization: Bearer $MONLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"sponsorship","amount":10000,"currency":"KRW","memberId":"mem_xxx"}'

2) 구독 생성과 일시정지/재개

const sub = await membersOnly.subscriptions.create({ memberId: 'mem_123', plan: 'pro_monthly' });
await membersOnly.subscriptions.pause(sub.id);
await membersOnly.subscriptions.resume(sub.id);

Changelog

v0.1.0 — 초기 공개 베타 문서.