Sandbox

관련 문서: README · 인증

#사용 시작

1. 먼저 CardV의 사업자 심사 승인을 받아야 합니다.
2. 포털에 로그인한 뒤 상단에서 Sandbox를 선택합니다. Sandbox에 바로 로그인하는 방법은 없습니다.
3. 처음 전환하면 CardV가 Sandbox 계정을 만들어 줍니다. Merchant ID는 Live와 같고, 테스트 머니 1,000 USD가 들어 있습니다.
4. Sandbox에서 Owner가 Sandbox API 키를 만들고 확인합니다. Live 키는 여기서 쓸 수 없습니다.
5. 필요하면 Sandbox Webhook을 설정합니다. 서명 시크릿은 Live와 별개입니다.

#분리되는 항목

• Sandbox에는 API 키, 지갑, 주문, Webhook, IP 허용 목록, 감사 로그가 따로 있습니다.
• 설정은 공유되지 않습니다. API 키, Webhook, IP 허용 목록은 환경마다 따로 설정하세요.
• Sandbox 주문으로는 실제 상품을 구매하지 않습니다. 테스트 코드는 사용할 수 없습니다.
• 테스트 머니는 가치가 없습니다. Sandbox에서는 충전, 출금, Live로의 이전이 모두 불가능합니다.
• 테스트 머니가 부족하면 CardV 고객지원에 추가를 요청하세요.

#테스트 머니

주문에는 Live의 실제 돈과 똑같은 방식으로 테스트 머니가 쓰입니다. 실패한 테스트 주문도 같은 방식으로 환불됩니다. 테스트 머니의 입출금 내역은 포털의 거래 내역 화면에서 볼 수 있습니다.

#테스트 상품

• Sandbox 상품 목록은 규모가 작고 테스트 상품만 있습니다.
• SKU ID는 Live와 다릅니다. Sandbox에서는 항상 GET/skus로 조회하세요.
• Sandbox ID를 Live 설정에 복사하거나, 반대로 Live ID를 Sandbox에 쓰지 마세요.
• 가격, 판매 여부, 발급 속도는 Live와 다릅니다.

#테스트 체크리스트

• GET/account에 귀사의 Merchant ID와 "api_access_enabled": true가 표시된다.
• GET/balance가 정상 동작한다.
• GET/skus를 페이지별로 모두 조회할 수 있고, available인 SKU만 주문한다.
• 서명한 주문이 성공한다. 서명이 틀리면 HTTP 403을 받는다.
• 모든 주문 항목에 expected_unit_price를 보낸다.
• 범위 금액 SKU를 amount와 함께 주문할 수 있다(Sandbox에 해당 상품이 있는 경우).
• 같은 주문을 두 번 보내면(nonce는 새로, 본문과 주문번호는 그대로) HTTP 200과 같은 order_id가 반환되고, 잔액은 한 번만 차감된다.
• 같은 주문번호에 다른 본문을 보내면 external_order_id에 대한 HTTP 400을 받는다.
• 타임아웃이 나면 새 주문번호를 만들지 않고 같은 주문을 다시 보낸다.
• deliveries[].display_fields를 읽어 고객에게 전달한다.
• failed, refunded, partially_succeeded를 처리한다.
• Webhook 코드가 테스트 값과실제 Sandbox Webhook 검증을 통과하고, 중복 알림을 무시한다.
• HTTP 429를 받으면 Retry-After만큼 기다린다.
• 로그에 API 키, 서명, 코드, 고객 계정 정보가 남지 않는다.

#서비스 오픈 체크리스트

• Live 포털에서 Live API 키를 만들고, 운영 환경의 시크릿 저장소에 보관한다.
• 설정의 기본 URL을 https://b2b.cardv.net/api/v1로 바꾼다.
• Live 상품 목록을 불러와 귀사 상품을 Live SKU ID와 연결한다.
• 포털에서 Live 지갑을 충전하고, 잔액 부족 알림을 설정한다.
• 필요하면 서버 IP를 Live IP 허용 목록에 등록한다.
• Live Webhook을 설정하고 서명 시크릿을 배포한다.
• 주문 한도와 요청 한도를 CardV와 확인한다.
• 소액 Live 주문을 1건 넣어 결제 금액, 코드, Webhook을 확인한다. 그다음 거래량을 단계적으로 늘린다.
• 포털의 거래 내역과 내보내기 파일로 매일 대사한다.
• 모든 Owner 계정에 2단계 인증을 켠다.

#문제 해결

HTTP 403 error code: 1010

Sandbox 서버 앞에는 네트워크 보안 서비스가 있습니다. 일부 HTTP 클라이언트는 이 서비스에서 error code: 1010이라는 일반 텍스트와 함께 HTTP 403을 받습니다. 요청이 CardV까지 도달하지 않은 것이므로API 키나 서명을 바꿔도 해결되지 않습니다.

• 알아보기 쉬운 User-Agent를 지정하세요.
• 계속 발생하면 서버 IP, User-Agent, 발생 시각을 CardV 고객지원에 보내 주세요.
• 대신 Live에서 테스트하는 일은 절대 하지 마세요.