개발자/생태계 및 리소스

Dujiao-Next용 CardV

Dujiao-Next 스토어에 CardV를 공급처로 추가하세요. CardV 기프트카드와 게임 충전 상품을 내 상품으로 가져오고 가격은 직접 정합니다. 구매자가 결제하면 스토어가 CardV 잔액으로 CardV에서 상품을 구매하고, 코드가 구매자의 주문 페이지에 자동으로 표시됩니다.

API 키 받기 ↗

#준비 사항


Dujiao-Next	업스트림 연결 기능(Integration 메뉴)이 있는 v1.5.0 이상
CardV 계정	API 접근이 활성화된 승인된 가맹점 계정
API 키	가맹점 포털에서 발급한 서명 API 키(키 ID + 서명 시크릿)
잔액	USD 기준 CardV 선불 잔액. 스토어가 넣는 모든 주문은 여기서 결제됨

구매자에 대한 판매자는 귀하입니다. 가격을 정하고, 구매자 문의에 답하고, 환불을 처리합니다.

#1단계: API 키 받기

가맹점 포털의 API 및 웹훅 > API 키에 있는 기존 API 키를 사용합니다. Dujiao-Next용 키를 따로 만들 필요는 없습니다.

키 ID는 ck_live_로 시작합니다.
서명 시크릿은 cs_live_로 시작합니다. 키를 만들 때 한 번만 표시됩니다. 더 이상 가지고 있지 않다면 해당 키에서 시크릿 재발급을 사용하세요. 키 ID는 그대로이며, 이전 시크릿은 즉시 작동하지 않습니다.

키 ID가 없는 이전 키는 사용할 수 없습니다. 대신 포털에서 새 키를 만드세요.

가맹점 포털의 API 키 페이지(키 ID는 흐리게 처리)

#2단계: 연결 추가

Dujiao-Next 관리자 화면에서 Integration > Connection Management > New Connection을 열고 양식을 작성합니다.

항목	입력할 내용	이유
Name	예: `CardV (USD)`	본인에게만 보입니다. 통화를 넣어 두면 나중에 헷갈리지 않습니다
Base URL	`https://b2b.cardv.net/dujiao`	`/dujiao`까지 포함하고 그 뒤에는 아무것도 붙이지 않으며, 끝에 슬래시도 넣지 않습니다
API Key	키 ID(`ck_live_…`)
API Secret	서명 시크릿(`cs_live_…`)	나중에 연결을 수정할 때 비워 두면 저장된 시크릿이 유지됩니다
Protocol	`dujiao-next`
Callback URL	비워 둠	CardV는 콜백을 보내지 않습니다. 스토어가 각 주문의 결과를 확인합니다(전달 방식 참고)
Max Retries / Retry Intervals	기본값 유지(`3` / `30,60,120`)	재시도는 일시적인 오류에만 적용됩니다
Exchange Rate	직접 입력하는 고정 숫자입니다. USD에서 스토어 통화로의 오늘 실제 환율을 확인하고, 여유분으로 조금 높게 설정합니다. 스토어가 USD로 판매한다면 `1`을 입력합니다	CardV 가격은 항상 USD입니다. Dujiao-Next는 실시간 환율을 가져오지 않으며, CardV가 이 값을 대신 설정할 수도 없습니다. 기본값이 `1`이므로 다른 통화로 판매하는 스토어에서는 10 USD 카드가 자국 통화 10으로 표시됩니다
Price Markup (%)	마진. 예: `15`	기본값은 `0`이며, 이는 이익이 없다는 뜻입니다
Price Rounding	Round up (0.1) 또는 Round up (integer)	올림을 하면 판매 가격이 원가보다 낮아지지 않습니다
Auto-update price on sync	Yes	CardV 가격이 바뀌면 다음 동기화 때 판매 가격이 다시 계산됩니다

환율과 마크업은 다음과 같이 계산됩니다: CardV 가격 × 환율 × (1 + 마크업)을 구한 뒤 Price Rounding 설정에 따라 반올림합니다. 예를 들어 환율을 7.2(예시일 뿐이며, 직접 확인한 현재 환율을 입력하세요), 마크업을 15%로 가정하면 5.78 USD 카드는 47.9에 판매됩니다.

