Unifi Pay Direct API 레퍼런스

문서 버전 안내: 이 페이지는 최신 API v2 기준 문서입니다. API v1으로 연동 중인 파트너를 위한 기존 문서도 계속 제공됩니다. V1 문서 보기

Unifi Pay API를 연동하는 개발자를 위한 API 레퍼런스 입니다.

빠른 연동

SDK 없이 REST API만으로 결제 연동 완료

HMAC 보안

API 요청 시 HMAC 서명 인증 적용

Webhook 지원

비동기 Webhook으로 실시간 결제 상태 수신

AI 연동 가이드

AI 코딩 어시스턴트에 제공하면 API 연동 작업에 참고 자료로 활용할 수 있습니다.

PDF 다운로드 평문(txt) 보기

1 PDF 또는 평문(txt) 파일을 받습니다.

2 Claude Code, Codex CLI, Gemini CLI 등 AI 코딩 어시스턴트에 파일로 제공합니다.

3 "이 문서를 참고해서 결제 연동 코드를 작성해줘"처럼 요청합니다.

1. API 연동 다이어그램

결제 링크 발급 방식의 가맹점 서버·고객·Unifi Pay 간 데이터 흐름입니다.

1.1 결제 다이어그램

결제 링크 발급부터 Webhook 수신까지의 전체 흐름입니다.

동기 호출 (Sync)

응답 (Response)

비동기 Webhook (Async)

Your Server: apiKey와 HMAC Signature를 이용해 Unifi Pay에 결제 링크 발급을 요청합니다.

결제 링크: 발급받은 linkUrl을 고객에게 공유합니다. 공유 채널에는 제한이 없습니다.

Customer: 링크에 접속해 결제를 진행하면 결제 요청이 생성되고, 지갑 연결 및 서명으로 결제가 완료됩니다.

Webhook: 결제 링크 발급 시 callbackUrl을 등록한 경우에만 전송됩니다. PAID 시점에 1차, CONFIRMED 시점에 2차로 결제 결과를 비동기 전송합니다. 결제 결과를 전달받는 유일한 경로이므로 반드시 등록하십시오.

2. API 상세 소개

Base URL

Preview https://app-api-pay.unifi.me

Production https://api-pay.unifi.me

2.1 인증 (Authentication)

서버 간 API 요청은 기본적으로 HMAC 인증이 필수입니다. X-Authorization-Hmac 헤더에 서명값을 포함해야 합니다. X-Authorization-Hmac

기본 인증 규칙: 별도 표기가 없는 한 서버 간 API 는 모두 HMAC 인증이 기본입니다. 인증 방식이 다른 API(예: 무인증 공개 API)는 해당 API 에 별도로 표기합니다.

HMAC 생성 공식

Formula

BASE64(HMACSHA256(apiSecret, {HTTP_METHOD}{URI}{X-API-Key}{X-Timestamp}{REQUEST_BODY}))

REQUEST_BODY가 있는 경우

POST /api/seller/v2/payment/link

요청 예시

request header:
  X-API-Key:            "b6ef2f7c-3e74-438c-b456-689e821992be"
  X-Timestamp:          1773017787000
  X-Authorization-Hmac: "some-hmac-signature"
request body:
{
  "requestId": "REQ-20260304-0001",
  "storeId": "123",
  "serviceName": "MyShop",
  "itemName": "ITEM-GAME-001",
  "itemPrice": 12.34,
  "orderCurrencyCode": "USD",
  "returnUrl": "https://myshop.com/payment/returnUrl",
  "callbackUrl": "https://myshop.com/payment/callbackUrl",
  "expiresAt": "2026-08-31T00:00:00Z"
}

서명 생성

