CardV Merchant API

#문서 목록

#환경

Sandbox는 테스트 머니로 움직이는 별도의 CardV 테스트 환경입니다. API 키, 잔액, 주문, 상품 ID는 환경마다 모두 다릅니다.

#빠른 시작

1. 가입을 신청합니다. 포털에서 가맹점 계정을 신청하고 이메일 인증을 마칩니다.

2. 승인을 기다립니다. CardV가 사업자 정보를 확인한 뒤 Merchant ID(가맹점 ID)를 발급합니다. 예: M00000001

3. Sandbox를 엽니다. 포털에 로그인한 뒤 상단에서 Sandbox를 선택합니다. 테스트 머니 1,000 USD가 지급됩니다.

4. API 키를 만듭니다. 포털의 Integrations → API keys 메뉴로 이동합니다. 키를 만든 뒤, CardV가 이메일로 보내는 인증 코드를 입력해 키를 확인합니다. 확인한 키는 시크릿 저장소에 보관합니다.

5. 잔액을 확인합니다.

   ShellCopy

   export CARDV_BASE=https://sandbox.cardv.net
   export CARDV_MERCHANT_ID=M00000001     # yours
   export CARDV_API_KEY=cvb2b_...         # from your secret store
   AUTH=(-H "X-Merchant-Id: $CARDV_MERCHANT_ID" -H "X-Api-Key: $CARDV_API_KEY")
   
   curl -sS "$CARDV_BASE/api/v1/balance" "${AUTH[@]}"

6. 상품을 찾습니다.

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus?search=steam&limit=20" "${AUTH[@]}"

   "availability": "available"인 상품을 하나 골라 sku_id를 적어 둡니다.

7. 가격을 조회합니다.

   ShellCopy

   curl -sS "$CARDV_BASE/api/v1/skus/S000001/quote?quantity=1" "${AUTH[@]}"

   merchant_price를 확인합니다. 한 개당 실제로 결제할 금액입니다.

8. 주문합니다. 주문 요청에는 서명이 필요합니다. 인증 문서의 예제 코드에 아래 본문을 넣어 보내세요.

   JSONCopy

   {
     "external_order_id": "TEST-0001",
     "items": [
       {"sku_id": "S000001", "quantity": 1, "expected_unit_price": "9.2500"}
     ]
   }

   성공하면 HTTP 201과 함께 O-00001234 같은 CardV 주문 ID를 받습니다.

9. 코드를 받습니다. 상태가 succeeded가 될 때까지 GET/api/v1/orders/O-00001234를 호출합니다. 코드는 items[].deliveries[].display_fields에 들어 있습니다. 주문이 끝났을 때 Webhook으로 알림을 받을 수도 있습니다.

10. Sandbox 체크리스트를 모두 통과하면 Live로 전환합니다.

위의 ID와 가격은 예시입니다. 실제로는 귀사 계정에서 조회되는 값을 사용하세요.

#API 한눈에 보기

엔드포인트는 모두 7개이며, 경로는 /api/v1로 시작합니다.

그 밖의 엔드포인트를 API 키로 호출하면 HTTP 403이 반환됩니다.

{"detail": "This operation is only available in the Merchant Portal."}

휴대폰 요금 충전(통화 충전)은 API로 제공하지 않습니다.

#ID 종류

ID는 문자열로 저장하고, 형식을 해석하지 마세요. 자세한 내용은 공통 규칙을 참고하세요.

#포털에서 하는 일

• 지갑 충전, 잔액 부족 알림 이메일 설정
• 주문 내역 조회, 검색, CSV 내보내기
• 주문 인보이스
• 지갑 거래 내역과 정산 대사
• Webhook 설정, 발송 내역 확인, 재발송
• API 키 관리
• IP 허용 목록
• 팀원과 역할 관리
• 감사 로그
• 2단계 인증(2FA)
• Live와 Sandbox 전환

#호환성과 문의

응답에 새 필드나 새 상태 값이 예고 없이 추가될 수 있습니다. 모르는 필드는 무시하고, 모르는 주문 상태는 "아직 완료되지 않음"으로 처리하세요. 오류 메시지의 문구에 의존하지 마세요.

문의는 [email protected]으로 보내 주세요. Merchant ID, 환경(Live/Sandbox), 주문 ID, 발생 시각(UTC), HTTP 상태 코드를 함께 적어 주시면 됩니다. API 키, 서명, Webhook 시크릿, 카드 코드는 절대 보내지 마세요.