Base URL, 환율, 마크업을 입력한 새 연결 양식(7.2 환율과 15% 마크업은 예시 값)

환율이 바뀌면 연결의 환율을 업데이트하고 Reapply Markup을 클릭해 이미 가져온 상품의 가격을 업데이트합니다. 마크업을 바꿀 때도 똑같이 합니다.

#3단계: 연결 테스트

연결에서 Ping을 클릭합니다. Ping succeeded가 표시되면 키가 정상적으로 작동하는 것이며, 연결 상태가 Active로 바뀝니다. 오류가 표시되면 문제 해결을 참고하세요.

Ping 성공, 연결 활성

#4단계: 상품 가져오기

Integration > Product Mappings > Import from Upstream을 열고 CardV 연결을 선택합니다.
카테고리별로 둘러보거나 Flat List로 전환해 개별 상품을 고릅니다.
로컬 카테고리를 선택하거나 Auto-create local categories에 체크합니다. 상품을 저장하려면 카테고리가 있어야 합니다.
가져옵니다. 각 상품의 제목, 설명, 사용 방법, 액면가(10 USD 등)가 그대로 유지됩니다.

업스트림에서 가져오기, 카테고리별 둘러보기

가져온 상품은 판매 중지 상태입니다. 하나씩 확인한 뒤 상품 편집기에서 Active를 켜세요.

마크업이 적용된 판매 가격이 표시된 상품 매핑

#5단계: 주문당 1개로 설정

가져온 모든 상품에 대해 상품 편집기를 열고 Max purchase quantity를 1로 설정합니다.

CardV는 주문당 1개를 전달합니다. 구매자가 한 주문에서 코드 2개를 결제하면 CardV는 구매를 거절하며, 그 주문은 직접 처리해야 합니다. Dujiao-Next는 이 제한을 CardV에서 자동으로 받아 오지 못하므로 직접 설정하세요.

편집기를 연 김에 다음도 권장합니다.

스토어 재고 표시: Hide quantity를 선택합니다. CardV는 주문이 들어올 때 브랜드에서 구매하므로, 스토어에 표시되는 재고 숫자는 "구매 가능"이라는 의미일 뿐입니다.
이미지: 이미지가 없는 상품에는 직접 추가합니다.

최대 구매 수량을 1로 설정한 상품 편집기

#전달 방식

구매자가 스토어에서 결제합니다.
스토어가 구매를 CardV로 보내고, CardV가 CardV 잔액에서 대금을 차감합니다.
스토어가 CardV에서 주문을 확인합니다. 저희 테스트에서는 코드가 1분 이내에 도착했습니다.
코드는 구매자의 주문 페이지에 Code, PIN(카드에 있는 경우), Expires(카드에 만료일이 있는 경우)로 표시됩니다. 항상 코드이며 링크로 전달되지 않습니다.

직접 충전. 일부 상품은 구매자의 게임 또는 앱 계정에 바로 충전됩니다. 구매자는 결제할 때 플레이어 ID나 전화번호 등 상품에 필요한 정보를 입력합니다. 충전이 완료되면 구매자의 주문 페이지에 Top-up completed.가 표시됩니다.

CardV가 전달할 수 없는 경우. CardV는 주문 금액을 CardV 잔액으로 환불하고, 스토어는 해당 구매를 취소됨으로 표시합니다. 그런 다음 스토어에서 구매자에게 환불하거나 도움을 제공하세요.

직접 충전할 계정 정보를 입력하는 구매자

구매자의 주문 페이지에 전달된 코드(여기서는 흐리게 처리)

#제공되지 않는 상품

가져오기 목록에는 이 연결을 통해 스토어에서 판매할 수 있는 상품만 표시됩니다.

고정 금액만. 구매자가 금액을 직접 입력하는 카드는 표시되지 않습니다.
표시되지 않음: 휴대폰 통화 충전, 결제 및 지갑 상품, 암호화폐, 선불 결제 카드.
코드만. 링크로만 전달할 수 있는 상품은 표시되지 않습니다.

표시되는 가격은 USD 기준 귀하의 CardV 가격입니다.

#IP 화이트리스트

가맹점 포털에서 IP 화이트리스트를 설정했다면 Dujiao-Next 스토어를 실행하는 서버의 공인 IP 주소를 추가하세요. 그렇지 않으면 CardV는 해당 서버의 모든 요청을 거절합니다. CardV API와 Dujiao-Next에는 같은 키, 화이트리스트, 요청 한도가 적용됩니다.

