Unifi Pay 연동 가이드: 크로스보더 결제 API 및 PG 연동 문서

이 문서는 Unifi Pay Direct 이용 가이드입니다. Direct는 사용자가 별도의 사전 심사 없이 직접 연동 설정을 진행할 수 있는 스마트 컨트랙트 프로그램입니다. 본 가이드에서는 프로그램 연동 설정부터 결제, 정산, 환불 송금 보조 기능, 계정 해지 및 지원 환경까지 전체 이용 흐름을 안내합니다.

이미 별도 절차를 거쳐 온보딩이 완료된 Classic 가맹점은 본 가이드의 대상이 아니므로, 관련 문의는 담당자에게 별도로 요청해 주세요.

화면을 따라 하는 콘솔 사용 가이드

가입부터 결제 링크 공유까지 5단계 스크린샷으로 안내합니다

콘솔 사용 가이드 보기

연동 설정 절차

콘솔 가입부터 API Key 발급까지 직접 설정

정산 및 결제 흐름

스마트 컨트랙트를 통한 즉시 정산 구조와 결제 링크·API 연동 방식

환불(송금 보조 기능)

판매자가 구매자에게 직접 송금할 수 있도록 기능 지원

탈퇴 및 해지

기술지원 채널을 통한 계정 해지 요청

지원 환경

지원 코인, 네트워크 등 환경 정보

1. Unifi Pay Direct란

Unifi Pay Direct는 사용자가 별도의 사전 심사 없이 직접 연동 설정을 진행할 수 있는 스마트 컨트랙트 프로그램입니다.

이용 대상	사업자등록번호 없이 개인·개인사업자·법인 등이 이용 가능. 단, 이용약관과 이용정책 및 지원 환경에 따른 제한이 적용될 수 있습니다.
연동 설정	콘솔에서 사용자가 직접 연동 설정
정산 방식	결제 즉시 스마트 컨트랙트에 따라 사용자가 등록한 정산 지갑으로 결제 대금이 즉시 분배됩니다.
수수료	거래 금액의 1%가 스마트 컨트랙트에 따라 Protocol Fee로 자동 분배됩니다.
결제 수단	Unifi Wallet에서 지원하는 스테이블코인(`USDT`/`JPYC`) 중 선택(스토어별로 하나 또는 두 자산을 모두 설정 가능하며, `IDRP`는 순차적으로 지원 예정)
연동 방식	결제 링크 생성 기능(No-code) 또는 API 연동 중 선택
환불(송금 보조 기능)	기존 결제를 취소하는 방식이 아니라, 판매자가 구매자에게 직접 송금하는 보조 기능을 제공
페이백 프로모션	적용 대상에서 제외

2. 셀프 연동 설정 절차

콘솔 가입부터 결제 시작까지 사용자가 직접 연동 설정을 진행할 수 있습니다.

1

콘솔 가입

2

판매자 정보 등록

3

정산 지갑 등록

4

스토어 설정

5

API 키 발급 (선택)

✓

연동 완료

1

콘솔 가입

별도의 사전 심사 없이 약관 동의 후 가입할 수 있으며, 가입과 동시에 Owner 권한이 자동으로 부여됩니다.

2

판매자 정보 등록

사업 형태(개인/개인사업자/법인/기타), 서비스명, 서비스 URL(선택), 운영 국가를 입력하고 필수 확인·동의 항목 5개와 이용정책(AUP)에 동의합니다. App ID는 시스템 내부에서 사용하는 식별자로 가입 시 자동으로 부여되며, 이 단계에서 직접 입력하는 항목이 아닙니다. 내부 식별자이므로 콘솔 화면에는 표시되지 않습니다.

3

정산 지갑 등록

결제 대금은 Kaia Mainnet 지갑으로만 수령할 수 있습니다. 지원 결제 수단인 USDT와 JPYC가 Kaia 블록체인을 기반으로 처리되므로, 정산 지갑도 Kaia Mainnet 주소여야 합니다. 결제 대금을 수령하려면 정산 지갑 등록이 필수이며, 아래 두 가지 방식 중 하나를 선택할 수 있습니다. 잘못된 지갑 주소를 등록하면 정산이 정상적으로 처리되지 않거나 자산을 복구하기 어려울 수 있으므로, 등록 전에 지갑 주소와 네트워크를 반드시 확인해 주세요.

