여행 결제 API
여행 예약을 위한 결제 게이트웨이 API: 체크아웃부터 환불까지
결제 게이트웨이 API는 예약 사이트가 카드 정보를 직접 다루지 않고 여행객의 결제를 받는 방법입니다. 이 페이지에서는 카드 결제 한 건의 호출 순서, 결제가 거치는 상태, 여행 결제가 일반 소매보다 까다로운 이유, 그리고 PHPTRAVELS가 예약 흐름을 원하는 게이트웨이에 연결하는 방법을 설명합니다.
- 세션, 3-D Secure, 매입
- 모든 결제 상태
- 카드, 월렛, 은행, 외상
- 서버에 카드 정보 없음
호출 방식
카드 결제 한 건을 호출 단위로 살펴보기
결제 게이트웨이 API는 결제 회사가 가맹점에 열어 주는 웹 서비스 모음입니다. 서버가 금액과 통화를 지정해 결제 생성을 요청하면, 여행객이 게이트웨이의 자체 폼에 카드 정보를 입력하고, 게이트웨이가 카드 네트워크와 발급 은행과 통신합니다. 서버는 카드 번호를 볼 일이 없고 결제 ID와 상태만 받습니다.
참여자는 네 곳입니다. 다이어그램은 각 참여자를 열로, 각 메시지를 번호가 붙은 화살표로 보여 줍니다. 게이트웨이마다 이름(payment intent, session, order, charge)은 다르지만 순서는 같습니다.
점선 화살표는 웹훅입니다. 게이트웨이가 스스로 서버를 호출하므로 여행객이 브라우저를 닫아도 결제 결과가 예약에 반영됩니다. 각 단계를 PHPTRAVELS 예약에 연결하는 방법은 결제 게이트웨이 연동 페이지에서 설명합니다.
- 여행객
- 내 사이트
- 게이트웨이
- 카드 네트워크 / 은행
01체크아웃여행객 내 사이트
여행객이 일정을 확인하고 결제 버튼을 누릅니다. 예약은 공급사에 보류된 상태이며 아직 확정되지 않았습니다.
02Payment Intent 또는 세션 생성내 사이트 게이트웨이
서버가 시크릿 API 키로 금액, 통화, 예약 번호, 멱등성 키를 보냅니다. 게이트웨이는 결제 ID를 반환합니다.
03호스팅 필드 또는 리디렉션게이트웨이 여행객
카드 입력 폼은 게이트웨이가 제공하며, 내 페이지 안에 삽입하거나 별도 페이지로 열립니다. 카드 정보는 게이트웨이로 바로 전달됩니다.
043-D Secure카드 네트워크 / 은행 여행객
발급 은행이 요구하면 여행객이 은행 앱이나 일회용 코드로 결제를 인증합니다.
05승인게이트웨이 카드 네트워크 / 은행
게이트웨이가 카드 네트워크를 통해 발급사에 해당 금액의 승인을 요청합니다.
06승인 완료, 금액 보류카드 네트워크 / 은행 게이트웨이
발급사가 카드에서 금액을 보류합니다. 아직 돈은 이동하지 않았습니다.
07사이트로 결과 전달게이트웨이 내 사이트
여행객이 결제 ID와 함께 사이트로 돌아옵니다. 서버는 API에서 상태를 읽고 공급사에 예약을 확정합니다.
08매입내 사이트 게이트웨이
공급사가 확정하면 서버가 전액 또는 더 적은 금액으로 매입합니다. 많은 게이트웨이는 즉시 매입도 지원합니다.
09웹훅게이트웨이 내 사이트게이트웨이가 자동으로 전송
게이트웨이가 서명된 이벤트(매입, 환불, 분쟁 등)를 엔드포인트로 보냅니다. 서버는 서명을 확인하고 예약을 갱신합니다.
결제 상태
상태 머신으로 보는 결제의 일생
모든 게이트웨이 API는 결제마다 상태를 알려 줍니다. 표현은 달라도 몇 가지 상태로 대응되며, 예약 로직은 각 상태에 맞게 반응해야 합니다.
created
생성됨
금액과 통화가 지정된 결제가 만들어져 여행객의 입력을 기다립니다.
failed최종
실패
거절되었거나 3-D Secure가 완료되지 않았거나 중단되었습니다. 청구되지 않습니다.
authorized
승인됨
발급사가 금액을 승인하고 카드에서 보류하고 있습니다.
voided최종
취소됨
매입 전에 보류를 취소하므로 여행객에게는 청구되지 않습니다.
captured
매입됨
금액이 확정되어 가맹점 계좌로 정산됩니다.
partially_refunded최종
부분 환불됨
매입한 금액의 일부를 돌려줍니다. 예를 들어 취소 수수료를 제외하는 경우입니다.
refunded최종
환불됨
매입한 전체 금액이 카드로 돌아갑니다.
승인은 영원히 유지되지 않습니다. 제때 매입하지 않으면 보류가 만료되고 은행이 금액을 풀어 줍니다. 부분 환불된 결제는 매입 금액까지 추가로 환불할 수 있습니다.
여행이 더 어려운 이유
여행 결제가 다른 이유
상점은 재고가 있는 물건을 팝니다. 여행 판매자는 공급사가 아직 확정하지 않은 예약의 대금을 출발 몇 달 전에 받기도 합니다. 결제 API는 이런 상황에 맞아야 합니다.
01
먼저 승인, 나중에 매입
요청 기반 호텔, 단체 운임, 투어는 주문 후 몇 시간에서 며칠 뒤에 확정됩니다. 먼저 승인하고 확정 시 매입하면 성사되지 않은 예약에는 청구하지 않습니다.
02
공급사가 거절할 수도 있음
결제와 발권 사이에 운임이 매진될 수 있습니다. 승인 단계에서는 취소로 금액을 풀어 주고, 매입 후에는 환불이 됩니다.
03
취소 수수료를 뺀 부분 환불
숙박이나 항공권을 취소하면 보통 수수료가 남습니다. 환불 호출은 원 결제에 대해 더 적은 금액을 규정이 요구하는 횟수만큼 보냅니다.
04
다중 통화
여행객은 자국 통화로 결제하고 공급사는 자사 통화로 청구합니다. 게이트웨이는 표시 통화를 지원해야 하고, 기록에는 두 금액이 모두 남아야 합니다.
05
고액 사기 검사
내일 출발 항공권, 타인을 위한 구매, 새 카드 결제는 전형적인 사기 패턴입니다. 3-D Secure, 게이트웨이의 위험 점수, 수동 검토 대기열이 고액 주문을 보호합니다.
06
몇 달 뒤 도착하는 차지백
분쟁은 여행이 끝난 뒤에 접수되는 경우가 많습니다. 인증 결과, 예약 문서, 게이트웨이 이벤트를 함께 보관해 두면 증거를 들어 대응할 수 있습니다.
결제 수단
결제 게이트웨이 API가 지원하는 결제 방법
카드는 선택지 중 하나일 뿐입니다. 여행객과 에이전트는 서로 다른 방식으로 결제하며, 환불 방식도 각각 다릅니다.
| 수단 | 설명 | 입금 시점 | 환불 |
|---|---|---|---|
| 카드 | 게이트웨이를 통한 체크카드와 신용카드이며, 발급사가 요구하면 3-D Secure를 적용합니다. | 체크아웃 시 승인하고, 즉시 또는 공급사 확정 시 매입합니다. | API로 같은 카드에 전액 또는 부분 환불합니다. |
| 디지털 월렛 | 게이트웨이가 지원하는 PayPal이나, 토큰화된 카드를 담은 모바일 월렛 같은 계정입니다. | 체크아웃 시 여행객이 월렛에서 승인한 뒤입니다. | 게이트웨이를 통해 월렛 또는 그 뒤의 카드로 돌려줍니다. |
| 계좌 이체 | 여행객이나 에이전트가 귀사 은행 계좌로 송금하고, 입금 내역이 예약에 기록됩니다. | 며칠 뒤이며, 직원이 입금을 확인할 때까지 예약은 대기합니다. | 게이트웨이 밖에서 이체로 돌려줍니다. |
| 후불 | 예약은 지금 하고 결제는 나중에 합니다. 입금되면 직원이 결제를 기록합니다. | 예약 후 여행객이 결제할 때입니다. | 실제로 결제된 금액만 돌려줍니다. |
| B2B 에이전트 월렛 또는 신용 | 하위 에이전트가 미리 충전한 잔액이나 귀사가 부여한 신용 한도에서 결제합니다. | 예약 시 차감되며, 예치금과 신용은 귀사 조건에 따라 정산합니다. | 에이전트 잔액으로 환급합니다. |
계좌 이체, 후불, 월렛 잔액은 게이트웨이가 아니라 플랫폼 자체의 정산 방식입니다. 에이전트 잔액과 신용 한도는 B2B 에이전트 지갑 페이지에서, 은행 결제는 계좌이체 결제 페이지에서 설명합니다.
PHPTRAVELS에 바로 사용 가능
이미 연동된 결제 게이트웨이 API
아래 게이트웨이는 이미 PHPTRAVELS에 연동되어 있습니다. 결제 회사에서 가맹점 계정을 만들고, 관리자 화면에 API 키를 입력하고, 샌드박스에서 테스트한 뒤 운영을 시작하면 됩니다. 목록은 연동 디렉터리의 실시간 정보입니다.
Stripe연동 가이드
PayPal연동 가이드
xMoney
Fawaterk
Cashfree
Paystack
Flutterwave
Adyen
MyFatoorah
SSLcommerz
Razorpay- 모든 결제 연동
수수료와 가맹점 심사는 PHPTRAVELS가 아니라 결제 회사와 협의합니다. 목록에 없는 게이트웨이는 맞춤형 API 연동(으)로 추가할 수 있으며, 각 게이트웨이의 설정 방법은 결제 게이트웨이 연동 페이지에서 설명합니다.
보안
카드 정보를 내 시스템 밖에 두기
가장 안전한 카드 번호는 서버가 한 번도 받지 않은 번호입니다. 결제 게이트웨이 API는 서버가 카드 번호를 받지 않도록 설계되어 있습니다.
카드 번호는 저장하지 않기
카드 정보는 게이트웨이로 전달되고, 게이트웨이가 토큰이나 결제 ID를 돌려줍니다. 데이터베이스에는 그 참조 값만 보관하며 카드 번호와 보안 코드는 저장하지 않습니다.
호스팅 필드와 리디렉션으로 PCI DSS 범위 축소
PCI DSS는 카드 정보를 다루는 모든 곳에 적용됩니다. 카드 폼이 게이트웨이의 자체 페이지나 삽입 필드이면 범위에 들어가는 시스템이 훨씬 줄어듭니다. 어떤 자체 평가 유형이 해당되는지는 매입사에 확인하세요.
서명으로 검증하는 웹훅
각 웹훅에는 공유 시크릿으로 만든 서명이 포함됩니다. 서버가 서명을 다시 계산해 일치하지 않는 이벤트를 거부하므로 결제 완료 예약을 위조할 수 없습니다.
시크릿 키는 서버에만
브라우저에는 공개용 키만 전달됩니다. 결제와 환불을 생성하는 시크릿 키는 서버 설정에 두고, 요청마다 멱등성 키를 붙여 재시도해도 이중 청구되지 않게 합니다.
1$payload = file_get_contents("php://input"); 2$signature = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; 3$expected = hash_hmac("sha256", $payload, $webhookSecret); 4 5if (!hash_equals($expected, $signature)) { 6 http_response_code(400); exit; // reject 7} 8$event = json_decode($payload, true); 9if (alreadyHandled($event["id"])) exit; // repeat delivery10updateBooking($event["data"]["metadata"]["booking_ref"], $event["type"]);
일반적인 예시입니다. 헤더 이름과 서명 방식은 선택한 게이트웨이에 따라 달라집니다.
PHPTRAVELS는 직접 호스팅하는 소프트웨어이므로 PCI DSS 준수는 소프트웨어 자체가 아니라 귀사의 비즈니스와 서버를 기준으로 평가됩니다.
결제 회사가 제공하는 웹 서비스 모음으로, 웹사이트가 카드 정보를 직접 저장하지 않고도 결제를 생성하고, 은행에 승인을 요청하고, 매입하고, 환불하고, 웹훅으로 상태 알림을 받을 수 있게 해 줍니다.
게이트웨이는 웹사이트가 직접 통신하는 부분으로, 카드를 안전하게 수집해 요청을 전달합니다. 프로세서는 거래를 카드 네트워크를 거쳐 발급 은행까지 전달합니다. 많은 업체가 둘을 하나의 서비스로 제공합니다.
우리 사업을 승인해 주고, 고객의 국가, 통화, 결제 수단을 지원하며, 승인과 매입을 분리하고 부분 환불을 제공하는 곳입니다. 글로벌 카드 게이트웨이와 지역 게이트웨이를 함께 쓰는 여행사도 많습니다.
승인은 여행객의 카드에서 금액을 보류하는 것이고, 매입은 실제로 청구하는 것입니다. 둘을 나누면 공급사가 예약을 확정한 뒤에만 청구할 수 있고, 확정되지 않으면 보류를 취소할 수 있습니다.
유럽경제지역과 영국을 비롯한 많은 지역에서 대부분의 온라인 카드 결제에 강력한 고객 인증이 요구되며, 카드는 3-D Secure로 이를 충족합니다. 인증 절차는 게이트웨이 API가 처리하고, 예약 흐름은 결과를 기다립니다.
그것만으로는 아닙니다. 게이트웨이의 호스팅 필드나 결제 페이지를 쓰면 카드 정보가 서버를 거치지 않아 PCI DSS 범위가 줄어들지만, 매입사가 요구하는 평가는 여전히 완료해야 합니다.
게이트웨이가 부분 환불을 지원하면 가능하며, 대부분의 카드 게이트웨이가 지원합니다. 원 결제에 대해 더 적은 금액, 예를 들어 요금에서 취소 수수료를 뺀 금액으로 환불을 요청합니다.
아니요. 선택한 게이트웨이에서 가맹점 계정을 직접 만들고 수수료도 그쪽과 협의합니다. PHPTRAVELS는 관리자 화면에 입력한 API 키로 예약 플랫폼을 그 계정에 연결합니다.
네. 문서화된 API가 있는 게이트웨이라면 맞춤 연동으로 추가할 수 있고, 소스 코드가 포함되어 있어 개발자가 결제 흐름을 확장할 수도 있습니다.