LifeOS Payment API

LifeOS 결제 시스템 REST API. 결제 생성, 조회, 환불, 웹훅 관리를 지원합니다.

https://api.lifeos.dev/v2 v2.1

🔐 인증 (Authentication)

모든 요청에 API 키를 포함해야 합니다. 테스트 키(sk_test_)와 라이브 키(sk_live_)를 구분하세요.

Authorization: Bearer sk_live_xxxxx 
curl -H 'Authorization: Bearer sk_test_abcd1234' https://api.lifeos.dev/v2/payments

📡 Endpoints

GET https://api.lifeos.dev/v2/payments Status 200

결제 목록 조회

생성된 결제 목록을 페이지네이션으로 조회합니다.

ParameterTypeRequiredDescription
limitintegeroptional반환할 최대 개수 (기본 10, 최대 100)
statusstringoptional필터: pending, completed, refunded
created_afterstringoptionalISO 8601 날짜 이후 필터

Response

{
  "data": [
    {
      "id": "pay_abc123",
      "amount": 29900,
      "currency": "KRW",
      "status": "completed",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "has_more": true,
  "total": 142
}
POST https://api.lifeos.dev/v2/payments Status 201

결제 생성

새로운 결제를 생성합니다. 결제 수단과 금액을 지정하세요.

ParameterTypeRequiredDescription
amountintegerrequired결제 금액 (원)
currencystringrequired통화 코드 (KRW, USD)
methodstringrequired결제 수단: card, bank, kakao
descriptionstringoptional결제 설명
metadataobjectoptional커스텀 메타데이터

Response

{
  "id": "pay_new456",
  "amount": 29900,
  "currency": "KRW",
  "status": "pending",
  "checkout_url": "https://pay.lifeos.dev/checkout/pay_new456"
}
GET https://api.lifeos.dev/v2/payments/{id} Status 200

결제 상세 조회

결제 ID로 상세 정보를 조회합니다.

ParameterTypeRequiredDescription
idstringrequired결제 ID (path parameter)

Response

{
  "id": "pay_abc123",
  "amount": 29900,
  "currency": "KRW",
  "status": "completed",
  "method": "card",
  "card": {
    "last4": "4242",
    "brand": "visa"
  },
  "refundable": true
}
POST https://api.lifeos.dev/v2/payments/{id}/refund Status 200

결제 환불

완료된 결제를 환불합니다. 부분 환불도 가능합니다.

ParameterTypeRequiredDescription
idstringrequired결제 ID (path parameter)
amountintegeroptional부분 환불 금액 (미지정시 전액)
reasonstringoptional환불 사유

Response

{
  "id": "ref_xyz789",
  "payment_id": "pay_abc123",
  "amount": 29900,
  "status": "completed",
  "reason": "고객 요청"
}
GET https://api.lifeos.dev/v2/webhooks Status 200

웹훅 목록

등록된 웹훅 엔드포인트 목록을 조회합니다.

Response

{
  "data": [
    {
      "id": "wh_001",
      "url": "https://your-app.com/webhook",
      "events": ["payment.completed", "refund.created"],
      "active": true
    }
  ]
}
POST https://api.lifeos.dev/v2/webhooks Status 201

웹훅 등록

새 웹훅 엔드포인트를 등록합니다.

ParameterTypeRequiredDescription
urlstringrequired웹훅 수신 URL
eventsarrayrequired구독할 이벤트 타입 배열

Response

{
  "id": "wh_new002",
  "url": "https://your-app.com/webhook",
  "secret": "whsec_abcdef123456",
  "events": ["payment.completed"]
}

⚠️ Error Codes

CodeNameDescription
400Bad Request필수 파라미터 누락 또는 잘못된 형식
401Unauthorized유효하지 않은 API 키
404Not Found요청한 리소스를 찾을 수 없음
409Conflict이미 처리된 요청 (중복 결제 등)
429Rate Limited요청 한도 초과 (100req/min)
500Server Error서버 내부 오류. 재시도하세요

📦 SDK & Code Examples

$ pip install lifeos-sdk

from lifeos import LifeOS

client = LifeOS(api_key='sk_test_xxx')
payment = client.payments.create(
    amount=29900,
    currency='KRW',
    method='card'
)
print(payment.checkout_url)

$ npm install lifeos-sdk

const LifeOS = require('lifeos-sdk');

const client = new LifeOS('sk_test_xxx');
const payment = await client.payments.create({
  amount: 29900,
  currency: 'KRW',
  method: 'card'
});
console.log(payment.checkout_url);
curl -X POST https://api.lifeos.dev/v2/payments \
  -H 'Authorization: Bearer sk_test_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"amount": 29900, "currency": "KRW", "method": "card"}'

📋 Changelog

v2.12024-01-15
  • 부분 환불 지원
  • 웹훅 재시도 로직 추가
  • rate limit 100 → 200 req/min
v2.02023-11-01
  • REST API v2 출시
  • 카카오페이 연동
  • SDK Python/Node.js 공개
v1.02023-06-01
  • 최초 출시
  • 카드 결제 지원