환불 송금 기능 이용 시 유의사항
환불 송금 보조 기능은 정산 지갑 등록 방식과 관계없이 Unifi Wallet을 통해서만 이용할 수 있습니다. 외부 지갑을 정산 지갑으로 등록한 경우에도 환불 송금 기능을 이용하려면 별도의 Unifi Wallet이 필요합니다. 환불을 실행하기 전에 해당 Unifi Wallet에 환불할 자산과 네트워크 수수료를 충당할 수 있는 잔액을 준비해 주세요. 정산과 환불 송금은 서로 독립적으로 실행되는 별개의 기능입니다.

① Unifi Wallet 연결

Web3 이용이 익숙하지 않거나 별도의 지갑 관리가 부담스러운 경우 권장합니다. Unifi 계정으로 로그인한 후 Unifi Wallet을 연결하면 등록이 완료됩니다.

② 지갑 주소 직접 입력

Kaia Mainnet을 지원하는 외부 지갑 또는 거래소 지갑의 주소를 직접 입력합니다. Web3 지갑과 네트워크 개념에 익숙하고 지갑 주소를 직접 관리할 수 있는 사용자에게 적합합니다.

4

스토어 설정

콘솔에서 스토어 정보를 직접 생성하고 설정합니다. 스토어 생성 과정에서 구매자가 사용할 결제 수단인 USDT와 JPYC를 선택할 수 있습니다. 스토어별로 하나의 결제 수단만 선택하거나 두 결제 수단을 모두 설정할 수 있습니다.

5

API 키 발급 (선택)

자체 서비스에 API로 직접 연동하려는 경우 콘솔에서 API Key를 발급받습니다. 콘솔의 결제 링크 생성 기능만 이용하는 경우에는 API Key를 발급하지 않아도 됩니다.

가입 시 Unifi Console 이용약관과 Unifi Pay Console 이용약관에 동의해야 합니다. 또한 서비스 유형, 서비스명, URL, 운영 국가 등 기본 운영 정보를 변경할 때에는 필수 확인 항목과 이용정책(AUP)을 다시 확인하고 동의해야 합니다.

API 키 발급 상세

발급 위치	콘솔 > 연동 정보 탭
발급 종류	Production 환경에서 사용하는 API Key를 발급합니다. 발급 버튼을 누르면 API Key, Secret 및 발급 일시가 표시됩니다.
Secret 노출	Secret은 발급 화면에서만 전체 값이 1회 표시됩니다. 이후에는 마스킹된 값과 발급 일시만 확인할 수 있으며, 전체 값을 다시 조회할 수 없습니다.
분실 시	콘솔에서 셀프 재발급(Regenerate)할 수 있습니다. 재발급 시 이전 키는 사용 권한이 만료되어 신규 결제 링크 생성과 거래 내역 조회는 불가능하지만, 이전 키로 이미 생성된 결제 링크는 계속 정상 작동합니다.
발급 필수 여부	선택 사항입니다. 결제 링크 생성 기능만 이용하는 경우에는 발급하지 않아도 되며, API로 직접 연동할 때만 필요합니다.
콜백 도메인	최대 5개까지 직접 등록할 수 있습니다. 선택 항목이며 https:// 형식만 허용됩니다.
Preview(테스트) 환경	콘솔에서 별도의 API Key를 발급하지 않고 외부 Preview 콘솔을 통해 이용합니다.

3. 정산 방식

결제가 완료되는 즉시 스마트 컨트랙트가 실행되어, Protocol Fee 1%를 제외한 결제 대금이 판매자가 등록한 정산 지갑으로 직접 분배되는 구조로 별도의 정산 주기가 없습니다. 이렇게 분배되는 금액은 콘솔에서 실수령액(Net Revenue)으로 표시됩니다.

즉시 정산

결제가 완료되면 별도의 정산 주기 없이 등록된 정산 지갑으로 결제 대금이 즉시 분배됩니다. Protocol Fee 1%도 스마트 컨트랙트에 따라 결제와 동시에 자동 분배됩니다.

1

결제 완료

✓

정산 지갑으로 즉시 분배

3.1 결제 수단

1 주문 표시통화

구매자 화면에 주문 금액을 표시할 때 사용하는 통화입니다. USD와 JPY를 지원합니다. KRW는 현재 지원하지 않으며, 오픈 이후 추가 지원 여부를 검토할 예정입니다.

2 결제 수단 (실결제)

