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정보를 예약합니다.(카드정보 필수사항)