X-Authorization-Hmac = Base64(
  HmacSHA256(
    apiSecret,
    "POST"                                    ← HTTP_METHOD
    + "/api/seller/v2/payment/link"           ← URI
    + "b6ef2f7c-3e74-438c-b456-689e821992be" ← X-API-Key
    + "1773017787000"                         ← X-Timestamp
    + "{"requestId":"REQ-20260304-0001","storeId":"123","serviceName":"MyShop","itemName":"ITEM-GAME-001","itemPrice":12.34,"orderCurrencyCode":"USD","returnUrl":"https://myshop.com/payment/returnUrl","callbackUrl":"https://myshop.com/payment/callbackUrl","expiresAt":"2026-08-31T00:00:00Z"}"       ← REQUEST_BODY (공백 없이)
  )
)

REQUEST_BODY가 없는 경우

GET /api/seller/v2/payment/123

요청 예시

request header:
  X-API-Key:            "b6ef2f7c-3e74-438c-b456-689e821992be"
  X-Timestamp:          1773017787000
  X-Authorization-Hmac: "some-hmac-signature"

서명 생성

X-Authorization-Hmac = Base64(
  HmacSHA256(
    apiSecret,
    "GET"                                     ← HTTP_METHOD
    + "/api/seller/v2/payment/123"            ← URI
    + "b6ef2f7c-3e74-438c-b456-689e821992be" ← X-API-Key
    + "1773017787000"                         ← X-Timestamp
                                              ← REQUEST_BODY 없음 (생략)
  )
)

쿼리 파라미터가 있는 경우

GET /api/seller/v2/payment/settlement/transaction

요청 예시

request url:
  GET /api/seller/v2/payment/settlement/transaction?from=2026-03-01T00:00:00Z&to=2026-03-31T23:59:59Z&paymentType=PURCHASE&page=0&size=20

request header:
  X-API-Key:            "b6ef2f7c-3e74-438c-b456-689e821992be"
  X-Timestamp:          1773017787000
  X-Authorization-Hmac: "some-hmac-signature"

서명 생성

X-Authorization-Hmac = Base64(
  HmacSHA256(
    apiSecret,
    "GET"                                                  ← HTTP_METHOD
    + "/api/seller/v2/payment/settlement/transaction"       ← URI (쿼리스트링 제외)
    + "b6ef2f7c-3e74-438c-b456-689e821992be"              ← X-API-Key
    + "1773017787000"                                      ← X-Timestamp
                                                           ← REQUEST_BODY 없음 (생략)
  )
)

쿼리 파라미터 처리: 서명 대상 URI 에는 경로(path)만 포함하며, 쿼리스트링(? 이후)은 포함하지 않습니다. 쿼리스트링을 포함해 서명하면 인증에 실패합니다.

요청 헤더 파라미터

파라미터	타입	필수	설명
X-Authorization-Hmac	STRING	필수	생성된 HMAC 서명값. 모든 서버 간 API 요청에 필수입니다.
X-API-Key	STRING	필수	Unifi Pay에서 발급받은 apiKey.
X-Timestamp	STRING	필수	밀리초 단위 Unix 타임스탬프. 현재 시각과 5분 이상 차이 시 요청이 거부됩니다.

⚠️ 타임스탬프 유효 범위: X-Timestamp는 현재 서버 시각에서 5분 이내여야 합니다. 이 범위를 벗어나면 재전송 공격(Replay Attack) 방지를 위해 요청이 자동으로 거부됩니다.

서버 timestamp 조회

Unifi Pay 서버의 timestamp를 조회하여 서버 상태를 확인하고, 응답의 timestamp 값을 HMAC 서명에 활용합니다.

GET /api/v2/server/time

인증 방식: 이 API 는 무인증 공개 API 입니다. X-API-Key · X-Timestamp · X-Authorization-Hmac 헤더 없이 호출합니다. HMAC 서명에 사용할 timestamp 를 얻기 위한 API 이므로 위 기본 인증 규칙에서 제외됩니다.

응답 필드

필드 이름	타입	설명
timestamp	INTEGER(INT64)	서버의 timestamp 밀리초 단위 값

