ordernow payment API - 킥오프 프로세스

1. 사전 준비 사항

1. API URL: ordernow에서 발급받은 API 엔드포인트(예: https://pg.ordernow.au/...)
2. ClientKey: 외부 호출 인증을 위해 부여된 키(또는 인증 정보)
3. STORE(가게명): 실제 매장 혹은 테스트 매장 식별자
4. POIID(디바이스 고유 ID): POS 단말(또는 디바이스)의 고유한 ID

주의: 실제 운영(Production)과 테스트(Sandbox) 환경이 구분되어 있을 수 있으니, 각각 발급받은 URL과 키가 올바른지 확인하세요.

2. 단계별 프로세스

2.1 발급 정보 기반 API 연동 테스트

1. API 호출 환경 설정
   • 고객사 개발 환경(로컬 PC, 서버 등)에서 API URL과 ClientKey를 설정
   • STORE(가게명), POIID(디바이스 ID) 값도 코드 내에 반영하거나 환경 변수로 저장
   • MessageHeader에 ServiceID는 24시간 이내에 고유한 값이어야 함
2. 테스트 모드인지 확인
   • 실제 결제 발생 전, Sandbox 환경(테스트 URL)에서 먼저 검증 권장
   • Test Card(가상 카드) 등을 사용해 승인/거절 시나리오를 시도해볼 수 있음
3. 예시 요청
   • purchase(amount) 또는 유사한 결제 요청 API를 POST로 호출
   • 요청 Body에 SaleToPOIRequest 구조, MessageHeader(SaleID=STORE, POIID=디바이스 ID) 등을 포함

참고 코드 예시 (간략)

// typescript 코드 예시
const body = {
  SaleToPOIRequest: {
    PaymentRequest: { /* ... */ },
    MessageHeader: {
      ProtocolVersion: '3.0',
      MessageClass: 'Service',
      MessageCategory: 'Payment',
      MessageType: 'Request',
      SaleID: STORE,
      ServiceID: 'xxxxxx',  // 24시간 이내에 Unique ID
      POIID: POIID
    }
  }
};

fetch(API_URL, {
  method: 'POST',
  headers: {
    'x-api-key': ClientKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => response.json())
.then(result => {
  // TODO: 결과 처리
})
.catch(error => {
  // 에러 처리
});
  

2.2 고객사 프로그램 내부에서 API 호출 테스트

1. 프로그램 연동
   • 고객사가 이미 운용 중인 POS 프로그램(또는 웹/앱)에 결제 버튼(또는 결제 기능) 구현
   • 결제 버튼을 누르면 ordernow payment API를 호출하도록 연동
2. REST 호출 검증
   • 오류 로그(HTTP 4xx/5xx)나 인증 에러가 없는지 확인
   • Success, Failure, Error 등 결제 응답 상태를 프로그램 내부에서 적절히 분기 처리
3. 테스트 카드 / 소액 결제
   • 실제 카드 정보 대신 테스트용 카드 사용 권장
   • 지정된 화폐단위로 여러 시나리오(승인, 거절, 취소) 시도

2.3 성공 / 실패 핸들링

1. 성공(결제 승인) 처리
   • Result가 Success일 때, 고객사 프로그램에서 주문 상태를 “결제 완료”로 변경
   • 필요한 경우 사용자에게 결제 성공 알림(영수증 발행, 알림톡 등)
2. 실패(거절/오류) 처리
   • Result가 Failure 또는 Error인 경우, 거절 사유(AdditionalResponse, refusalReason) 등을 로그로 남김
   • 재시도 안내, 다른 결제 수단 유도 등 UI/UX 제공
3. 예외 시나리오
   • 네트워크 에러, Timeout 발생 시 → 재시도 전략(몇 초 후 재시도, 결제 중단 후 사용자 안내)
   • Webhook 기반 알림을 사용할 경우, Webhook에서 최종 결제 상태를 수신하여 재확인

2.4 오더나우 앱 내 페이먼트 트랜잭션 / 입금액 표기 확인

1. ordernow 측 연동 확인
   • 결제가 완료되면, ordernow Payout 페이지(또는 앱)에서 해당 주문에 대한 트랜잭션 정보와 입금액 표시가 정상 반영되는지 확인
   • 트랜잭션 ID, 결제 시간, 결제 금액, 수수료 등이 정확히 표기되는지 점검
2. 입금(정산) 주기 확인
   • 실제 운영 환경에서는 일정 주기(예: 익일 비지니스데이)로 정산 입금이 이루어짐
   • 테스트 결제이더라도 결제껀 표시가 잘 되는지, 입금될 금액은 나오는지 등을 확인
3. 비교 검증 (매출집계 별도로 사용시)
   • 고객사 프로그램(매출 집계) vs. ordernow 관리자 페이지(트랜잭션 로그) 금액이 일치하는지 교차 검증
   • 결제 시점과 정산 시점이 달라 발생할 수 있는 차이를 유의 (시스템상 시드니시간 새벽3시에 송금 예약됨)

3. 마무리 점검 사항

• (1) API Key 보안
  x-api-key(ClientKey)는 외부로 유출되지 않도록 주의. 소스코드 내에서 암호화 또는 안전한 환경 변수로 관리
• (2) 에러 로깅 및 알림
  결제 API 호출이 실패했을 때, 상세 로그를 남기고 운영팀이 모니터링할 수 있는 체계를 마련
• (3) Webhook 도입 고려
  결제 승인/거절 여부를 실시간으로 업데이트하기 위해 Webhook 연동을 추가 구현하면 편리함
• (4) 운영 전 재검증
  실제 운영(Production) 전, 테스트 환경에서 여러 케이스(승인, 거절, 취소, 오프라인 등) 충분히 시뮬레이션
  POS 디바이스/단말 버전 및 네트워크 연결 상태도 함께 점검

4. 문의 및 지원

• 기술 지원: [email protected] 이메일 문의
• 장애 대응: 긴급 상황 발생 시 카카오 채널고객센터 또는 담당자 연락

본 킥오프 프로세스를 마친 뒤, 고객사는 실제 운영 환경에서 안정적으로 결제를 처리할 수 있는 기초를 갖추게 됩니다. 추가 문의나 문제 발생 시 언제든지 연락 주시기 바랍니다.

감사합니다.