💳 네이티브 결제 연동

API 업데이트 공지

최근 API 엔드포인트 및 매개변수에 업데이트가 있었습니다. 자세한 내용은 변경 기록을 참조하십시오.

Native Checkout API: 사용자는 사이트/앱에 구축된 결제 페이지의 QR 코드를 스캔하거나 주소를 복사하여 결제할 수 있습니다.

Native Checkout API와 연동하여 사이트/앱의 결제 페이지를 구축하십시오. 사용자는 사이트/앱 내에서 결제합니다. 외부 페이지로 안내할 필요가 없습니다. 사용자의 결제 경험을 완벽하게 제어하십시오.

📦 1. 주문 생성

인터페이스 설명: 이 인터페이스를 통해 결제 주문을 제출하고 영수증 정보를 얻습니다.
인터페이스 주소: POST /api/order/create

요청 매개변수

필드	유형	필수	설명
out_trade_no	string	예	판매자 주문 ID
currency_id	int	예	전역 고유 통화 ID
`fiat_name`	string	아니요	법정 화폐 이름 (USD / USDT / JPY / CHF / CAD / NOK / SEK / HKD / SGD / KRW / TWD / CNY / INR / BRL / MXN / ZAR / RUB / TRY / EUR / GBP / AUD / VND / THB)
fiat_amount	string	아니요	법정 화폐 금액 ("1.2")
token_amount	string	아니요	토큰 금액
callback_url	string	아니요	콜백 URL
time_out	int64	아니요	10자리 만료 타임스탬프, 0을 입력하면 기본값은 30분(1753513764)입니다

응답 필드 설명

필드	유형	설명	예시
trade_no	string	트랜잭션 ID	"20250629153045a7b3c9d2e5f8a1b4c6"
chain	string	블록체인 네트워크	"Tron"
token	string	암호화폐 토큰	"TRX"
contract	string	토큰 계약 주소	"TRX"
amount	string	트랜잭션 금액	"15.724197"
mode	string	결제 모드	"address"
pay_address	string	수취인 주소	"TSg8kWPE2s7z5Lon6bSnZZrYnquGHx2..."
time_expire	integer	만료 타임스탬프	1753515371
decimal	integer	토큰 소수점 자리수	6
chain_id	integer	체인 ID	3448148188
equity	integer	지분 가치	1
create_time	integer	생성 타임스탬프	1753513571
amount_collected	string	수집된 금액	"0"
need_confirms	integer	필요한 확인 수	0
already_confirms	integer	현재 확인 수	0
entrust_url	string	결제 URL	"https://checkout.pay.halochat.io/20260....b876498e0771e1"
referer	string	리퍼러 정보	""
chain_info	object	체인 정보	`{"token": "TRX", "rpc": "...", ...}`

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "trade_no": "20260317173635066d54f5b6c7269d41",
    "chain": "Tron",
    "token": "TRX",
    "contract": "TRX",
    "amount": "16.556743",
    "mode": "address",
    "pay_address": "THgSjcyhyxfzrjtS7VYw1vnHvb7QkMsY...",
    "time_expire": 1773741995,
    "decimal": 6,
    "chain_id": 3448148188,
    "equity": 1,
    "create_time": 1773740196,
    "amount_collected": "",
    "need_confirms": 0,
    "already_confirms": 0,
    "entrust_url": "https://checkout.pay.halochat.io/20260317173635066d54f5b6c7269d41",
    "referer": "",
    "chain_info": {
      "token": "TRX",
      "abi": "",
      "rpc": "https://nile.trongrid.io",
      "browser_url": "https://nile.tronscan.org/#/transaction",
      "decimal": 6,
      "logo": "https://halo-n.oss-ap-southeast-1.aliyuncs.com/png/202505/45d1f4b5-b80f-4331-af78-ec557f97d832.png",
      "series": "Tron",
      "monitor_chain_id": 3448148188
    }
  }
}

🔍 2. 주문 조회

인터페이스 설명: 이 인터페이스를 사용하여 주문 상태를 조회합니다.
인터페이스 주소: POST /api/order/detail

요청 매개변수

필드	유형	필수	설명
trade_no	string	예	트랜잭션 ID

응답 필드 설명