응답 예시

정상 응답 · 200 OK

{
  "timestamp": 1773017787000
}

오류 응답 · 500 Internal Server Error

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": ""
}

2.2 결제 링크 발급 API

고정된 금액과 상품의 결제 링크를 발급합니다. 응답으로 받은 링크를 고객에게 공유하면 별도 연동 없이 결제 페이지로 진입합니다.

POST /api/seller/v2/payment/link

요청 바디 파라미터

파라미터	타입	길이	필수	설명
requestId	STRING	64	필수	발급 요청에 대한 고유 식별자(멱등키). 영문·숫자·하이픈·언더스코어만 사용합니다. 동일한 requestId로 재요청하면 중복 발급으로 거부됩니다.
storeId	STRING	128	필수	요청자가 제공하는 가맹점 ID 정보.
serviceName	STRING	40	필수	링크 화면과 결제창에 노출될 서비스 또는 가맹점 정보.
itemName	STRING	100	필수	판매 상품의 이름(상품명).
itemPrice	DOUBLE	—	필수	판매 상품의 가격. 주문 통화 기준이며 0보다 커야 합니다.
orderCurrencyCode	STRING	8	필수	ISO 4217을 따르는 주문 통화 코드. USD 또는 JPY를 지원합니다.
returnUrl	STRING	2048	선택	결제 완료 후 사용자가 복귀할 URL. 지정하지 않으면 복귀 버튼 없이 결제를 진행합니다.
callbackUrl	STRING	2048	선택	결제 결과를 수신할 Webhook URL. 결제 링크 방식은 결제가 발생하기 전까지 거래 식별자가 생성되지 않아 상태 조회로 결과를 확인할 수 없으므로, 반드시 지정해 주십시오.
expiresAt	STRING	—	필수	결제 링크의 만료 시각. ISO-8601 형식이며 미래 시점이어야 합니다. 만료 후 링크에 접속하면 만료 오류로 응답합니다.

응답 필드

필드 이름	타입	설명
linkUrl	STRING	발급된 결제 링크 URL. 고객에게 공유합니다.
linkId	STRING	링크 식별자. 가맹점이 보관하며, 링크를 만료시킬 때는 콘솔의 결제 링크 목록에서 강제 만료 버튼을 사용합니다.

요청 / 응답 예시

요청 (JSON)

JSON

{
  "requestId": "REQ-20260304-0001",
  "storeId": "123",
  "serviceName": "MyShop",
  "itemName": "ITEM-GAME-001",
  "itemPrice": 12.34,
  "orderCurrencyCode": "USD",
  "returnUrl": "https://myshop.com/payment/returnUrl",
  "callbackUrl": "https://myshop.com/payment/callbackUrl",
  "expiresAt": "2026-08-31T00:00:00Z"
}

응답 (JSON)

JSON

{
  "linkUrl": "https://unifipay.example.com/pay/links/3f1d0a549c1e4f6a8a5b2f",
  "linkId": "3f1d0a549c1e4f6a8a5b2f"
}

💡 참고: 응답의 linkUrl을 고객에게 공유하면 별도 연동 없이 결제가 진행됩니다. requestId는 멱등키이므로 동일한 값으로 재요청하면 중복 발급이 거부됩니다.

📌 결제 링크의 API 버전 안내: 결제 건은 링크를 발급하는 시점이 아니라 고객이 링크에서 결제를 진행하는 시점에 생성되며, 이때 결제 건의 API 버전은 링크 발급에 사용한 버전을 따릅니다.

오류 응답