구매자가 실제 결제에 사용하는 자산입니다. Kaia 블록체인 기반 스테이블코인인 USDT와 JPYC를 지원하며, IDRP는 순차적으로 지원할 예정입니다.

3 정산 수단

구매자가 결제한 스테이블코인이 별도의 환전이나 교환 과정 없이 그대로 판매자의 정산 지갑으로 분배됩니다.

·정산 지갑은 Kaia Mainnet 지갑으로 한정됩니다.
·Unifi Reward 페이백 프로모션 적용 대상에서 제외됩니다.

결제 금액 한도

주문 통화 최소	0.01 USD / 1 JPY
주문 통화 최대	999,999 USD / 999,999,999 JPY
결제 통화 최소	0.01 USDT / 1 JPYC — 결제 금액을 결제 수단으로 환산한 결과가 최소 지원 수량보다 작은 경우에는 해당 결제 수단을 이용할 수 없습니다. (예시: 1 JPY 상품은 JPYC로 결제할 수 있지만, USDT로 환산하면 최소 결제 금액(0.01 USDT) 미만이 되어 USDT 결제가 지원되지 않을 수 있습니다.)
결제 통화 최대	9,999,999 USDT / 999,999,999 JPYC

4. 결제 처리 흐름

별도의 개발 없이 콘솔에서 결제 링크를 생성하거나, API를 자체 서비스에 직접 연동할 수 있습니다.

4.1 결제 링크 생성 기능

콘솔에서 금액을 입력해 결제 링크(Product Links)를 생성하면, 별도의 개발 없이 링크를 구매자에게 전달하여 결제를 받을 수 있습니다. 링크 생성 개수에는 제한이 없으며, 생성한 링크는 콘솔에서 목록으로 관리하거나 직접 만료 처리할 수 있습니다. 링크를 생성하면 QR 코드가 함께 발급되며, 구매자는 Unifi 앱의 스캐너로 이 QR 코드를 인식해 결제를 진행할 수 있습니다.

유효기간 — 각 결제 링크의 유효기간은 24시간 / 7일 / 30일(기본값) / 90일 중 하나로 설정할 수 있습니다. 설정한 유효기간이 지나면 링크가 자동으로 만료되며, 해당 링크를 통한 결제는 더 이상 진행할 수 없습니다.

1

콘솔

결제 링크 생성

금액과 필요한 정보를 입력하여 결제 링크를 생성합니다.

2

구매자

링크 접속

구매자가 전달받은 링크를 통해 결제 화면에 접속합니다.

3

Unifi Wallet

인증 및 결제

구매자가 Unifi Wallet을 통해 인증하고 결제를 진행합니다.

4

콜백 도메인

결과 수신 (선택)

등록한 콜백 도메인으로 결제 결과를 수신할 수 있습니다.

4.2 API 연동

자체 서비스에 Direct 기능을 직접 연결하려는 경우 API를 이용할 수 있습니다. Direct API를 통해 결제를 생성하고 거래 내역을 조회할 수 있습니다.

판매자 API 로 결제 링크 관리 (발급, 목록 조회, 강제 만료, 거래 내역 조회), 환불 (접수, 사전 조회, 단건 조회), 지갑 차단, 정산 내역과 결제 내역 조회, 스토어 목록 조회를 할 수 있습니다. 상세는 API 레퍼런스를 참고하세요.

1

Your Server → Unifi Pay

결제 생성

API를 호출하여 결제를 생성합니다.

2

Your Service

사용자 이동

응답으로 받은 startPageUrl로 구매자를 이동시킵니다.

3

Unifi Wallet

인증 및 결제

구매자가 Unifi Wallet을 통해 인증하고 결제를 진행합니다.

4

Your Service

결제 완료 및 복귀

결제가 완료되면 지정한 returnUrl로 구매자가 이동합니다.

5

Your Server

거래 내역 조회

Direct API를 통해 거래 내역을 조회할 수 있습니다.

결과 수신 (선택)

콜백 도메인을 등록한 경우 결제 결과를 콜백으로 수신할 수 있습니다.

API 버전 (v1 / v2)

