본문으로 건너뛰기

URL 인코딩 (Percent Encoding)

URL 인코딩이란, URL(인터넷 주소)에서 사용할 수 없는 문자(한글, 공백, 특수문자 등)를 인터넷 전송이 가능한 ASCII 문자열(%XX 형태) 로 변환하는 것을 말합니다. 정식 명칭은 퍼센트 인코딩(Percent Encoding) 입니다.

결제 시스템 연동 시 상품명, 구매자명(한글) 을 전송하거나, 결제 결과 메시지를 수신할 때 데이터가 깨지지 않게 하려면 필수적으로 이해해야 합니다.

🔄 변환 원리 (Mechanism)​

웹 브라우저는 URL에 영문자와 숫자, 일부 기호만 허용합니다. 허용되지 않은 문자는 UTF-8 바이트 코드로 변환된 후, 각 바이트 앞에 %를 붙여 표현됩니다.

예시: 휴대폰 (한글) $\to$ %ED%9C%B4%EB%8C%80%ED%8F%B0

💡 결제 연동 시 주의사항​

1. 요청할 때 (Encoding)​

GET 방식의 쿼리 스트링이나 리다이렉트 URL을 만들 때, 한글 데이터는 반드시 인코딩해서 보내야 합니다.

  • 대상: goodsName(상품명), buyerName(구매자명), mallName(가맹점명) 등
  • 증상: 인코딩 없이 보내면 수신 측에서 문자가 깨지거나(???), 요청 자체가 거절될 수 있습니다.

2. 받을 때 (Decoding)​

PG사로부터 결제 결과(Return URL)를 받을 때, 한글 메시지는 인코딩된 상태로 들어올 수 있습니다.

  • 대상: resMsg(결제 결과 메시지), authMsg(승인 메시지)
  • 해결: 반드시 URL Decoding 함수를 사용하여 원래의 한글로 복원해야 합니다.

💻 언어별 함수 예제​

대부분의 언어는 표준 라이브러리로 인코딩/디코딩을 지원합니다. UTF-8 캐릭터셋 사용을 권장합니다.

JavaScript (Browser/Node.js)​

const text = "테스트 상품";

// 인코딩 (Encode)
const encoded = encodeURIComponent(text);
console.log(encoded); // "%ED%85%8C%EC%8A%A4%ED%8A%B8%20%EC%83%81%ED%92%88"

// 디코딩 (Decode)
const decoded = decodeURIComponent(encoded);
console.log(decoded); // "테스트 상품"

Java​

import java.net.URLEncoder;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;

String text = "테스트 상품";

// 인코딩
String encoded = URLEncoder.encode(text, StandardCharsets.UTF_8);

// 디코딩
String decoded = URLDecoder.decode(encoded, StandardCharsets.UTF_8);

Python​

from urllib.parse import quote, unquote

text = "테스트 상품"

# 인코딩
encoded = quote(text)

# 디코딩
decoded = unquote(encoded)