HTTP 상태	오류 코드	설명
400	BAD_REQUEST	유효하지 않은 입력 값 (형식 오류, 필수 값 누락, 과거 시점의 expiresAt 등)
401	UNAUTHORIZED	유효하지 않은 HMAC
403	FORBIDDEN	허용되지 않은 IP 혹은 Path
503	MAINTENANCE	점검 중
406	PAYMENT_INVALID_REQUEST	동일한 requestId로 재요청한 경우 또는 callbackUrl이 허용 목록에 없는 경우
406	PAYMENT_UNSUPPORTED_POLICY	지원하지 않는 주문 통화 또는 금액 정책 (orderCurrencyCode, itemPrice)
406	PAYMENT_STORE_INACTIVE	요청한 storeId가 ACTIVE 상태가 아닐 때
406	PAYMENT_WALLET_NOT_REGISTERED	정산 지갑 주소가 등록되지 않은 경우
500	INTERNAL_SERVER_ERROR	서버 내부 오류

2.3 결제 상태 확인 API

생성된 결제 건의 현재 상태를 확인합니다.

GET /api/seller/v2/payment/{transactionId}

응답 필드

필드 이름	타입	설명
transactionId	STRING	Unifi Pay에서 생성한 거래 번호.
orderId	STRING	Unifi Pay에서 생성한 주문 id. 결제 링크를 통한 거래는 LINK-{linkId}-{12문자 랜덤 문자열} 형식으로 발급됩니다.
storeId	STRING	요청자가 제공하는 가맹점 ID 정보.
serviceName	STRING	결제창에 노출될 서비스 또는 가맹점 정보.
status	STRING	CREATED결제 생성 완료 PENDING결제 진행 중 PAID결제 성공 CONFIRMED정산 완료 (종결) FAILED결제 실패 (종결) CANCELED결제 취소 (종결)
failType	STRING	status가 FAILED일 때 설정됩니다. WALLET_PURCHASE_BLOCKCHAIN_FAILEDunifi wallet에서 blockchain 출고 과정 중 실패 WALLET_PURCHASE_INSUFFICIENT_BALANCE사용자 지갑의 잔고 부족 PAYMENT_PURCHASE_BLACKLISTED사용자의 지갑이 payment 블랙리스트에 포함되어 실패 UNKNOWN결제 과정 중 알 수 없는 오류
items Array — 결제 상품 목록 최대 1건
↳ name	STRING	판매 상품의 식별 정보.
↳ price	DOUBLE	판매 상품의 가격.
orderCurrencyCode	STRING	ISO 4217를 따르는 주문 통화 코드 (USD, JPY).
orderAmount	DOUBLE	주문한 금액.
payCurrencyCode	STRING	결제한 스테이블 코인 종류.
payAmount	DOUBLE	결제된 금액.
blockchainTxId	STRING	블록체인 트랜잭션 해시. 블록체인 확정 이후(CONFIRMED)이거나, 블록체인 네트워크에 전파된 후 실패(FAILED)한 경우에 반환됩니다.
blockchainNetworkFee	DOUBLE	블록체인 네트워크 수수료. 블록체인 확정 이후(CONFIRMED) 및 네트워크 전파 후 실패(FAILED) 시점에 실제로 소모된 수수료 금액이 반환됩니다. (Unifi가 전액 대납하여 사용자 부담은 없습니다.)

📌 v1·v2 혼용 안내: PAID 상태는 결제 건이 v2로 생성되고 v2 API로 조회·수신하는 경우에만 노출됩니다. 생성 또는 조회 중 하나라도 v1이면 PAID 없이 기존과 동일하게 CONFIRMED로 안내됩니다.

⚠️ PAID 시점 응답 안내: PAID 시점에는 blockchainTxId·blockchainNetworkFee가 반환되지 않습니다. 결제 금액(payAmount)은 CONFIRMED 시점에 확정되므로, 금액·블록체인 정보는 CONFIRMED 이후 조회한 값을 사용하시기 바랍니다.

응답 예시

JSON