Direct API는 v1과 v2 두 버전을 제공하고 있습니다. 신규로 연동을 진행하시는 파트너사는 반드시 최신 버전인 v2를 적용해 주시기를 바랍니다. 기존에 v1으로 연동하신 경우 당분간은 기존 버전을 그대로 사용하실 수 있습니다. 하지만 v1 서비스가 영구적으로 제공되는 것은 아니므로, 가급적 빠른 시일 내에 v2로 전환해 주시기를 권장해 드립니다. v1부터 제공해 온 API는 두 버전의 요청 및 응답 형식이 동일하며 호출 경로만 다릅니다. 다만 v1.6.0에서 신설된 API(결제 링크 목록 조회, 결제 링크 강제 만료, 결제 링크 거래 내역 조회, 결제 내역 조회, 정산 내역 cursor 조회, 스토어 목록 조회, Blacklist)는 v2 경로에서만 제공됩니다. 또한 인증에 사용하는 서명(Signature) 값에 호출 경로가 포함되므로, v2로 전환하실 때는 API 주소뿐만 아니라 서명을 생성하는 로직도 함께 수정해 주셔야 합니다. 호출 경로와 상세 규격은 API 레퍼런스를 참고해 주세요.

API를 직접 연동하지 않더라도 콘솔의 결제 링크 생성 기능을 통해 결제를 생성할 수 있습니다. 환불 접수는 콘솔 또는 환불 API 로 가능하며, 어느 경로든 접수 후 판매자가 본인의 Unifi Wallet 로 직접 서명해야 실행됩니다.

5. 환불(송금 보조 기능)

Direct의 환불은 기존 결제를 취소하거나 이미 정산된 결제 대금을 회수하는 방식이 아닙니다. 판매자가 구매자에게 새로운 송금 거래를 직접 실행하는 방식으로 처리됩니다.

환불 여부, 금액 및 조건은 판매자와 구매자 간 협의를 통해 결정하며, Unifi Pay는 해당 결정이나 협의 과정에 관여하지 않습니다.

처리 주체	판매자가 Unifi Pay 콘솔의 ‘환불 관리’ 메뉴에서 본인이 관리하는 Unifi Wallet로 직접 서명하여 송금을 실행합니다.
환불 가능 시점	환불 송금은 원결제의 블록체인 정산이 완료된 이후에 실행할 수 있습니다. 결제 직후 정산이 처리되는 짧은 시간(통상 수 초) 동안에는 환불 신청이 제한되며, 정산이 완료되면 정상적으로 실행할 수 있습니다.
API 제공 여부	콘솔 또는 환불 API 로 접수할 수 있습니다. 어느 경로든 처리 과정에서 판매자의 Unifi Wallet 서명이 필요하며, API 로 접수한 경우 응답의 startPageUrl 페이지에서 서명합니다.
환불 지갑	환불 송금 기능은 Unifi Wallet을 통해서만 이용할 수 있습니다. 외부 지갑을 정산 지갑으로 등록한 경우에도 별도의 Unifi Wallet이 필요합니다.
필요 잔액	환불을 실행하기 전에 Unifi Wallet에 환불할 자산과 네트워크 수수료를 충당할 수 있는 잔액이 있어야 합니다.
환불 주소 및 네트워크	원결제에 사용된 구매자 지갑 주소와 동일한 주소 및 네트워크로만 송금할 수 있습니다.
환불 금액	원결제 시 판매자가 수령한 스테이블코인의 수량을 기준으로 하며, 환율 변동 등에 따른 별도의 재산정은 이루어지지 않습니다. 실제 환불 수량은 판매자와 구매자 간 합의에 따라 판매자가 결정합니다.
환불 기준	Unifi Pay는 별도의 환불 기준이나 정책을 정하지 않습니다. 판매자와 구매자 간 협의가 완료된 건에 한하여 판매자가 직접 송금을 실행할 수 있는 보조 기능을 제공합니다.

Unifi Pay는 환불 자금을 보관하거나 회수하지 않으며, 판매자를 대신하여 환불 송금을 실행하지 않습니다.

6. 탈퇴 및 해지

콘솔에서 사용자가 직접 탈퇴하는 기능은 제공하지 않습니다. 이용 해지가 필요한 경우 기술지원 이메일 채널을 통해 요청해 주세요.

직접 탈퇴	미제공
해지 절차	기술지원 이메일로 해지 요청 → 요청 내용 확인 → 계정 비활성화 처리

7. 지원하는 환경

Unifi Pay에서 결제수단으로 사용하는 통화는 Kaia Blockchain 기반의 스테이블 코인입니다. 또한 연동 테스트 시 사용할 수 있는 Preview 환경을 제공합니다.

Preview 환경

Kairos Testnet (테스트넷)

Testnet

