--- title: 엑심베이 description: 엑심베이 결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. - V2 결제 모듈을 사용하시려면 엑심베이 신모듈로 연동하셔야 합니다. ## 해외결제 차지백 웹훅 등록 - 해외결제 차지백 웹훅을 수신하기 위해서는 엑심베이에 웹훅 URL로 `https://tx-gateway-service.prod.iamport.co/eximbay-v2`를 등록해 주셔야 합니다. - 웹훅 URL을 등록하신 후 받으신 웹훅 시크릿 키를 채널 정보에 입력해 주세요. ## 가능한 결제수단 엑심베이의 경우 포트원의 결제수단 구분과 상관없이 MID에 설정된 여러 결제수단을 표시할 수 있습니다. `payMethod`를 생략하고, 특정 결제수단만을 노출할 경우 `bypass.eximbay_v2`를 사용해야 합니다. - MID에 설정된 기본 결제수단을 전부 표시하려면 `bypass.eximbay_v2.payment`를 생략해야 합니다. - 특정 결제수단을 단독으로 표시하려면 `bypass.eximbay_v2.payment.payment_method`를 설정합니다. - 일부 결제수단만을 표시하려면 `bypass.eximbay_v2.payment.multi_payment_method`에 결제수단 목록을 전달합니다. - 엑심베이의 결제수단 코드는 포트원 코드와 상이하므로, [EXIMBAY Docs](https://developer.eximbay.com/eximbay/api_sdk/code-organization.html#paymentCode)에서 확인 후 입력해야 합니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 엑심베이 채널 사용을 명시해주세요. 엑심베이 기준으로 작성한 예제 코드는 아래와 같습니다.
```javascript import * as PortOne from "@portone/browser-sdk/v2"; function requestPayment() { PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. paymentId: `payment${crypto.randomUUID()}`, orderName: "PortOne Purchase", totalAmount: 100, // 1 USD currency: "USD", customer: { fullName: "PortOne", email: "test@example.com", }, }); } ```
### 주요 파라미터 - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string **채널 키** 콘솔에서 채널 연동 시 생성된 채널 키입니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** - ISO 4217 통화 코드 - [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - locale?: Locale **결제창 언어** - `KO_KR`: 한국어 - `EN_US`: 영어 - `JA_JP`: 일본어 - `ZH_CN`: 중국어 (중국 본토) - `ZH_TW`: 중국어 (대만) - `TH_TH`: 타이어 - `VI_VN`: 베트남어 - customer?: object **고객 정보** 엑심베이의 경우 구매자 성명과 이메일은 필수 입력 항목입니다. - customerId?: string **구매자 고유 ID** - fullName?: string **구매자 전체 이름** `fullName`과 `firstName` / `lastName`이 모두 입력된 경우 `fullName`으로 기록됩니다. - firstName?: string **구매자 이름** `firstName`을 입력하는 경우 `lastName`도 필수로 입력해야 합니다. `fullName`이 없고, `firstName`과 `lastName`이 존재하는 경우 `{firstName} {lastName}`으로 저장됩니다. - lastName?: string **구매자 성** `lastName`을 입력하는 경우 `firstName`도 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일 주소** 결제 완료 메일이 발송됩니다. - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbay\_v2?: object **엑심베이 특수 파라미터** - payment?: object - payment\_method?: string **결제수단 단독 노출** 엑심베이의 결제수단 코드는 포트원 코드와 상이하므로, [EXIMBAY Docs](https://developer.eximbay.com/eximbay/api_sdk/code-organization.html#paymentCode)에서 확인 후 입력해야 합니다. - multi\_payment\_method?: string\[] **결제수단 노출 목록** 여러 결제수단을 노출합니다. - merchant?: object - shop?: string **상점명** - partner\_code?: string **파트너 코드** - tax?: object - receipt\_status?: string **현금영수증 발급 여부** - `Y`: 발급 - `N`: 미발급 네이버페이 결제 시 필수 입력이며, 계좌이체 사용 시에는 반드시 `Y`로 입력해야 합니다. - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unit\_price?: string **단가 (음수 가능)** - ship\_to?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **수신인의 성을 제외한 이름** - last\_name?: string **수신인의 성** - phone\_number?: string **수신인 전화번호** - postal\_code?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - bill\_to?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **청구 카드 명의자의 성을 제외한 이름** - last\_name?: string **청구 카드 명의자의 성** - phone\_number?: string **청구 카드 명의자의 전화번호** - postal\_code?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** - settings?: object - call\_from\_app?: string **모바일 앱 내에서 결제를 연동할 경우 설정** - `Y`: 모바일 앱 환경인 경우 - `N`: 모바일 앱 환경이 아닌 경우 - issuer\_country?: string **해외 결제 가맹점에서 국내 결제를 사용할 경우 `KR`** - virtualaccount\_expiry\_date?: string **입금 만료 일자 (yyyyMMddHH)** ## SDK 빌링키 발급 및 결제 요청하기 엑심베이의 경우 빌링키 발급과 동시에 최초 결제가 일어나며, `requestIssueBillingKeyAndPay` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 엑심베이 채널 사용을 명시해주세요. 엑심베이 기준으로 작성한 예제 코드는 아래와 같습니다.
```javascript import * as PortOne from "@portone/browser-sdk/v2"; function issueBillingKeyAndPay() { PortOne.requestIssueBillingKeyAndPay({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. paymentId: `payment${crypto.randomUUID()}`, orderName: "PortOne Recurring Payment", totalAmount: 100, // 1 USD currency: "USD", customer: { fullName: "PortOne", email: "test@example.com", }, }); } ```
### 주요 파라미터 - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string **채널 키** 콘솔에서 채널 연동 시 생성된 채널 키입니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** - ISO 4217 통화 코드 - [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - locale?: Locale **결제창 언어** - `KO_KR`: 한국어 - `EN_US`: 영어 - `JA_JP`: 일본어 - `ZH_CN`: 중국어 (중국 본토) - `ZH_TW`: 중국어 (대만) - `TH_TH`: 타이어 - `VI_VN`: 베트남어 - customer?: object **고객 정보** 엑심베이의 경우 구매자 성명과 이메일은 필수 입력 항목입니다. - customerId?: string **구매자 고유 ID** - fullName?: string **구매자 전체 이름** `fullName`과 `firstName` / `lastName`이 모두 입력된 경우 `fullName`으로 기록됩니다. - firstName?: string **구매자 이름** `firstName`을 입력하는 경우 `lastName`도 필수로 입력해야 합니다. `fullName`이 없고, `firstName`과 `lastName`이 존재하는 경우 `{firstName} {lastName}`으로 저장됩니다. - lastName?: string **구매자 성** `lastName`을 입력하는 경우 `firstName`도 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일 주소** 결제 완료 메일이 발송됩니다. - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbay\_v2?: object **엑심베이 특수 파라미터** - payment?: object - payment\_method?: string **결제수단 단독 노출** 엑심베이의 결제수단 코드는 포트원 코드와 상이하므로, [EXIMBAY Docs](https://developer.eximbay.com/eximbay/api_sdk/code-organization.html#paymentCode)에서 확인 후 입력해야 합니다. - multi\_payment\_method?: string\[] **결제수단 노출 목록** 여러 결제수단을 노출합니다. - merchant?: object - shop?: string **상점명** - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unit\_price?: string **단가 (음수 가능)** - ship\_to?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **수신인의 성을 제외한 이름** - last\_name?: string **수신인의 성** - phone\_number?: string **수신인 전화번호** - postal\_code?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - bill\_to?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **청구 카드 명의자의 성을 제외한 이름** - last\_name?: string **청구 카드 명의자의 성** - phone\_number?: string **청구 카드 명의자의 전화번호** - postal\_code?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** ## API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제 요청 시 `POST /payments/{paymentId}/billing-key` API를 호출해야 합니다. 엑심베이 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts const response = await axios({ url: `https://api.portone.io/payments/${paymentId}/billing-key`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { billingKey: "billing-key-1", // SDK 빌링키 발급 및 결제 시 발급받은 빌링키 orderName: "PortOne Recurring Payment", customer: { name: { full: "PortOne", }, email: "test@example.com", }, amount: { total: 100, // 1 USD }, currency: "USD", locale: "KO_KR", }, }); ```
### 주요 파라미터 - paymentId: string **결제 주문 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - URL path에 포함하여 요청해야 합니다. - billingKey: string **빌링키 결제에 사용할 빌링키** - orderName: string **주문명** - amount: object **결제 금액** `vat`와 `taxFree` 파라미터는 지원하지 않습니다. - total: number **총 결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화** - [ISO 4217 통화 코드](https://en.wikipedia.org/wiki/ISO_4217) - customer: object **고객 정보** 엑심베이의 경우 고객 이름과 이메일은 필수 입력 항목입니다. - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber?: string **구매자 연락처** - email: string **구매자 이메일** - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbayV2?: object **엑심베이 특수 파라미터** - merchant?: object - shop?: string **상점명** - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unitPrice?: string **단가 (음수 가능)** - shipTo?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **수신인의 성을 제외한 이름** - lastName?: string **수신인의 성** - phoneNumber?: string **수신인 전화번호** - postalCode?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - billTo?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **청구 카드 명의자의 성을 제외한 이름** - lastName?: string **청구 카드 명의자의 성** - phoneNumber?: string **청구 카드 명의자의 전화번호** - postalCode?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** ## API 빌링키 예약/반복 결제 요청하기 예약 결제를 하기 위해서는 `POST /payments/{paymentId}/schedule` 를 이용하여 결제를 예약합니다. 엑심베이 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts const response = await axios({ url: `https://api.portone.io/payments/${paymentId}/schedule`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { payment: { billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키 orderName: "PortOne Recurring Payment", customer: { name: { full: "PortOne", }, email: "test@example.com", }, amount: { total: 100, // 1 USD }, currency: "USD", locale: "KO_KR", }, timeToPay: "2023-01-01T00:00:00+09:00", // 결제 예정 시점. RFC 3339 형식으로 입력해야 합니다. }, }); ```
### 주요 파라미터 - paymentId: string **결제 주문 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - URL path에 포함하여 요청해야 합니다. - payment: object **빌링키 결제 요청 입력정보** - billingKey: string **빌링키 결제에 사용할 빌링키** - orderName: string **주문명** - amount: object **결제 금액** `vat`와 `taxFree` 파라미터는 지원하지 않습니다. - total: number **총 결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화** - [ISO 4217 통화 코드](https://en.wikipedia.org/wiki/ISO_4217) - customer: object **고객 정보** 엑심베이의 경우 고객 이름과 이메일은 필수 입력 항목입니다. - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber?: string **구매자 연락처** - email: string **구매자 이메일** - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbayV2?: object **엑심베이 특수 파라미터** - merchant?: object - shop?: string **상점명** - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unitPrice?: string **단가 (음수 가능)** - shipTo?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **수신인의 성을 제외한 이름** - lastName?: string **수신인의 성** - phoneNumber?: string **수신인 전화번호** - postalCode?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - billTo?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **청구 카드 명의자의 성을 제외한 이름** - lastName?: string **청구 카드 명의자의 성** - phoneNumber?: string **청구 카드 명의자의 전화번호** - postalCode?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** - timeToPay: string **결제 예정 시점** ## 유의사항 ### 공통 - `customer.name` 및 `customer.email`은 필수 입력 항목입니다. - 해외카드 결제를 제외하고 `products`를 필수로 입력해야 합니다. 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. - `products` 입력 시 `link`를 필수로 입력해야 합니다. ### SDK 결제 / 빌링키 발급 및 결제 요청 - 네이버페이 포인트로 결제할 경우에는 `bypass.eximbay_v2.tax` 내용을 모두 입력해야 합니다. - 계좌이체 사용 시에는 현금영수증 발급을 위해 반드시 `bypass.eximbay_v2.tax.receipt_status`를 `Y`로 입력해야 합니다. - `bypass.eximbay_v2.payment_method`에 일본 편의점 결제를 지정할 경우 `customer.phoneNumber`을 필수로 입력해야 합니다. - 아래 결제수단의 경우 사용이 제한되므로 결제 연동 시 유의해 주시기 바랍니다. - 가상계좌(`P305`) : 호환성 이슈로 추후 지원 예정 - Klarna(`P197`) : 엑심베이 정책에 따라 신규 결제 사용 불가 - 모바일 앱 내에서 결제를 연동할 경우 `appScheme` 파라미터를 설정하고 `bypass.eximbay_v2.settings.call_from_app` 파라미터를 "Y"로 설정해야 합니다. - 엑심베이의 경우 결제창을 닫은 이후에 결제가 성공 처리될 수 있습니다. 웹훅을 연동하여 결제 실패 상태에서 결제 성공 상태로 바뀌는 경우를 처리해야 합니다.