일반결제 연동 유의사항

결제창 호출 실패 사유 알 수 없음

상점 아이디 설정 이슈, 파라미터 설정 오류 등으로 결제창 호출이 불가능한 경우 PG사로부터 정확한 사유를 전달받지 못하기 때문에 다음과 같이 “알 수 없는 이유로 결제가 중단되었습니다. 나이스페이로 문의(1661-0808)하세요.” 에러를 리턴합니다. 이 메시지를 받으신 경우 결제창 호출 시 사용한 파라미터 전문과 함께 포트원으로 문의해 주시길 바랍니다.

카드 결제

토스뱅크 카드사 다이렉트 호출 미지원

나이스페이먼츠(신모듈)의 경우 토스뱅크 카드(card.direct.code = “092”) 다이렉트 호출이 불가능합니다.

카드사 다이렉트 호출시 고정 할부 개월수 필수 입력

나이스페이먼츠(신모듈)는 카드사 다이렉트 호출시 고정 할부 개월수를 필수 로 입력해야 합니다. 결제 금액이 할부 지원 금액 미만(일반적으로 50,000원 이상 결제 시 할부 기능을 지원하나 카드사에 따라 다를 수 있습니다.)인 경우 할부 개월수를 0(일시불)으로 전달해야 합니다.

IMP.request_pay(
  {
    // ...중략
    pg: "nice_v2",
    pay_method: "card",
    card: {
      direct: {
        // 다이렉트 호출할 카드사 코드와 고정 할부 개월수를 모두 지정해야 함
        code: "361", // BC카드
        quota: 5, // 5개월 할부
      },
    },
  },
  // 콜백함수
);

IMP.request_pay(
  {
    // ...중략
    pg: "nice_v2",
    pay_method: "card",
    card: {
      direct: {
        // 다이렉트 호출 할 카드사 코드와 고정 할부 개월수를 모두 지정해야 함
        code: "365", // 삼성카드
        quota: 0, // 일시불
      },
    },
  },
  // 콜백함수
);

모바일 환경에서는 다이렉트 호출시에만 할부 옵션 설정 가능

나이스페이먼츠(신모듈)의 경우 일반 카드 결제 시(간편결제 제외) 할부 옵션(고정 할부 개월수)사용이 가능하나 모바일 환경에서는 카드사 다이렉트 호출할 때만 할부 옵션 사용이 가능합니다. 만약 모바일 환경에서 다이렉트 호출 코드 없이 할부 옵션을 전달하는 경우 무시됩니다.

모바일 환경에서 리스트 할부 개월수만 전달 → 전달한 파라미터가 무시되고 모든 할부 개월수 렌더링

IMP.request_pay(
  {
    // ...중략
    pg: "nice_v2",
    pay_method: "card",
    display: { card_quota: [2, 3, 4, 5, 6] }, // 2 ~ 6 개월 리스트 할부 개월수 적용 시도
  },
  // 콜백함수
);

모바일 환경에서 3개월 고정 할부 개월수만 전달 → 전달한 파라미터가 무시되고 모든 할부 개월수 렌더링

// ...중략
IMP.request_pay(
  {
    pg: "nice_v2",
    pay_method: "card",
    display: { card_quota: [3] }, // 3개월 고정 할부 개월수 적용 시도
  },
  // 콜백함수
);

가상계좌

가상계좌 입금 기한(vbank_due) 필수 입력

나이스페이먼츠(신모듈) 가상 계좌 발급 시, 입금 기한은 필수 입력해야 하며 아래 4가지 형식만 유효합니다. 입금 기한을 입력하지 않거나, 유효하지 않은 형식을 입력할 경우 가상계좌 발급 결제창이 호출되지 않고 “결제 창 호출에 실패하였습니다. 나이스페이 V2 가상계좌 발급시 유효한 입금 기한을 필수로 입력해야 합니다.” 라는 에러 메세지가 리턴되오니 유의하시기 바랍니다.

• YYYY-MM-DD HH:mm:ss
• YYYYMMDDHHmmss
• YYYY-MM-DD
• YYYYMMDD

계좌이체

계좌이체 다이렉트 호출시 은행 코드 지정 불가능

나이스페이먼츠(신모듈) 계좌이체 다이렉트 호출은 은행 코드를 지정하지 않고 바로 뱅크페이 결제창이 띄워지는 구조입니다.

계좌이체 다이렉트 호출시 현금영수증 정보는 필수 입력