필드	유형	설명	예시
trade_no	string	트랜잭션 ID (플랫폼)	"20250629153045a7b3c9d2e5f8a1b4c6"
out_trade_no	string	판매자의 주문 ID	"202401011753513569"
chain	string	블록체인 네트워크	"Tron"
token	string	암호화폐 토큰	"TRX"
contract	string	토큰 계약 주소	"TRX"
fiat_name	string	법정 화폐 이름	"USD"
fiat_amount	string	지불할 법정 화폐 금액	"5"
amount	string	보낼 암호화폐 금액	"15.724197"
mode	string	결제 모드	"address"
pay_address	string	수취인 암호화폐 주소	"TSg8kWPE2s7z5Lon6bSnZZrYnquGHx2bsj"
status	string	트랜잭션 상태	"TO-BE-PAID"
time_expire	integer	만료 타임스탬프 (Unix)	1753515371
decimal	integer	토큰 소수점 자리수	6
chain_id	integer	체인 ID	3448148188
equity	integer	지분 가치	1
create_time	integer	생성 타임스탬프 (Unix)	1753513571
amount_collected	string	수집된 금액	"0"
need_confirms	integer	필요한 확인 수	0
already_confirms	integer	현재 확인 수	0
entrust_url	string	결제 URL (해당하는 경우)	""
referer	string	리퍼러 정보	""
chain_info	object	체인 정보	`{"token": "TRX", "rpc": "...", ...}`

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "trade_no": "20260317173635066d54f5b6c7269d41",
    "out_trade_no": "ORDER_1773740195363",
    "chain": "Tron",
    "token": "TRX",
    "contract": "TRX",
    "fiat_name": "USD",
    "fiat_amount": "5",
    "amount": "16.556743",
    "mode": "address",
    "pay_address": "THgSjcyhyxfzrjtS7VYw1vnHvb7QkMsY7w",
    "status": "TO-BE-PAID",
    "time_expire": 1773741995,
    "decimal": 6,
    "chain_id": 3448148188,
    "equity": 1,
    "create_time": 1773740196,
    "amount_collected": "0",
    "need_confirms": 0,
    "already_confirms": 0,
    "entrust_url": "",
    "referer": "",
    "chain_info": {
      "token": "TRX",
      "abi": "",
      "rpc": "https://nile.trongrid.io",
      "browser_url": "https://nile.tronscan.org/#/transaction",
      "decimal": 6,
      "logo": "",
      "series": "",
      "monitor_chain_id": 0
    }
  }
}

💱 3. 가격 환율

인터페이스 설명: TOKEN과 법정 화폐 간의 현재 환율을 가져옵니다.
인터페이스 주소: POST /api/order/exchange-rates

요청 매개변수

필드	유형	필수	설명
currency_id	int	예	전역 고유 통화 ID
`fiat_name`	string	예	법정 화폐 약어 (USD / USDT / JPY / CHF / CAD / NOK / SEK / HKD / SGD / KRW / TWD / CNY / INR / BRL / MXN / ZAR / RUB / TRY / EUR / GBP / AUD / VND / THB)
fiat_amount	string	예	법정 화폐 금액

응답 필드 설명

필드	유형	설명
amount	string	금액
exchange_rate	string	환율

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "amount": "0.00001971",
    "exchange_rate": "100"
  }
}

📋 4. 앱 토큰 목록 (잔액 포함)

인터페이스 설명: 현재 앱(X-Appid)에서 수금이 활성화된 암호화폐와 주소 집계 기준 잔액을 반환합니다(POST /api/account/balance와 동일한 집계 기준). 플랫폼 전체 토큰 목록이 아닙니다. 전체 목록은 §5 토큰 목록을 참고하세요.
인터페이스 주소: POST /api/currency/app-token-list
요청 매개변수: 본문은 {}. 인증 헤더는 다른 API와 동일합니다.

응답 필드 설명

루트 객체:

필드	유형	설명
code	integer	비즈니스 코드, `0`이면 성공
msg	string	메시지
data	array	현재 앱에서 수금 활성화된 토큰 및 잔액

data[] 요소:

필드	유형	설명
currency_id	integer	전역 고유 통화 ID
chain	string	체인 이름
network	string	네트워크 이름
token	string	토큰 심볼
contract	string	컨트랙트 주소
chain_id	integer	체인 ID
logo	string	토큰 로고 URL
decimal	integer	소수 자릿수
balance	string	총 잔액(10진 문자열)
operable_balance	string	가용 잔액
frozen_amount	string	동결 금액
status	integer	상태: 1 — 활성, 2 — 비활성
transaction_enabled	boolean	수금 활성(본 응답에서는 항상 `true`)

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "currency_id": 46,
      "chain": "Tron",
      "network": "Nile",
      "token": "JST",
      "contract": "TF17BgPaZYbxxxxhriubPDsA7ArKoLX3",
      "chain_id": 3448148188,
      "logo": "https://halo-n.oss-ap-southeast-1.aliyuncs.com/png/202505/xxx-c3f3-4d5d-a9b5-0143d78326f9.png",
      "decimal": 18,
      "balance": "0.785074013",
      "operable_balance": "0.785074013",
      "frozen_amount": "0",
      "status": 1,
      "transaction_enabled": true
    }
  ]
}

📋 5. 토큰 목록

인터페이스 설명: 시스템에서 지원하는 Token 목록을 가져옵니다. 앱별 수금 활성 토큰과 잔액이 필요하면 §4 앱 토큰 목록을 사용하세요.
인터페이스 주소: POST /api/currency/token-list
요청 매개변수: 없음

응답 필드 설명

필드	유형	설명
currency_id	int	전역 고유 통화 ID.
chain	string	체인
network	string	네트워크
token	string	토큰
contract	string	계약 주소. 현재 기본 통화가 통화 이름과 동일한 경우 값은 통화 이름과 일치합니다.
chain_id	int	체인 ID. 이더리움 시리즈에만 값이 있습니다.
logo	string	로고
decimal	int	소수점 자리수

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "currency_id": 46,
      "chain": "Tron",
      "token": "JST",
      "network": "Nile",
      "contract": "TF17BgPaZYbxxxxhriubPDsA7ArKoLX3",
      "chain_id": 3448148188,
      "logo": "https://halo-n.oss-ap-southeast-1.aliyuncs.com/png/202505/xxx-c3f3-4d5d-a9b5-0143d78326f9.png",
      "decimal": 18
    }
  ]
}

💸 6. 지급 (출금)

인터페이스 설명: 판매자는 이 인터페이스를 통해 지정된 주소로 현금을 인출할 수 있습니다.
인터페이스 주소: POST /api/payout/create

요청 매개변수

필드	유형	필수	설명
currency_id	int	예	전역 고유 통화 ID
amount	string	예	통화 기본 금액
to_address	string	예	수취인 주소
callback_url	string	아니요	콜백 주소 (판매자 APPID에 의해 설정된 기본 콜백 주소)
google_code	string	아니요	Google 인증 코드 (현재 앱에 대해 인증이 활성화된 경우 필수)

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "cost": "0.801502",
    "actual_receipt": "0.001",
    "trade_no": "202603171746187e582d1b789b27ea55",
    "estimated_transfer": "0"
  }
}

📊 7. 전송 상태 조회

인터페이스 설명: 지급 주문 상태를 조회합니다.
인터페이스 주소: POST /api/payout/detail

요청 매개변수

필드	유형	필수	설명
trade_no	string	예	트랜잭션 번호

응답 필드 설명

필드	유형	설명
trade_no	string	트랜잭션 ID
service_charge	string	서비스 수수료
gas	string	GAS 요금
token	string	통화
amount	string	금액
target_address	string	수취인 주소
start_time	int	시작 시간
created_time	int	생성 시간
status	string	트랜잭션 상태 (CONFIRMING-PROGRESS: 확인 중, PAID: 성공, FAIL: 실패, CANCEL: 취소됨, PROGRESS: 대기 중)

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "service_charge": "0.000002",
    "gas": "0.8015",
    "amount": "0.001",
    "status": "TRANSFER",
    "target_address": "TDYiTL3pke3T9BsoTotbKb922WsXQCmSxv",
    "start_time": 1773740882,
    "created_time": 1773740882,
    "trade_no": "202603171748020a09cbb09b4846bc99",
    "token": "DK7bKg181cC7pBgX3PxSIH2WdklZ5IPT"
  }
}

