개발자센터
V1
V2

페이조아 유의사항

결제 연동시 유의사항을 안내합니다.

페이조아 결제 특이사항

PC 결제는 success, 모바일 결제는 imp_success 전달

PC와 모바일에서 결제창이 각기 다른 방식으로 호출되기 때문에, 결제 후속 프로세스에도 차이가 있습니다. PC 결제의 경우 페이조아 결제창이 iframe 방식으로 호출되기 때문에 결제 프로세스 완료 후 콜백 함수(IMP.request_pay 함수 호출시 전달한 두 번째 파라미터)가 호출되지만, 모바일 결제의 경우 페이조아 결제창이 페이조아 URL로 리디렉션되기 때문에 결제 프로세스 완료 후 지정 된 URL(m_redirect_url)로 302 리디렉션 됩니다. 이때 결제 실패/성공 여부를 의미하는 파라미터가 전달되는데, PC 결제시에는 success, 모바일 결제시에는 imp_success로 서로 다른 이름의 파라미터가 전달되어 주의가 요구됩니다. 정리해보면 아래와 같습니다.

  • [PC결제] iframe → 콜백 함수 호출 → 콜백 함수로 전달되는 response 객체에 success 키 값으로 전달

    IMP.request_pay(
      {
        // 중략
      },
      function (response) {
        const { success } = response; // 결제 성공 또는 실패 여부
        if (success) {
          // 결제 성공 시 프로세스
        } else {
          // 결제 실패 시 프로세스
        }
      }
    );
  • [모바일 결제] 리디렉션 → m_redirect_url로 302 리디렉션 → imp_success 쿼리 파라미터 전달

    /**
     * m_redirect_url을 https://myservice.com/payments/complete로 설정한 후
     * 결제 프로세스 종료 됐을때 302 리디렉션 되는 URL 예시
     */
    https://myservice.com/payments/complete?**imp_success=true**&imp_uid=imp1234567890&merchant_uid=mid_123467890

imp_successsuccess는 deprecated

하지만 애초에 imp_success 파라미터든 success 파라미터는 deprecated 되었기 때문에 해당 파라미터를 기반으로 결제 실패/성공 여부를 판단하시면 안 됩니다. 해당 파라미터는 단순히 포트원 → 가맹점 클라이언트로 응답되는 시기의 결제 실패/성공 여부를 내려주는데, 이 값은 페이조아 → 포트원으로 결제 결과 통지 → 포트원 DB 업데이트가 완료된 시점이어야지만 정확하다고 볼 수 있습니다.

그런데 페이조아 → 포트원로의 결제 결과가 전달 → 포트원 DB 업데이트와 포트원 → 가맹점 클라이언트로의 응답이 비동기로 동작하기 때문에 실제로는 결제가 정상적으로 완료된 경우에도 아직 포트원 DB에 업데이트가 안 된 시점이라 가맹점 클라이언트로 응답되는 imp_success 또는 success 파라미터가 false일 수 있습니다.

따라서 포트원 → 가맹점 클라이언트로 응답되는 결과 데이터 중 신뢰할 수 있는 값은 오로지 포트원 주문 번호(imp_uid)와 가맹점 주문 번호(merchant_uid)이며, 이 값을 가맹점 서버로 전달해 포트원 결제내역 조회 API(GET /payments/{imp_uid})를 호출한 결과(status)를 보고 결제 실패(failed)/성공(paid) 여부를 판단하시길 바랍니다.

사파리 브라우저 - 하나카드 / NH앱캐시 결제 시 세션 관련 이슈 존재

사파리 브라우저에서 하나카드 / NH앱캐시(계좌이체) 결제 시 아래와 같이 세션 유효기간이 초과되어 카드사와 연결이 종료되었습니다와 같은 메시지가 렌더링되며 더 이상 결제가 불가능한 이슈가 있습니다.

참고이미지

이러한 현상을 겪으시는 경우, 사파리 환경설정에서 아래와 같이 크로스 사이트 추적 방지 해제 및 모든 쿠키 차단이 모두 해제되어 있는지 확인해 보시고, 모두 해제 후 다시 시도해보시길 바랍니다.

참고이미지

사파리/파이어폭스 브라우저 - BC카드 결제시 이슈 존재