계좌이체 거래는 계좌에서 현금성 결제로 현금영수증 발급이 가능하므로 현금영수증 정보를 필수로 입력해야 합니다. 만약 입력하지 않을 경우 나이스페이먼츠(신모듈) 계좌이체 다이렉트 호출 시 현금영수증 발급 유형은 필수 입력입니다. 라는 에러 메시지가 뜨면서 결제창이 호출되지 않으니 유의하시기 바랍니다.

계좌이체 에스크로 결제시에는 다이렉트 호출 불가능

나이스페이먼츠 정책상 계좌이체 + 에스크로 결제시에는 다이렉트 호출이 불가능합니다. 아래와 같이 계좌이체 + 에스크로 + 다이렉트 호출을 위한 파라미터를 설정할 경우 “나이스페이 V2 계좌이체 에스크로 결제시 다이렉트 호출은 불가능합니다.”라는 에러 메시지가 뜨면서 결제창이 호출되지 않으니 유의하시기 바랍니다.

계좌이체 에스크로 결제시 결제창에 올바른 이메일을 입력해야 함

존재하지 않는 이메일을 입력할 경우 이메일 주소 오류라는 에러 메시지와 함께 승인에 실패합니다. 또한 실제로 존재하는 이메일 도메인이더라도 나이스페이먼츠 정책상 유효하지 않다고 취급하는 이메일 주소(예: .finance로 끝나는 이메일 주소)를 입력한 경우 승인은 정상적으로 되지만 이후 API로 에스크로 등록시 에스크로 구매 확정 이메일이 전송되지 않습니다.

자세히 보기

IMP.request_pay(
  {
    // ...중략
    pg: "nice_v2",
    pay_method: "trans", // 계좌이체 결제
    escrow: true, // 에스크로 결제
  },
  // 콜백함수
);

휴대폰 소액결제

실물/컨텐츠 여부(digital) 필수 입력

휴대폰 소액결제시 실물/컨텐츠 여부(digital) 파라미터는 필수 입력입니다. 입력하지 않는 경우 “나이스페이 V2 휴대폰 소액결제시 상품 유형 파라미터는 필수 입력입니다.” 라는 에러 메시지가 뜨면서 결제창이 호출되지 않으니 유의하시기 바랍니다.

또한 상점 아이디 설정과 실물/컨텐츠 여부가 불일치할 경우 “CPID 설정 오류”라는 메시지가 리턴되며 결제창 호출에 실패하니 유의하시기 바랍니다.

상품권 결제

컬쳐랜드(cultureland)만 지원

나이스페이먼츠(신모듈)은 상품권 결제시 컬쳐랜드만 지원하며 북앤라이프, 스마트문상, 해피머니 등은 지원하지 않습니다.

MallUserID(bypass.nice_v2.MallUserID)는 필수 입력

나이스페이먼츠(신모듈) 상품권 결제시 고객사 구매자 ID를 의미하는 MalluserID는 필수 입력이며, bypass 파라미터로 전달할 수 있습니다.

승인 완료시 나이스페이먼츠로부터 승인번호(apply_num)가 전달되지 않음

나이스페이먼츠(신모듈)은 상품권 결제시에는 승인 번호를 전달하지 않아 승인번호 확인이 어렵습니다. 따라서 결제 내역 조회시 승인 번호는 null로 리턴됩니다.

GET /payments/{imp_uid}

{
  // ...중략
  "status": "paid",
  "pay_method": "cultureland",
  "pg": "nice_v2",
  "apply_num": null
}

카카오페이

네이버페이

결제 수단 지정 시 카드 또는 포인트 지정 필요

나이스페이먼츠(신모듈)를 통한 네이버페이 결제 시 카드 또는 포인트 결제를 지정하여 호출해야합니다. 결제 수단(pay_method) 파라미터에 naverpay 입력은 불가능하며 naverpay_card(카드) 또는 naverpay_point(포인트/머니) 둘 중 하나로 입력해야 정상적으로 결제창이 호출되오니 유의하시기 바랍니다.

네이버페이 머니와 포인트 복합 결제시, 포인트가 먼저 사용 됨

네이버페이 포인트 결제시 네이버페이 머니, 포인트 또는 복합(머니와 포인트 함께 사용) 방식으로 결제가 가능하며, 만약 복합 방식으로 결제할 경우 포인트 금액이 먼저 차감됩니다.

네이버페이 포인트 결제시 현금영수증 정보 필수 입력