💰 8. 잔액 확인

이 API를 통해 애플리케이션의 단일 통화 잔액 정보를 검색합니다.

인터페이스 주소: POST /api/account/balance

요청 매개변수

필드	유형	필수	설명
currency_id	int	예	전역 고유 통화 ID

응답 필드 설명

필드	유형	설명
currency_id	int	전역 고유 통화 ID
balance	string	남은 수량
balance_usdt	string	USDT로 변환된 남은 수량 가치
operable_balance	string	작동 가능한 수량 (지갑 주소의 기본 통화 금액이 너무 낮아 수집할 수 없는 경우 해당 지갑 주소를 사용할 수 없습니다. 개인 센터 => 네트워크 설정에서 최소 작동 임계값을 참조하십시오.)
operable_balance_usdt	string	작동 가능한 수량 가치
chain	string	체인 이름
network	string	네트워크
token	string	토큰
contract	string	계약 주소 (약어 토큰 이름으로 된 기본 토큰)

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "currency_id": 46,
    "balance": "0.785074013",
    "operable_balance": "0.785074013",
    "operable_balance_usdt": "0.043642",
    "balance_usdt": "0.043642",
    "chain": "Tron",
    "network": "Nile",
    "token": "JST",
    "contract": "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3"
  }
}

🖼️ 9. 정적 결제 QR 코드

인터페이스 설명: API를 통해 독립적인 정적 결제 주소를 신청합니다. 해당 APPID의 CallBack 인터페이스 주소로 콜백됩니다.
인터페이스 주소: POST /api/payment-qr-code/create

요청 매개변수

필드	유형	필수	설명
name	string	예	QR 코드 이름
currency_id	int	예	전역 고유 통화 ID
amount	string	아니요	기본 결제 금액 ("0"일 수 있음)

응답 필드 설명

필드	유형	설명	예시
id	int	고유 QR 코드 ID	115
address	string	정적 결제 주소	"TXd8UKLtLqk5V15v7e3W43ZdNw6berp6DP"

성공 응답 예시

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 115,
    "address": "TXd8UKLtLqk5V15v7e3W43ZdNw5berp6DP"
  }
}

💡

이 API에 요청하려면 QR 코드 애플리케이션의 APPID가 필요합니다.

📌 오류 코드 보기

📦 1. 주문 생성​

요청 매개변수​

응답 필드 설명​

성공 응답 예시​

🔍 2. 주문 조회​

요청 매개변수​

응답 필드 설명​

성공 응답 예시​

💱 3. 가격 환율​

요청 매개변수​

응답 필드 설명​

성공 응답 예시​

📋 4. 앱 토큰 목록 (잔액 포함)​

응답 필드 설명​

성공 응답 예시​

📋 5. 토큰 목록​

응답 필드 설명​

성공 응답 예시​

💸 6. 지급 (출금)​

요청 매개변수​

성공 응답 예시​

📊 7. 전송 상태 조회​

요청 매개변수​

응답 필드 설명​

성공 응답 예시​

💰 8. 잔액 확인​

요청 매개변수​

응답 필드 설명​

성공 응답 예시​

🖼️ 9. 정적 결제 QR 코드​

요청 매개변수​

응답 필드 설명​

성공 응답 예시​

📦 1. 주문 생성

요청 매개변수

응답 필드 설명

성공 응답 예시

🔍 2. 주문 조회

요청 매개변수

응답 필드 설명

성공 응답 예시

💱 3. 가격 환율

요청 매개변수

응답 필드 설명

성공 응답 예시

📋 4. 앱 토큰 목록 (잔액 포함)

응답 필드 설명

성공 응답 예시

📋 5. 토큰 목록

응답 필드 설명

성공 응답 예시

💸 6. 지급 (출금)

요청 매개변수

성공 응답 예시

📊 7. 전송 상태 조회

요청 매개변수

응답 필드 설명

성공 응답 예시

💰 8. 잔액 확인

요청 매개변수

응답 필드 설명

성공 응답 예시

🖼️ 9. 정적 결제 QR 코드

요청 매개변수

응답 필드 설명

성공 응답 예시