본문으로 건너뛰기

쿼리 스트링 (Query String)

쿼리 스트링(Query String) 이란, 사용자가 웹 프로그램(API)으로 데이터를 전달하기 위해 URL의 끝에 ? 뒤에 덧붙이는 문자열을 말합니다.

결제 연동에서는 주로 정보 조회(GET) API를 호출하거나, 결제가 완료된 후 PG사가 가맹점 페이지로 결과를 돌려줄 때(Return URL) 사용됩니다.

🧬 구조 (Structure)​

URL의 끝에 물음표(?)로 시작하며, 키(Key)=값(Value) 쌍을 앤퍼샌드(&)로 연결하여 여러 데이터를 보냅니다.

예시: https://api.kicc.co.kr/search?date=20231128&status=SUCCESS

💳 결제 연동 활용 사례​

1. Return URL (결제 결과 수신)​

사용자가 결제창에서 인증을 마치면, PG사는 가맹점이 미리 설정한 Return URL로 페이지를 리다이렉트(이동) 시킵니다. 이때 결제 결과가 쿼리 스트링에 담겨 옵니다.

  • 상황: 결제 성공 후 가맹점 페이지 이동
  • 전달되는 URL 예시: https://shop.com/pay/result?resCd=0000&resMsg=Success&authNo=123456
  • 개발자 할 일: 위 URL에서 resCd(응답코드)와 authNo(승인번호)를 추출(Parsing)하여 DB에 저장해야 합니다.

2. 조회 API (GET Request)​

거래 내역이나 정산 내역을 조회할 때 검색 조건을 전달합니다.

  • 요청: GET /api/v1/orders?startDate=20230101&endDate=20230131

⚠️ 주의사항: URL 인코딩 (Encoding)​

쿼리 스트링에는 한글이나 특수문자를 직접 넣을 수 없습니다. 반드시 Percent Encoding (URL Encoding) 처리를 해야 합니다.

  • 문제 상황: ?name=홍길동 (전송 불가)
  • 해결: ?name=%ED%99%8D%EA%B8%B8%EB%8F%99 (인코딩 변환)
개발자 체크포인트

결제 응답 메시지(resMsg)가 한글인 경우(예: "잔액부족"), 인코딩되어 전달될 수 있습니다. 받는 쪽(Server)에서 반드시 URL Decoding을 수행해야 깨지지 않은 한글을 볼 수 있습니다.

💻 언어별 파싱(Parsing) 예제​

URL에서 쿼리 스트링 값을 추출하는 방법입니다.

JavaScript (Browser/Node.js)​

const urlStr = "[https://shop.com/result?resCd=0000&msg=%EC%84%B1%EA%B3%B5](https://shop.com/result?resCd=0000&msg=%EC%84%B1%EA%B3%B5)";
const url = new URL(urlStr);

// 값 추출
const resCd = url.searchParams.get("resCd"); // "0000"
const msg = url.searchParams.get("msg");     // "성공" (자동 디코딩됨)

Java​

// Spring Boot Controller 예시
@GetMapping("/pay/result")
public String payResult(@RequestParam String resCd, @RequestParam String msg) {
    System.out.println("응답코드: " + resCd);
    System.out.println("메시지: " + msg); // 프레임워크가 자동 디코딩 처리
    return "resultView";
}

Python​

from urllib.parse import urlparse, parse_qs

url = "[https://shop.com/result?resCd=0000&msg=%EC%84%B1%EA%B3%B5](https://shop.com/result?resCd=0000&msg=%EC%84%B1%EA%B3%B5)"
parsed = urlparse(url)
params = parse_qs(parsed.query)

print(params['resCd'][0]) # '0000'
print(params['msg'][0])   # '성공'