신용카드 결제창에서 BC카드 선택 후 다음 버튼 클릭시 “지불에 실패하였습니다”라는 알림창이 뜨면서 더 이상 진행되지 않는 이슈가 있습니다. 다른 브라우저(크롬, 오페라, 엣지 등)나 다른 카드사에서는 이상 없이 BC카드 결제를 위한 페이북 QR코드가 렌더링되지만, 사파리와 파이어폭스에서는 아래와 같이 “지불에 실패하였습니다”라는 메시지를 담고 있는 알림창이 뜨면서 더 이상 결제가 진행되지 않습니다.

참고이미지

이러한 현상을 겪으시는 경우, 사파리 환경설정에서 아래와 같이 *.payjoa.co.kr 도메인에 대해 팝업 허용 설정 되어 있으신지 확인해보시고, 허용 후 다시 시도해보시길 바랍니다.

참고이미지

실시간 계좌이체 결제 플로우 상이

페이조아의 경우 내부적으로 토스페이먼츠 - 계좌이체를 사용하고 있어 토스 간편결제, NH앱캐시 그리고 계좌 정보 직접 입력을 통해서만 계좌이체가 가능합니다. 여기서 계좌 정보 직접 입력시, 보안카드 / OTP 인증 → 공인인증서 인증까지 진행해야 합니다.

단, 모바일 결제의 경우엔 토스 간편결제와 NH앱캐시를 통해서만 결제가 가능합니다.

PC 결제모바일 결제

가상계좌 입금 완료시, 송금자 이름만 알 수 있음

페이조아는 (발급된) 가상계좌에 입금 완료시, 송금자의 정보(은행명, 계좌번호, 송금인) 중 송금자 이름만 알려줍니다. 따라서 포트원 결제내역 조회(GET /payments/{imp_uid})시 송금자의 은행코드(bank_code)과 은행명(bank_name)은 모두 NULL로 내려가며, 송금자 이름을 확인하기 위해서는 아래 예시와 같이 별도의 쿼리 파라미터(extension)를 true로 설정해주셔야 합니다.

GET http://api.iamport.kr/payments/{포트원 번호}?**extension=true**
{
  // ... 중략
  "bank_code": null, // 송금자 은행 코드 알 수 없음
  "bank_name": null, // 송금자 은행 이름 알 수 없음
  "extension": {
    // ... 중략
    "REMITTER": "홍길동" // 송금자 이름
  }
}

가상계좌 결제 취소시, PG사와 특약 필요

가상계좌 입금 완료 건에 대한 결제 취소(환불)은 가상계좌 발급 시 부과되는 수수료 이슈로 인해 페이조아와 특약을 맺어야지만 가능합니다. 이 특약 없이는 기본적으로 가상계좌 결제 건의 환불은 불가능합니다.

가상계좌 결제 취소시, 실제 환불 금액 입금까지 7 영업일 이상 소요

페이조아 가상계좌 결제 취소(환불)는 가맹점 → 포트원 → 페이조아로 환불 요청 접수 시, 페이조아 담당자가 수기로 확인 후 환불 처리를 해 주는 프로세스로 진행되기 때문에 환불 금액이 실제로 입금 될때까지 7 영업일 이상 소요됩니다.

과세/면세/복합과세용 CPID는 모두 건별 구분으로 1개만 발급하여 사용

페이조아 측으로 해당 CPID 설정을 건별구분으로 발급 해달라고 요청해주셔야 합니다. 그래야 하나의 CPID로 과세/면세/복합과세 거래건을 모두 처리할 수 있습니다.

면세금액은 카드 결제만 설정 가능

결제창(IMP.request_pay 함수) 호출시 총 결제 금액(amount)중 면세 금액(tax_free)을 설정할 수 있습니다. 단, 페이조아 시스템 상 면세 금액은 카드 결제(pay_method: "card") 시에만 가능하고 계좌이체 / 가상계좌 결제 시에는 설정할 수 없어 전액 과세 처리 됩니다.

페이조아 자체 버그

에스크로 결제시 구매자 전화번호가 결제창에 자동 완성되지 않음

참고이미지
  • IMP.request_pay 호출시 전달한 구매자의 전화번호(buyer_tel)가 다른 결제창과는 달리 에스크로 결제창에서는 자동 완성되지 않습니다. 이는 페이조아가 해당 기능을 제공하지 않는 것으로 이용에 참고 부탁드립니다.