결제 생성하기
결제 API를 사용하면 다양한 결제 수단을 통해 안전하게 결제를 처리할 수 있습니다. 신용카드, 가상계좌, 간편결제(카카오페이, 네이버페이) 등을 지원하며, 자동 재시도 및 3DS 인증이 내장되어 있습니다.
결제 생성 API는 멱등성(Idempotency)을 지원합니다.
Idempotency-Key 헤더를 사용하여 중복 결제를 방지하세요.
요청
결제를 생성하려면 다음 엔드포인트로 POST 요청을 보내세요.
Node.js
Python
cURL
import { PayClient } from '@paydocs/sdk'; const client = new PayClient({ apiKey: process.env.PAYDOCS_SECRET_KEY, }); // 결제 생성 const payment = await client.payments.create({ amount: 50000, currency: 'KRW', orderId: 'order_2024_abc123', orderName: '오버핏 캐시미어 블렌드 코트', customer: { id: 'cust_8xkR2mN', email: 'user@example.com', name: '김지수', }, paymentMethod: 'card', metadata: { productId: 'prod_coat_001', }, }); console.log(payment.id); // pay_7Hs9mK3...
파라미터
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
amount |
integer |
필수 | 결제 금액 (원 단위). 최소 100원, 최대 50,000,000원. |
currency |
string |
필수 | 통화 코드. ISO 4217 형식. 예: KRW, USD |
orderId |
string |
필수 | 가맹점 주문 ID. 고유해야 하며 6~64자 영숫자, 하이픈, 언더스코어 허용. |
orderName |
string |
필수 | 결제 페이지에 표시될 주문명. 최대 100자. |
customer |
object |
선택 | 고객 정보 객체. id, email, name 필드 포함. |
paymentMethod |
enum |
선택 | card · virtualAccount · kakaopay · naverpay |
metadata |
object |
선택 | 임의의 키-값 데이터. API 응답 및 웹훅에 그대로 전달됨. |
응답
성공 시 HTTP 200과 함께 결제 객체를 반환합니다.
응답 JSON
{ "id": "pay_7Hs9mK3QpL2xR8vN", "object": "payment", "status": "DONE", "amount": 50000, "currency": "KRW", "orderId": "order_2024_abc123", "orderName": "오버핏 캐시미어 블렌드 코트", "method": "카드", "card": { "issuerCode": "11", "acquirerCode": "11", "number": "54**-****-****-2014", "installmentPlanMonths": 0, "approveNo": "00100328" }, "approvedAt": "2024-03-15T14:22:31+09:00", "metadata": { "productId": "prod_coat_001" } }
오류 처리
API는 표준 HTTP 상태 코드와 함께 구조화된 오류 응답을 반환합니다. 모든 오류는 code와 message 필드를 포함합니다.
카드사 오류(4xx)는 즉시 사용자에게 안내하세요. 5xx 오류는 지수 백오프로 최대 3회 재시도를 권장합니다.
INVALID_CARD_NUMBER
카드 번호가 올바르지 않습니다. 형식을 확인하세요.
INSUFFICIENT_FUNDS
카드 잔액이 부족합니다. 다른 결제 수단을 사용하세요.
EXPIRED_CARD
카드 유효기간이 만료되었습니다.
PAYMENT_LIMIT_EXCEEDED
결제 한도를 초과했습니다. 일일 한도를 확인하세요.