스마트로

스마트로 결제창 연동가이드를 확인 합니다.

1. 스마트로 PG 설정하기

PG사 연동 가이드의 스마트로 페이지의 내용을 참고하여 PG 설정을 진행합니다.

2. 가능한 결제 수단

일반 결제

카드
가상계좌
계좌이체
모바일
간편 결제

빌링키 발급

카드

3. SDK - 유의할 파라미터

결제 (`requestPayment`)

paymentId
- 가맹점 주문 고유 ID
- 스마트로의 경우 특수 문자를 사용할 수 없습니다.
customer.customerId
- 가맹점 고객의 고유 ID 입니다.
- 스마트로의 경우 간편결제, 빌링키 발급 시 필수로 입력합니다.
customer.phoneNumber
- 가맹점 고객의 휴대폰 번호입니다.
- 스마트로의 경우 결제창 호출 시 필수로 입력합니다.
bypass.smartro_v2
- 포트원에서 정규화한 파라미터 이외에 스마트로에서만 특수하게 지원하는 파라미터들을 bypass 를 통해 넘겨줄 수 있습니다.
- GoodsCnt
  - 결제 상품 품목 개수입니다.
- SkinColor
  - UI 색상 스타일입니다.
  - 미 설정시 기본 RED 로 적용됩니다.
  - RED, GREEN, BLUE, PURPLE 네 가지 지원됩니다.
- OpenType
  - 해외카드만 지원할지 여부입니다.
  - 국내 카드: KR, 해외 카드: EN
  - 미 설정시 기본 KR로 적용됩니다.
- 예를 들어 아래와 같이 bypass 파라미터를 넘겨줄 수 있습니다.
```
{
  "bypass": {
    "smartro_v2": {
      "GoodsCnt": 2,
      "SkinColor": "BLUE",
      "OpenType": "EN"
    }
  }
}
```

빌링키 발급 (`requestBillingKeyIssue`)

billingKeyMethod
- CARD로 설정해야 합니다.
- 스마트로는 카드 이외 발급 수단은 지원하지 않습니다.
customer.customerId
- 가맹점 고객의 고유 ID 입니다.
- 스마트로의 경우 간편결제, 빌링키 발급 시 필수로 입력합니다.
- 20자 이하로만 입력 가능합니다.
issueId
- 가맹점에서 채번하는 빌링키 발급 건 고유 ID
- 스마트로의 경우 필수 입력입니다.
bypass.smartro_v2
- 포트원에서 정규화한 파라미터 이외에 스마트로에서만 특수하게 지원하는 파라미터들을 bypass 를 통해 넘겨줄 수 있습니다.
- SkinColor
  - UI 색상 스타일입니다.
  - 미 설정시 기본 RED 로 적용됩니다.
  - RED, GREEN, BLUE, PURPLE 네 가지 지원됩니다.
- IsPwdPass
  - 결제 비밀번호 등록 Skip 여부입니다. (Y: 비밀번호 설정 미사용, N(기본값): 비밀번호 설정 사용)

4. 이외 연동 주의사항

스마트로와 사전 계약이 필요한 경우

아래 기능을 사용하시려면 스마트로에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(예) 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의 해주시기 바랍니다.

간편결제 사용
면세 / 복합과세 사용
할부 사용
상점 부담 무이자 할부 사용
카드사 포인트 사용
에스크로 사용
[TBD] 해외 결제 사용

테스트모드 유의사항

체크카드 결제시, 부분취소 불가능

테스트 모드로 연동시에는 체크카드 결제 건의 경우 전액 취소만 가능하며 부분취소는 불가능합니다.

국민카드(카카오뱅크) 결제 불가능

테스트 모드로 연동시에는 국민카드 또는 카카오뱅크로 결제가 불가능합니다.

카카오페이 / 페이코 결제시, 삼성/현대/농협/신한 카드 외 결제 불가능

카카오페이 / 페이코 - 테스트 모드 연동시 삼성, 현대, 농협, 신한 카드 외의 카드로는 결제가 불가능합니다.

일부 은행(예) K뱅크)의 경우 가상계좌 발급 불가능

테스트 모드로 연동시에는 일부 은행(예) K뱅크, 국민, 전북, 광주, 대구 등)의 경우 가상계좌 발급이 불가능합니다.

카카오페이 - 등록된 카드로 결제시, 반드시 직접 취소 필요

테스트모드로 연동시에는 카카오페이 - 등록된 카드로 결제시, 결제 된 금액이 자동으로 취소되지 않으므로 반드시 아임포트 REST cancel API(POST /payments/cancel)로 직접 취소하셔야 합니다.

카드 결제시 유의사항

할부 개월수 리스트를 제어할 수 없음

다른 PG사는 card.installment.monthOption.availableMonthList 파라미터로 구매자에게 노출 될 할부 개월수 리스트 제어가 가능하나 스마트로는 해당 기능을 지원하지 않습니다.

