포트원 API 이용하기

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

Deprecated

이 문서는 더 이상 관리되지 않습니다.

PortOne 개발자센터를 이용해주세요.

고객 카드정보를 이용하여 포트원 빌링키 발급 API를 요청하면 포트원 서버가 PG사를 통해 빌링키를 발급받습니다.

이 과정에서 카드정보는 포트원 서버에 기록되지 않습니다.

API를 통한 빌링키 발급의 장점

가맹점이 원하는 형태의 화면으로 카드정보 입력란을 커스터마이징할 수 있습니다. 가맹점 UI/UX 친화적인 결제 환경을 계획하고 계시다면 API 연동 개발을 선택하시면 됩니다.

API를 통한 빌링키 발급의 단점

개인정보 이용약관을 명시해야 하며 PG사 및 카드사 심사가 까다롭고 개인정보 유출에 유의해야 합니다.

1. 빌링키 발급 API 구현하기 (서버)

예시를 위해 경로가 /billing-keys인 빌링키 발급 API를 구현합니다.

이 API는 내부적으로 포트원의 빌링키 발급 API를 호출하며, API 호출을 위해 인증이 필요하므로 서버에서 구현되어야 합니다.

Express.js

// bodyParser 등을 통해 body의 Content-Type에 맞게 데이터를 파싱할 수 있는지 확인해주세요.
// 아래의 카드 정보 입력하기의 방법에 따라 요청으로 오는 Content-Type이 다를 수 있습니다.
// POST 요청을 받는 /billing-keys
app.post("/billing-keys", async (req, res) => {
  try {
    // 카드를 통한 빌링키 발급을 위한 정보들이 오기를 기대합니다.
    // 자세한 필요한 정보는 빌링키 발급 API를 참고해주세요.
    const {
      customer_id,
      card_number,
      expiry_month,
      expiry_year,
      birth_or_business_registration_number,
      password_two_digits,
    } = req.body;

    // 1. 포트원 API를 사용하기 위한 액세스 토큰 발급 받기
    const signinResponse = await axios({
      url: "https://api.portone.io/v2/signin/api-key",
      method: "post",
      headers: { "Content-Type": "application/json" },
      data: {
        api_key: PORTONE_API_KEY, // 포트원 API Key
      },
    });
    const { access_token } = signinResponse.data;
    
    // 2. 포트원 빌링키 발급 API 호출
    const issueResponse = await axios({
      url: "https://api.portone.io/v2/billing-keys",
      method: "post",
      // 1번에서 발급받은 액세스 토큰을 Bearer 형식에 맞게 넣어주세요.
      headers: { "Authorization": "Bearer " + access_token },
      data: {
        customer: {
          customer_id,
        },
        payment_method_option: {
          card: {
            card_credential: {
              card_number,
              expiry_month,
              expiry_year,
              birth_or_business_registration_number,
              password_two_digits
            },
          },
        },
      }
    });

    const { customer_id, billing_key } = issueResponse.data;
    // 빌링키가 발급되었습니다! 빌링키를 저장하거나 결제하는 로직을 구성하세요.
  } catch (e) {
    // 빌링키 발급에 실패했습니다.
    res.status(400).send(e);
  }
});

2. 카드 정보 입력받기

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

• 카드번호

• 유효기간(년/월)

• 생년월일 혹은 사업자번호 (법인카드)

• 비밀번호 앞 두자리

결제하기 버튼 클릭 시 입력 값들로 /billing-keys에 대해 POST요청이 호출되는 예제입니다.

카드 정보를 입력하는 필드들을 다음과 같이 작성합니다. 법인카드(개인명의로 발급된 기명카드 제외)의 경우 birthOrBusinessRegistrationNumber 파라미터에 사업자번호 10자리를 입력하시면 됩니다.

React.js

function CardForm(props) {
  const [state, setState] = useState({
    card_number: '',
    expiry_month: '',
    expiry_year: '',
    birth_or_business_registration_number: '',
    password_two_digits: '',
    customer_id: 'CUSTOMER_ID_HERE',
  });
  function handleInputChange(event) {
    const { value, name } = event.target;
    this.setState({
      [name]: value,
    });
  }
  function handleFormSubmit(event) {
    event.preventDefault();
    axios({
      // 1. 빌링키 발급 API 구현하기에서 구현한 URL을 제공해주세요.
      url: MY_SERVER_URL + "/issue-billing",
      method: "post",
      data: { ...state },
    }).then(response => {
      // 구현하신 빌링키 발급 API 응답 대로 결과를 처리하세요!
    });
  }
  return (
    <form onSubmit={handleFormSubmit}>
      <label>
        카드 번호
        <input type="text" name="card_number" value={state.card_number} onChange={handleInputChange} />
      </label>
      <label>
        카드 유효기간(년)
        <input type="text" name="expiry_year" value={state.expiry_year} onChange={handleInputChange} />
      </label>
      <label>
        카드 유효기간(월)
        <input type="text" name="expiry_month" value={state.expiry_month} onChange={handleInputChange} />
      </label>
      <label>
        생년월일 혹은 사업자번호(
        <input type="text" name="birth_or_business_registration_number" value={state.birth_or_business_registration_number} onChange={handleInputChange} />
      </label>
      <label>
        카드 비밀번호 앞 두자리
        <input type="text" name="password_two_digits" value={state.password_two_digits} onChange={handleInputChange} />
      </label>
      <input type="submit" value="결제하기" />
    </form>
  );
}

HTML

<!-- 1. 빌링키 발급 API 구현하기에서 구현한 URL을 제공해주세요. -→
<form action="https://MY-SERVER-URL/billing-keys", method="post">
  <label>
    카드 번호
    <input type="text" name="card_number">
  </label>
  <label>
    카드 유효기간(년)
    <input type="text" name="expiry_year">
  </label>
  <label>
    카드 유효기간(월)
    <input type="text" name="expiry_month">
  </label>
  <label>
    생년월일 혹은 사업자번호(법인카드)
    <input type="text" name="birth_or_business_registration_number">
  </label>
  <label>
    카드 비밀번호 앞 두자리
    <input type="text" name="password_two_digits">
  </label>
  <input hidden type="text" value="CUSTOMER_ID_HERE" name="customer_id">
  <input type="submit" value="결제하기">
</form>