{
  "transactionId": "<uuid>",
  "orderId": "<orderId>",
  "storeId": "<storeId>",
  "serviceName": "<serviceName>",
  "items": [
    {
      "name": "ITEM-GAME-001",
      "price": 50000
    }
  ],
  "status": "CONFIRMED",
  "failType": null,
  "countryCode": "KOR",
  "payAmount": 49000,
  "payCurrencyCode": "USDT",
  "orderAmount": 50000,
  "orderCurrencyCode": "USD",
  "blockchainTxId": "0x4fce0d72ff7f4b9f4ba0cf58d30119924bea3811d85a830c762e1d87b3e1ee17",
  "blockchainNetworkFee": 0.00253778
}

CONFIRMED

결제가 확정되고 정산까지 완료되어 종결된 상태입니다.

FAILED

결제가 실패한 상태입니다.

오류 응답

HTTP 상태	오류 코드	설명
400	BAD_REQUEST	유효하지 않은 입력 값
401	UNAUTHORIZED	유효하지 않은 HMAC일 경우
403	FORBIDDEN	허용되지 않은 IP 혹은 Path 일 경우
503	MAINTENANCE	점검 중일 경우
406	PAYMENT_TRANSACTION_NOT_FOUND	유효하지 않은 transactionId
500	INTERNAL_SERVER_ERROR	서버 내부 오류

2.4 결제 Webhook

결제 건에 대한 처리 결과를 비동기로 수신합니다. Webhook은 PAID 시점에 1차, CONFIRMED 시점에 2차로 총 2회 발송됩니다. 두 Webhook 모두 동일한 transactionId로 전송되므로 중복 수신에 대비해 멱등하게 처리해 주십시오. 1차(PAID) 수신 시점부터 결제 완료 화면으로 전환할 수 있습니다.

POST <가맹점 callbackUrl>

Webhook 바디 필드

필드 이름	타입	필수	설명
transactionId	STRING	필수	Unifi Pay에서 생성한 거래 번호.
orderId	STRING	필수	Unifi Pay에서 생성한 주문 id. 결제 링크를 통한 거래는 LINK-{linkId}-{12문자 랜덤 문자열} 형식으로 발급되며, 고객이 결제 링크에서 결제를 진행한 시점에 결정됩니다.
status	STRING	필수	결제 처리 결과. `PAID`: 결제 성공 (1차 Webhook), `CONFIRMED`: 정산 완료 (2차 Webhook), `FAILED`: 실패, `CANCELED`: CREATED 상태로 약 30분 이상 유지되거나 사용자가 결제창을 이탈한 경우 취소.
type	STRING	필수	거래 유형. 환불을 API로 제공하지 않으므로 항상 `PURCHASE`입니다.

요청 예시 (JSON) — 1차 Webhook (PAID)

JSON

{
  "transactionId": "<uuid>",
  "orderId": "LINK-3f1d0a549c1e4f6a8a5b2f-a1b2c3d4e5f6",
  "status": "PAID",
  "type": "PURCHASE"
}

요청 예시 (JSON) — 2차 Webhook (CONFIRMED)

JSON

{
  "transactionId": "<uuid>",
  "orderId": "LINK-3f1d0a549c1e4f6a8a5b2f-a1b2c3d4e5f6",
  "status": "CONFIRMED",
  "type": "PURCHASE"
}

📡 응답 필수 안내: 가맹점 서버는 Webhook 수신 후 반드시 HTTP 200 OK 응답 코드를 반환해야 합니다.

💡 상세 조회: Webhook은 최소한의 정보만 전달합니다. 결제 상세 정보는 Webhook 수신 후 2.3 결제 상태 확인 API를 호출하여 조회하세요.

재시도 정책

가맹점 서버에서 5xx 오류 또는 응답이 없을 경우, 아래 정책에 따라 재전송됩니다.

순서	재시도 시점
1차 재시도	3초 후
2차 재시도	30초 후
3차 재시도	10분 후
4차 재시도	1시간 후
5차 재시도	3시간 후

2.5 환불 (콘솔 처리)

환불은 API로 제공되지 않습니다. 지갑 서명이 필요한 처리이므로 콘솔에서만 실행할 수 있습니다.