무이자 할부 개월수 리스트를 제어할 수 없음

다른 PG사는 card.installment.freeInstallmentPlans 파라미터로 구매자에게 노출 될 무이자 할부 개월수 리스트 제어가 가능하나 스마트로는 해당 기능을 지원하지 않으며 상점 아이디에 등록 된 무이자 정보에 따라 자동 표기됩니다.

다이렉트 호출시에만 고정 할부 개월수 필수 입력

스마트로의 경우 카드사 다이렉트 호출시 고정 할부 개월수는 필수 입력입니다. 마찬가지로 고정 할부 개월수 지정시 다이렉트 호출 할 카드사 코드는 필수 입력입니다. 즉, 둘 다 지정하거나 둘 다 지정하지 않거나 둘 중에 하나만 가능합니다.

카드사 포인트 사용 여부 파라미터 제어 불가능

스마트로는 상점 아이디 설정에 카드사 포인트 사용 여부가 결정되는 방식입니다. 따라서 다른 PG사와는 달리 card.useCardPoint 파라미터로 카드사 포인트 사용 여부를 설정할 수 없습니다.

전북카드와 카카오뱅크 카드 다이렉트 호출은 윈도우 OS에서만 가능

스마트로의 경우 전북 카드(code: “372”)와 카카오뱅크 카드(code: “090”) 다이렉트 호출은 윈도우 OS에서만 가능하기 때문에 맥 OS에서는 사용이 불가능합니다.

간편 결제시 유의사항

구매자 식별값 `customer_id`는 필수 입력

스마트로는 간편결제시 구매자를 식별할 수 있는 고유 번호인 customer.customerId를 필수로 입력 받고 있으며, 입력 길이는 20자로 제한됩니다. 이는 빌링키 발급시에도 마찬가지입니다.

네이버페이는 카드 결제만 가능

스마트로를 통한 네이버페이 결제 시 등록된 카드로만 결제가 가능하고 네이버페이 포인트/머니 결제는 불가능합니다. 단, 카드 결제창에서 네이버페이를 선택한 경우에는 네이버페이 포인트/머니 결제 또는 네이버페이 카드 결제 둘 중 하나를 선택할 수 있으니 네이버페이 포인트/머니로 결제를 원하시면 카드 결제창 내에서 네이버페이를 선택하여 결제해주시기 바랍니다.

가상계좌 결제시 유의사항

현금영수증 정보 전달시 다이렉트 호출 필수

구매자는 가상계좌나 계좌이체와 같은 현금성 결제시 결제창에서 현금영수증 정보(현금영수증 발급 유형, 현금영수증 발행 식별 번호)를 선택할 수 있습니다. 스마트로의 경우 현금영수증 정보를 파라미터로 받고 있으며, 파라미터로 전달시 결제창에 자동 입력됩니다.

단, 스마트로 정책상 다이렉트 호출시에만 현금영수증 정보를 파라미터로 전달할 수 있습니다.

휴대폰 소액결제시 유의사항

`productType` 파라미터는 필수 입력

스마트로의 경우 휴대폰 소액결제시 상품 유형을 구분 짓는 productType 파라미터가 필수로 요구됩니다.

`productType` 파라미터가 올바르지 않은 경우 결제 불가

스마트로 상점 아이디 설정에 따라 올바른 파라미터 값이 정해져 있습니다. 만약 해당 상점 아이디 설정과 다른 파라미터가 입력될 경우엔 에러 알림 팝업이 노출되며 결제를 더이상 진행할 수 없습니다.

빌링키 발급시 유의사항

빌링키 발급 창에서는 언어 설정 미지원

스마트로는 결제창 언어로 한글과 영어를 선택할 수 있도록 지원하지만, 빌링키 발급 창에서는 한글만 지원합니다.

구매자 식별값 `customer.customerId`는 필수 입력

스마트로는 빌링키 발급시 구매자를 식별할 수 있는 고유 번호인 customer.customerId를 필수로 입력 받고 있으며, 입력 길이는 20자로 제한됩니다. 이는 간편결제시에도 마찬가지입니다.

본인인증 프로세스 존재

스마트로는 다른 PG사와는 다르게 빌링키 발급시 휴대폰 본인인증 프로세스가 존재합니다. 단, 한 번 인증 받은 “구매자”는 다시 인증 받을 필요가 없는데 이 “구매자”를 식별하기 위해 위에 언급 한 customerId가 사용되고 있습니다.

즉, 기존에 빌링키 발급시 사용한 customerId를 재사용하면 휴대폰 본인인증 프로세스가 생략되지만, 새로운 customerId로 빌링키 발급을 시도하면 휴대폰 본인인증 후 빌링키 발급이 진행됩니다.

에스크로 결제시 유의사항

에스크로 결제시 카드사/가상계좌 은행 다이렉트 호출 불가능