Preview 환경에서는 카이아 블록체인의 테스트넷인 Kairos 체인이 연동되며, 테스트 자금은 Faucet 서비스를 통해 확보할 수 있습니다.

Base URL API 연동용 https://app-api-pay.unifi.me

Console URL https://app-console.unifi.me

Preview 환경 테스트 시작하기

1

Preview 콘솔에 접속합니다

https://app-console.unifi.me 로 접속합니다. 가입·이용 절차는 Production 콘솔(console.unifi.me)과 동일하며, 이미 사용 중인 Unifi 계정으로 그대로 로그인하실 수 있습니다. 별도의 가입 신청이나 활성화 요청은 필요하지 않습니다.

2

테스트용 지갑 주소를 확인합니다

Preview 환경의 Unifi Wallet(https://app.unifi.me)에 Google 계정으로 로그인해 지갑 주소를 확인합니다. Preview와 Production은 환경이 분리되어 있어 같은 계정으로 로그인해도 지갑 주소가 서로 다릅니다. 아래 Faucet에는 이 Preview 지갑 주소를 입력해 주세요. Production 지갑 주소를 입력하면 테스트 자금이 Preview 지갑에 표시되지 않아 테스트에 사용하실 수 없습니다.

3

Faucet에서 테스트 자금을 받습니다

테스트 USDT — Kaia Faucet(https://www.kaia.io/ko/faucet)에서 위에서 확인한 Preview 지갑 주소로 받으실 수 있습니다.

테스트 JPYC — JPYC Faucet은 지갑을 연결하는 방식이라 Unifi Wallet 주소로 바로 받을 수 없습니다. 아래 순서로 진행해 주세요.

Kaia Wallet을 준비합니다. Chrome 웹 스토어에서 확장 프로그램으로 설치하거나 App Store·Google Play에서 앱으로 설치할 수 있습니다(공식 안내 https://www.kaiawallet.io). 설치 후 새 지갑을 만들고, 지갑 상단의 네트워크를 Kairos로 변경합니다.
Kaia Faucet(https://www.kaia.io/ko/faucet)에서 해당 Kaia Wallet 주소로 테스트 KAIA 토큰을 먼저 받습니다. 이후 JPYC를 받고 전송할 때 가스비로 사용됩니다. 1회 수령분이면 충분하며, 소모량은 JPYC 수령 약 0.003 KAIA · 전송 약 0.002 KAIA 수준입니다.
JPYC Faucet(https://faucet.jpyc.co.jp)에 접속해 Kaia Wallet에 로그인한 뒤 네트워크에서 Kaia Kairos Testnet을 선택합니다. 로그인한 지갑 주소가 자동으로 입력되며, 필요한 수량을 기입하면 Kaia Wallet으로 지급됩니다.
Kaia Wallet에 JPYC가 보이지 않으면 토큰 목록에서 토큰 추가 › Custom Token을 선택하고 Token Contract Address에 0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29(Kairos 테스트넷 JPYC 토큰의 컨트랙트 주소)를 입력해 주세요.
Kaia Wallet에서 위에서 확인한 Preview 지갑 주소로 JPYC를 전송하면 Preview 환경에서 사용하실 수 있습니다.

4

결제 링크를 만들어 테스트합니다

Preview 콘솔에서 Production 콘솔과 동일한 방법으로 결제 링크를 생성한 뒤, 앞서 받아 둔 테스트 USDT·JPYC로 실제 결제를 진행해 보시면 됩니다.

Production 환경

Kaia Mainnet (메인넷)

Mainnet

Production 환경에서는 카이아 블록체인의 메인넷인 Kaia 체인이 연동되며, 실 결제가 발생합니다.

Base URL API 연동용 https://api-pay.unifi.me

Console URL https://console.unifi.me

정산 지갑 및 환불 지갑은 Production 환경(Kaia Mainnet) 기준으로 한정하여 등록됩니다.

Preview와 Production은 로그인 세션이 각각 따로 관리됩니다. 같은 브라우저에서 두 환경을 번갈아 접속하면 앞서 로그인한 정보가 유효하지 않게 되어, 결제 화면에서 오류가 표시될 수 있습니다. 이 경우 화면에 안내되는 다시 로그인 절차를 진행하시면 이어서 이용하실 수 있습니다. 테스트와 실거래를 함께 진행하실 때는 브라우저를 나누어 사용하시면 번거로움을 줄일 수 있습니다.