처리 방법: 판매자가 Unifi Pay 콘솔의 환불 관리 메뉴에서 본인 명의의 Unifi Wallet으로 직접 서명하여 실행합니다.

💡 참고: 환불은 원결제가 CONFIRMED 상태인 경우에만 진행할 수 있습니다.

연동 시 참고 사항

항목	설명
환불 Webhook	제공하지 않습니다. 환불 처리 결과는 Webhook으로 전송되지 않으므로 결제 내역 API로 조회해야 합니다.
환불 내역 조회	아래 2.6 결제 내역 API에서 `paymentType=REFUND` 로 조회합니다.
원결제 연결	환불 건의 `originTransactionId` 가 원결제의 `transactionId` 를 가리킵니다.

💡 참고: 환불 지갑·환불 금액 기준·주소 및 네트워크 조건 등 환불 정책은 이용 가이드 5. 환불(송금 보조 기능)을 참고하시기 바랍니다.

2.6 결제 내역 API

결제, 환불 내역을 확인합니다.

GET /api/seller/v2/payment/settlement/transaction

요청 쿼리 파라미터

파라미터	타입	필수	설명
from	STRING	조건부	조회 시작일 (capturedAt 기준, ISO 8601 UTC. 예시 2026-03-01T00:00:00Z). transactionId/settlementId 미지정 시 필수이며, to보다 이전 시점 설정 필수.
to	STRING	조건부	조회 종료일 (capturedAt 기준, ISO 8601 UTC. 예시 2026-03-31T23:59:59Z). transactionId/settlementId 미지정 시 필수이며, 조회 기간은 최대 90일까지 허용.
paymentType	STRING	선택	결제 타입 필터 (PURCHASE / REFUND). 미지정 시 전체
transactionId	STRING	선택	Unifi Pay에서 생성한 거래 번호. from/to/settlementId 미지정 시 필수.
settlementId	STRING	선택	Unifi Pay 지급 명세서 ID 정보. from/to/transactionId 미지정 시 필수.
page	INTEGER	선택	페이지 번호 (0부터 시작, 기본값: 0)
size	INTEGER	선택	페이지 크기 (기본 50, 1 이상 100 이하)

응답 필드 (200 OK)

필드 이름	타입	필수	설명
content	List	필수	결제 데이터 목록
↳ partnerCorpName	STRING	필수	법인명 (EN)
↳ storeId	STRING	선택	가맹점 ID 정보
↳ orderId	STRING	필수	거래에 대한 ID 정보
↳ itemName	STRING	필수	상품의 식별 정보
↳ serviceName	STRING	선택	서비스 또는 가맹점명 (EN)
↳ orderCountryCode	STRING	필수	구매자 국가 코드
↳ orderCurrencyCode	STRING	필수	ISO 4217를 따르는 주문 통화 코드
↳ orderAmount	DOUBLE	필수	주문 금액
↳ createdAt	INSTANT	필수	주문 결제 요청 일시
↳ transactionId	STRING	필수	Unifi Pay에서 생성한 거래 번호.
↳ blockchainTxId	STRING	필수	KaiaScan TxID
↳ paymentType	STRING	필수	결제: PURCHASE / 환불: REFUND
↳ originTransactionId	STRING	선택	환불 시 원 거래 번호 (REFUND인 경우 필수, PURCHASE인 경우 Null)
↳ status	STRING	필수	CONFIRMED 고정 (CONFIRMED건만 조회)
↳ finalizedAt	INSTANT	필수	주문 결제 최종 상태 일시
↳ capturedAt	INSTANT	필수	주문 결제 완료 일시
↳ failType	STRING	선택	주문 결제 실패 사유
↳ payCurrencyCode	STRING	필수	실 결제 통화 USDT
↳ payAmount	DOUBLE	필수	실 결제 금액
↳ paymentExchangeRate	DOUBLE	필수	결제 시점 환율. 결제 통화와 주문 통화가 다를 때 적용되며, 같으면 1입니다. (기준 통화: payCurrencyCode)
↳ buyerWalletAddress	STRING	필수	구매자 결제 지갑 주소
↳ variableFeeRate	DOUBLE	선택	결제 수수료율 (%). Unifi Pay 지급 명세서 번호 생성 전인 경우 Null
↳ settlementId	STRING	선택	Unifi Pay 지급 명세서 ID 정보. 생성 전인 경우 Null
↳ settlementCurrencyCode	STRING	선택	정산 통화 코드 (USDT, JPYC). 정산 전인 경우 Null
↳ settlementExchangeRate	DOUBLE	선택	정산 시점 환율. 정산 전인 경우 Null
totalElements	LONG	필수	전체 건수
totalPages	INTEGER	필수	전체 페이지수
pageNumber	INTEGER	필수	현재 페이지 번호
first	BOOLEAN	필수	첫 페이지 여부
last	BOOLEAN	필수	마지막 페이지 여부