스마트로는 에스크로 결제시 카드사 다이렉트 호출 및 가상계좌 은행 다이렉트 호출이 불가능합니다. 만약 에스크로 결제시 아래와 같이 다이렉트 호출을 할 경우 결제창이 호출되지 않으니 유의하시기 바랍니다.

V2 에스크로 + 카드사 다이렉트 호출

PortOne.requestPayment({
  pgProvider: "SMARTRO_V2",
  payMethod: "CARD",
  totalAmount: 50000,
  isEscrow: true, // 에스크로 결제
  card: {
    cardCompany: "BC_CARD", // 카드사 다이렉트 호출
    installment: {
      monthOption: {
        fixedMonth: 5,
      },
    },
  },
});

V2 에스크로 + 가상계좌 다이렉트 호출

PortOne.requestPayment({
  pgProvider: "SMARTRO_V2",
  payMethod: "VIRTUAL_ACCOUNT",
  totalAmount: 50000,
  isEscrow: true, // 에스크로 결제
  virtualAccount: {
    bankCode: "SHINHAN_BANK", // 은행 다이렉트 호출
  },
});

에스크로 + 계좌이체 결제시 현금영수증 자동 입력 불가능

스마트로는 계좌이체 결제시 결제창에 자동 입력 될 현금영수증 정보(cashReceiptType: 현금영수증 유형, customerIdentifier: 현금영수증 식별 값)를 파라미터로 전달할 수 있습니다. 단, 에스크로 결제시에는 전달이 불가능합니다. 만약 에스크로 + 계좌이체 결제시 아래와 같이 현금영수증 정보를 전달할 경우 결제창이 호출되지 않으니 유의하시기 바랍니다.

V2 에스크로 + 계좌이체 + 현금영수증 정보 전달

PortOne.requestPayment({
  pgProvider: "SMARTRO_V2",
  totalAmount: 50000,
  payMethod: "TRANSFER", // 계좌이체 결제
  isEscrow: true, // 에스크로 결제
  transfer: {
    // 현금영수증 정보 전달
    cashReceiptType: "company",
    customerIdentiifer: "1178178260",
  },
});

기타 유의사항

주문 번호에 특수문자 입력 불가능

스마트로는 주문 번호(paymentId)에 특수문자를 허용하고 있지 않습니다. 따라서 결제창에서 일반결제를 할때와 발급 된 빌링키로 API를 통해 재결제를 하는 경우 숫자, 문자(알파벳 소문자와 대문자) 또는 그 조합으로 이루어진 주문 번호를 사용해주세요.

주문 번호 40자 길이 제한

스마트로는 주문 번호(paymentId)가 최대 40자를 넘을 수 없습니다. 40자가 넘을 경우 40자까지 잘려서 저장되기 때문에 유의 바랍니다.

결제 통화 파라미터 제어 불가능

스마트로는 상점 아이디 설정에 따라 사용 가능한 통화가 자동으로 정해지는 방식입니다. 따라서 다른 PG사와는 달리 currency 파라미터로 결제 통화를 설정할 수 없습니다.

단, 스마트로가 지원하지 않는 화폐(KRW와 USD를 제외 한 값)를 전달할 경우 “스마트로가 지원하지 않는 화폐입니다”라는 에러가 발생하며 결제를 진행할 수 없으니 유의 바랍니다.

제공 기간은 시작 날짜와 종료 날짜를 모두 입력해야 함

스마트로는 결제창 내 서비스 제공 기간을 노출시킬 수 있도록 offerPeriod 파라미터를 optional로 제공하고 있습니다. 단, 시작 날짜(from)와 종료 날짜(to)를 모두 입력해야 결제창에 정상적으로 노출됩니다.

현금성 결제시 `cashReceiptType`값에 따라 `customerIdentifier` 입력 정책이 달라짐

스마트로의 경우 현금성 결제시, bypass 파라미터에 현금영수증 발급 정보를 아래와 같이 전달할 수 있습니다.

...중략
bypass: {
  cashReceiptType: 'corporate', // 현금영수증 발급 유형
  customerIdentifier: '1178178260' // 현금영수증 발행 대상 식별 정보
}

이때 전달하는 cashReceiptType 파라미터 값에 따라 customerIdentifier 파라미터 입력 정책이 아래와 같이 달라지기 때문에 주의가 요구됩니다.

cashReceiptType	customerIdentifier
미입력	입력 불가(결제창에서 입력)
anonymous	입력 불가(결제창에서도 입력 불가)
personal	핸드폰 번호, 주민등록번호, 국세청 현금영수증 카드 번호 중 1개 필수 입력
corporate	사업자 등록번호 필수 입력

만약 cashReceiptType anonymous 또는 입력하지 않은 상태로 customerIdentifier를 입력하거나 cashReceiptType이 personal 또는 corporate인데 customerIdentifier를 입력하지 않으면 에러가 리턴되면서 결제창이 호출되지 않습니다.