네이버페이 포인트 결제 시 현금영수증 발급이 가능하며 현금영수증 정보를 필수로 입력해야 합니다. 만약 입력하지 않을 경우 “나이스페이 V2 네이버페이 포인트 결제시 현금영수증 발급 유형은 필수 입력입니다.”라는 에러 메시지가 뜨면서 결제창이 호출되지 않으니 유의하시기 바랍니다. 단, 네이버페이 머니로 결제할 경우에만 현금영수증이 발급됩니다. 결제 금액 모두 네이버페이 포인트로 결제하는 경우에는 결제창 호출시 현금영수증 정보를 전달하더라도 발급되지 않습니다.

페이코

삼성페이/11Pay (구.SKPay)/SSGPAY

애플페이/LPAY

SSG 은행계좌 결제

SSGPAY 은행 계좌 결제 시 주문 번호에 특수 문자를 사용 불가능

SSGPAY 정책상 은행 계좌 결제시에는 주문 번호(merchant_uid)에 특수 문자가 허용되지 않습니다. 주문 번호에 특수문자 입력 시 “나이스페이 V2 SSGPAY 은행 계좌 결제시 주문 번호에 특수문자는 허용되지 않습니다.”와 같은 에러 메시지가 리턴되면서 결제창이 호출되지 않으니 참고 부탁드립니다.

SSGPAY 은행 계좌 결제시 현금영수증 정보는 필수 입력

SSGPAY 은행 계좌 거래는 현금성 결제로 현금영수증 발급이 가능하므로 현금영수증 정보는 필수 입력입니다. 만약 입력하지 않을 경우 “나이스페이 V2 SSGPAY 은행 계좌 결제시 현금영수증 발급 유형은 필수 입력입니다.”라는 에러 메시지가 뜨면서 결제창이 호출되지 않으니 유의하시기 바랍니다.

IMP.request_pay({
  // ...중략
  pg: "nice_v2",
  pay_method: "ssgpay_bank",
  bypass: {
    cashReceiptType: "corporate", // 현금영수증 발급 유형(corporate: 지출증빙, personal: 소득공제)
    customerIdentifier: "1178178260", // 현금영수증 발행 식별 정보(사업자 등록번호 또는 휴대폰 번호)
  },
});

SSGPAY 은행 계좌 결제시 현금영수증 발급 정보를 확인할 수 없음

SSGPAY 은행 계좌 결제 시 현금영수증 발급 정보를 입력하여 정상적으로 발급되더라도 승인 완료(status: paid)시 나이스페이먼츠에서 현금영수증 발급 정보를 전달하지 않아 포트원 API로 결제/현금영수증 발급 내역 조회 또는 포트원 콘솔에서 현금영수증 내역을 확인할 수 없습니다. 단, 나이스페이먼츠 어드민에서는 확인이 가능합니다.

GET /payments/{imp_uid}

{
  // ...중략
  "pay_method": "trans",
  "emb_pg_provider": "ssgpay",
  "pg": "nice_v2",
  "status": "paid",
  "cash_receipt_issued": false // 실제로는 현금영수증이 발급됐으나 포트원에 정보가 없으므로 false로 내려감
}

GET /receipts/{imp_uid}

{
  "code": -1,
  "message": "해당 아임포트 고유 번호({아임포트 번호})로 현금영수증을 발급 한 내역이 존재하지 않습니다.",
  "data": null
}

V1 콘솔 현금영수증 발급 내역

현금영수증

현금영수증 발급 유형 지원 여부

현금영수증 발급 유형(cashReceiptType)이 소득 공제(personal)인 경우, 현금영수증 발급 유형(customerIdentifier)은 휴대폰 번호만 가능하며 주민등록번호 입력시 “현금영수증 식별 번호가 올바르지 않습니다.”라는 에러 메시지가 리턴되며 결제창이 호출되지 않으니 유의하시기 바랍니다.

계좌이체 다이렉트 호출, 네이버페이 포인트 결제, SSGPAY 은행 계좌 결제시 현금영수증 정보는 필수 입력입니다.

IMP.request_pay(
  {
    // ...중략
    pg: "nice_v2",
    pay_method: "naverpay_point", // 네이버페이 포인트 결제
    bypass: {
      cashReceiptType: "personal", // 소득공제
      customerIdentifier: "01012345678", // 핸드폰 번호 입력(주민등록번호 불가능)
    },
  },
  // 콜백함수
);

가상계좌, 계좌이체 결제 시 현금영수증 파라미터 사용이 불가능한 경우

결제창을 통한 가상계좌 발급 또는 계좌이체 비 다이렉트 호출 시에는 현금영수증 정보를 파라미터로 전달할 수 없기(전달해도 결제창에 자동 입력되지 않음)때문에 구매자가 결제창에 직접 현금영수증 정보를 입력해야 합니다.