#문제 해결

이 메시지는 Dujiao-Next 관리자 화면에서 Ping 후, 가져오기 중, 또는 Procurement Orders의 구매 건에 표시됩니다.

메시지	원인	해결 방법
`status 401 (invalid_signature): signature verification failed`	API Secret이 틀렸거나 포털에서 재발급함	현재 서명 시크릿을 연결에 복사합니다
`status 403 (invalid_api_key): api key is invalid or disabled`	API Key가 키 ID(`ck_live_…`)가 아니거나 키가 비활성화됨	활성 키의 키 ID를 사용합니다
`status 403 (user_disabled): merchant API access is not enabled`	계정이 아직 API 접근 승인을 받지 않음	포털에서 사업자 심사를 완료합니다
`status 403 (forbidden): source IP is not allowed for this merchant`	IP 화이트리스트에 스토어 서버가 없음	포털에서 서버의 공인 IP 주소를 추가합니다
`status 401 (timestamp_expired): timestamp expired`	서버 시계가 60초 넘게 어긋남	서버에서 자동 시간 동기화(NTP)를 켭니다
`status 404` 뒤에 웹 페이지가 표시됨	Base URL이 틀림. 대개 `/dujiao`가 빠짐	`https://b2b.cardv.net/dujiao`를 사용합니다
`CardV wallet balance is insufficient`	CardV 잔액이 구매 금액에 부족함. 구매자의 주문은 결제 완료 상태로 남음	CardV 잔액을 충전한 뒤 Procurement Orders에서 해당 구매의 Retry를 클릭합니다
`quantity must be 1: CardV accepts one item per order`	구매자가 한 상품을 2개 이상 주문함	Max purchase quantity를 `1`로 설정하고(5단계), 해당 주문은 직접 처리합니다
`sku is invalid or not available`	해당 상품을 CardV에서 더 이상 제공하지 않음	매핑에서 동기화를 실행합니다. CardV가 더 이상 제공하지 않는 상품은 판매 중지됩니다
`status 429 (rate_limited)`	1분 동안 요청이 너무 많음	스토어가 자동으로 재시도합니다. 계속 발생하면 동기화 빈도를 낮추세요

#자주 묻는 질문

Dujiao-Next용 새 API 키가 필요한가요? 아니요. 이미 가지고 있는 서명 API 키를 사용하세요. 같은 키를 직접 구축한 CardV API 연동에도 사용한다면 둘이 같은 요청 한도를 공유합니다.

콜백 URL은 왜 비워 두나요? CardV는 스토어에 콜백을 보내지 않습니다. Dujiao-Next 스토어가 결과가 확정될 때까지 각 주문을 직접 확인합니다.

CardV 가격이 바뀌면 어떻게 되나요? Auto-update price on sync가 켜져 있으면 다음 동기화 때 귀하의 환율과 마크업으로 판매 가격이 다시 계산됩니다. 꺼져 있으면 스토어는 이전 가격으로 계속 판매합니다.

CardV에서 이 주문은 어디서 확인하나요? 가맹점 포털의 주문 페이지에서 확인합니다. 내 주문 ID 열은 dujiao:로 시작하고 그 뒤에 Dujiao-Next 하위 주문 번호가 붙습니다(예: dujiao:DJ…-01). CardV 웹훅을 설정했다면 이 주문에도 웹훅이 전송됩니다.

가맹점 포털에 표시된 Dujiao-Next 주문(금액은 흐리게 처리)

상품 제목, 설명, 이미지를 바꿀 수 있나요? 네. 동기화는 가격과 판매 가능 여부를 업데이트합니다. 제목이나 이미지는 덮어쓰지 않습니다.

자유 금액을 판매할 수 있나요? 아직 Dujiao-Next에서는 할 수 없습니다. 고정 금액만 제공됩니다.

#지원

Merchant ID, Dujiao-Next 주문 번호, 오류 메시지를 적어 [email protected]으로 이메일을 보내 주세요. CardV 이용에는 이용약관이 적용됩니다.

연동 관련 문의는 Merchant ID와 주문 ID 또는 요청 ID를 포함해 [email protected]로 보내 주세요.