개발자센터
V1
V2
이 페이지의 다른 버전 보기
파트너 정산 릴리즈 노트 기술 블로그

REST API 이용하기

포트원 REST API 를 이용하여 손쉽게 빌링키를 획득할수 있습니다.

포트원 REST API 를 이용하여 빌링키를 획득하여 결제를 요청할 수 있습니다. 고객 카드정보를 이용하여 빌링키 발급을 요청하면 포트원 서버가 PG사의 API를 호출하여 빌링키를 발급받습니다. 이 과정에서 카드정보는 기록되지 않습니다. 이 방식은 다음과 같은 특징이 있습니다.

  • 장점: 고객사가 원하는 형태의 화면으로 카드정보 입력란을 커스터마이징할 수 있다.
  • 단점: 개인정보 이용약관을 명시해야 하며 PG사 및 카드사 심사가 까다롭고 개인정보 유출에 유의해야 합니다.

고객사 UI/UX 친화적인 결제 환경을 계획하고 계시다면 API 연동 개발을 선택하시면 됩니다.

STEP 01. 카드 정보 입력받기

카드 정보를 입력하는 필드들을 다음과 같이 작성합니다. 요청 시 customer_uid를 저장 할 히든필드를 작성합니다. 법인카드(개인명의로 발급된 기명카드 제외)의 경우 birth 파라미터에 사업자번호 10자리 를 입력하시면 됩니다. 결제하기 버튼 클릭 시 입력 값들과 customer_uid로 /subscription/issue-billing에 대해 POST요청이 호출되는 예제입니다.

customer_uid 란?

PG사가 발급한 빌링키와 1:1로 맵핑되는, 고객사가 지정한 고유한 값입니다. customer_uid는 카드 번호 단위로 구분하여 저장되어야 합니다.

예) 홍길동 고객이 A 카드 빌링키를 요청하는 경우 customer_uid회원별 카드 번호 단위로 고유하게 발급되어야 합니다.

이전 빌링키 발급에 사용된 customer_uid를 재사용하는 경우 가장 마지막 빌링키 발급에 사용된 카드번호의 빌링키로 대체됩니다. (기존에 발급된 빌링키는 자동으로 해지되지 않습니다.)

빌링키 발급을 위한 카드정보

  • 카드번호
  • 유효기간
  • 생년월일
  • 비밀번호 앞 두자리
client-side
<form action="{빌링키 발급 요청을 받을 서비스 URL}" , method="post"> <!--예: https://www.myservice.com/subscription/issue-billing--> <div> <label for="card_number">카드 번호 XXXX-XXXX-XXXX-XXXX</label> <input id="card_number" type="text" name="card_number" /> </div> <div> <label for="expiry">카드 유효기간 YYYY-MM</label> <input id="expiry" type="text" name="expiry" /> </div> <div> <label for="birth">생년월일 YYMMDD</label> <input id="birth" type="text" name="birth" /> </div> <div> <label for="pwd_2digit">카드 비밀번호 앞 두자리 XX</label> <input id="pwd_2digit" type="text" name="pwd_2digit" /> </div> <input hidden type="text" value="gildong_0001_1234" name="customer_uid" /> <input type="submit" value="결제하기" /> </form>

STEP 02. 카드 정보 추출하기

카드 정보를 전달받을 API endpoint를 작성하고 요청에 담긴 카드 정보를 추출합니다./subscription/issue-billing에 대한 POST요청을 처리하는 API endpoint의 예제입니다.

server-side
// "/subscription/issue-billing"에 대한 POST 요청을 처리 app.post("/subscriptions/issue-billing", async (req, res) => { try { const { card_number, // 카드 번호 expiry, // 카드 유효기간 birth, // 생년월일 pwd_2digit, // 카드 비밀번호 앞 두자리, customer_uid, // 카드(빌링키)와 1:1로 대응하는 값 } = req.body; // req의 body에서 카드정보 추출 // ... } catch (e) { res.status(400).send(e); } });

STEP 03. 빌링키 발급 요청 및 응답 처리하기

당사가 제공하는 빌링키 발급 REST API를 통해 빌링키 발급을 요청하고 결과값에 따라 응답을 반환하는 예제입니다.

server-side
// "/subscription/issue-billing"에 대한 POST 요청을 처리 app.post("/subscriptions/issue-billing", async (req, res) => { try { const { card_number, // 카드 번호 expiry, // 카드 유효기간 birth, // 생년월일 pwd_2digit, // 카드 비밀번호 앞 두자리 customer_uid, // 카드(빌링키)와 1:1로 대응하는 값 } = req.body; // req의 body에서 카드정보 추출 // 인증 토큰 발급 받기 const getToken = await axios({ url: "https://api.iamport.kr/users/getToken", method: "post", // POST method headers: { "Content-Type": "application/json" }, data: { imp_key: "imp_apikey", // REST API 키 imp_secret: "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f", }, }); const { access_token } = getToken.data; // 인증 토큰 // 빌링키 발급 요청 const issueBilling = await axios({ url: `https://api.iamport.kr/subscribe/customers/${customer_uid}`, method: "post", // 인증 토큰 Authorization header에 추가 headers: { Authorization: access_token }, data: { card_number, // 카드 번호 expiry, // 카드 유효기간 birth, // 생년월일 pwd_2digit, // 카드 비밀번호 앞 두자리 pg: YOUR_PG_HERE, // 빌링키 발급에 사용할 PG }, }); const { code, message } = issueBilling.data; if (code === 0) { // 빌링키 발급 성공 res.send({ status: "success", message: "Billing has successfully issued", }); } else { // 빌링키 발급 실패 res.send({ status: "failed", message }); } } catch (e) { res.status(400).send(e); } });

REST API 를 이용하기 위해서는 Access Token 획득이 선행되어야 하는점 잊지 마세요

빌링키 발급과 결제 요청을 한번에 하기

예약결제 REST API /subscribe/payments/schedule를 사용하면 등록된 customer_uid가 없는 경우 빌링키 신규 발급을 먼저 진행한 후 schedule정보를 예약합니다.(카드정보 필수사항)