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>

client-side
// React.js
  class CardForm extends React.Components {
    constructor(props) {
      super(props);
      this.state = {
        cardNumber: "",
        expiry: "",
        birth: "",
        pwd2Digit: "",
        customer_uid: "gildong_0001_1234",
      };
    }
    ...
    handleInputChange = (event) => {
      const { value, name } = event.target;
      this.setState({
        [name]: value,
      });
    };
    ...
    handleFormSubmit = (event) => {
      event.preventDefault();
      const { cardNumber, expiry, birth, pwd2Digit, customer_uid } = this.state;
      axios({
        // 예: https://www.myservice.com/subscription/issue-billing
        url: "{빌링키 발급 요청을 받을 서비스 URL}", 
        method: "post",
        data: {
          cardNumber,
          expiry,
          birth,
          pwd2Digit,
          customer_uid,
        }
      }).then(rsp => {
        ...
      });
    };
    ...
    render() {
      const { cardNumber, expiry, birth, pwd2Digit } = this.state;
      return (
        <form onSubmit={this.handleFormSubmit}>
          <label>
            카드 번호
            <input type="text" name="cardNumber" value={cardNumber} onChange={this.handleInputChange} />
          </label>
          <label>
            카드 유효기간
            <input type="text" name="expiry" value={expiry} onChange={this.handleInputChange} />
          </label>
          <label>
            생년월일
            <input type="text" name="birth" value={birth} onChange={this.handleInputChange} />
          </label>
          <label>
            카드 비밀번호 앞 두자리
            <input type="text" name="pwd2Digit" value={pwd2Digit} onChange={this.handleInputChange} />
          </label>
          <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정보를 예약합니다.(카드정보 필수사항)