응답 예시 — 성공

JSON

{
  "content": [
    {
      "partnerCorpName": "ABC Corporation",
      "storeId": "store_001",
      "orderId": "ORD-20260301-0001",
      "itemName": "Premium Subscription",
      "serviceName": "ABC Service",
      "orderCountryCode": "KR",
      "orderCurrencyCode": "USD",
      "orderAmount": 50000,
      "createdAt": "2026-03-01T10:00:00Z",
      "transactionId": "txn_abc123def456",
      "blockchainTxId": "0xabcdef1234567890abcdef1234567890abcdef12",
      "paymentType": "PURCHASE",
      "originTransactionId": null,
      "status": "CONFIRMED",
      "finalizedAt": "2026-03-01T10:01:30Z",
      "capturedAt": "2026-03-01T10:01:25Z",
      "failType": null,
      "payCurrencyCode": "USDT",
      "payAmount": 10.87,
      "paymentExchangeRate": 1.0,
      "buyerWalletAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "variableFeeRate": 1.5,
      "settlementId": "stl_xyz789",
      "settlementCurrencyCode": "USDT",
      "settlementExchangeRate": 1.0
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "pageNumber": 0,
  "first": true,
  "last": true
}

응답 예시 — 실패

JSON

{
  "code": "PAYMENT_INVALID_REQUEST",
  "message": "Date range must not exceed 90 days"
}

오류 타입 코드

HTTP 상태	오류 코드	설명
400	BAD_REQUEST	유효하지 않은 입력 값 (page/size 범위 등)
401	UNAUTHORIZED	유효하지 않은 HMAC
403	FORBIDDEN	허용되지 않은 IP 혹은 Path
503	MAINTENANCE	점검 중
406	PAYMENT_INVALID_REQUEST	from/to 누락 (단건 또는 정산 id 미지정 시) 또는 조회 기간 제약 위반
500	INTERNAL_SERVER_ERROR	서버 내부 오류

3. 테스트 가이드

Preview 환경에서 Unifi Pay 결제 연동을 테스트하는 방법입니다.

1 Unifi Pay 테스트는 Preview 환경에서 진행할 수 있습니다.
2 Unifi Wallet은 Preview 환경에서 Production 기준의 Google 계정으로 생성 및 연동을 진행합니다. (Preview 환경에서 생성한 Unifi Wallet은 Production 환경과 별도로 관리됩니다.) Preview Unifi Wallet →
3 Preview 환경의 결제는 Kaia Blockchain의 테스트넷 환경인 Kairos 기준으로 진행됩니다.
4 아래 가이드를 참고하여 Kairos 테스트넷에서 테스트용 USDT를 확보한 후 결제 테스트를 진행해주시기 바랍니다.

Preview 환경

Kairos Testnet (테스트넷)

Testnet

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

Kaia Faucet →

Base URL https://app-api-pay.unifi.me