API 문서 (v1.0.0) OpenAPI (Swagger)

암호화폐 결제 API 문서

VisualPay 암호화폐 결제 게이트웨이의 전체 REST API 레퍼런스입니다. 이 API로 거래를 생성하고, 지원되는 모든 네트워크에서 USDT, USDC, ETH, BNB, TON 결제를 받고, 온체인 상태를 확인하고, 웹훅을 수신할 수 있습니다. 모든 작업은 고객님의 백엔드에서 이루어지며 중간에 별도의 호스팅 결제 화면을 거치지 않습니다.

아래의 모든 엔드포인트는 가맹점 API 키 하나로 인증하고 JSON을 반환하며, 어떤 언어나 프레임워크에서도 호출할 수 있습니다. 설치할 SDK도, 관리할 플러그인도 없습니다.

시작하기

VisualPay로 암호화폐 결제 게이트웨이를 연동하는 데는 POST 요청 한 번이면 충분합니다. 주문 금액(USD)과 결제받을 코인 및 네트워크를 보내면, API가 결제 주소, 정확한 USDT(또는 다른 코인) 수량, 주문과 함께 저장할 수 있는 추적 코드를 응답합니다.

VisualPay를 연동하면 비즈니스에서 암호화폐 결제를 간편하게 받을 수 있습니다. 결제를 처리하려면 새 거래를 생성한 뒤, 응답에 포함된 결제 페이지로 사용자를 리디렉션하세요. 블록체인 모니터링은 VisualPay가 처리하며, 상태를 폴링하거나 가맹점 패널에서 대사할 수 있습니다.

거래를 생성할 때 선택적으로 callback_url을 전달하면, 결제가 완료되거나 실패한 뒤 결제자를 고객님의 사이트로 돌려보낼 수 있습니다. VisualPay는 이 URL에 order_id(제공한 경우), status, tracking_code를 쿼리 파라미터로 붙입니다.

기본 URL https://visualpay.net/

콜백 리디렉션

거래 생성 시 선택 항목인 callback_url을 제공하면, 결제가 최종 상태에 도달한 뒤 결제 페이지가 결제자의 브라우저를 해당 URL로 리디렉션합니다. 모든 결과에 하나의 URL을 사용하며, 성공과 실패는 status 쿼리 파라미터로 구분합니다.

URL에 추가되는 쿼리 파라미터

게이트웨이는 아래 표의 파라미터를 콜백 URL에 추가합니다. 덕분에 애플리케이션은 API를 다시 호출하지 않고도 주문과 최종 결과를 식별할 수 있습니다.

파라미터 설명
order_id 거래 생성 시 제공한 주문 ID(제공한 경우).
status 최종 결제 상태: confirmed, expired, cancelled 중 하나(거래 조회 API와 동일한 값).
tracking_code 검증에 사용하는 VisualPay 거래 UUID.

리디렉션 예시

url
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
중요: 콜백 리디렉션은 브라우저 사용자 경험을 위한 기능일 뿐입니다. 주문을 처리하기 전에 백엔드에서 반드시 웹훅이나 거래 조회 엔드포인트로 결제를 확인해야 합니다. callback_url을 생략하면 결제자는 VisualPay 결제 페이지에 그대로 머뭅니다.

리디렉션 시점: 결제가 확인되면 성공 메시지를 3초간 표시한 뒤 이동하고, 만료되거나 취소된 결제는 즉시 이동합니다.

인증

VisualPay 가맹점 API를 사용하려면 모든 요청을 가맹점 API 키로 인증해야 합니다. VisualPay 패널에서 가맹점을 만들고 가맹점 설정에서 API 키를 복사하세요.

보안 참고: API 키는 안전하게 보관하세요. 키는 생성할 때 표시되며 클라이언트 측 코드에 노출해서는 안 됩니다.

모든 요청에 가맹점 API 키가 필요합니다.

모든 API 요청의 x-api-key HTTP 헤더에 가맹점 API 키를 포함하세요.

http
x-api-key: YOUR_MERCHANT_API_KEY
GET /api/v1/merchant/currencies/list

지원 통화 목록 조회

인증된 가맹점에 활성화된 통화와 네트워크를 반환합니다.

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/currencies/list' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

응답 예시

json
{
    "status": 200,
    "data": [
        {
            "currency_name": "Tether",
            "currency_symbol": "USDT",
            "currency_type": "stable",
            "price_in_usdt": 1,
            "icon": "",
            "supported_networks": [
                {
                    "network_name": "TRON (TRC20)",
                    "network_symbol": "TRX",
                    "network_code": "trc20",
                    "network_fee": 1,
                    "minimum_pay_usd": 5,
                    "maximum_pay_usd": 10000,
                    "max_ttl": 30,
                    "icon": ""
                }
            ]
        }
    ],
    "message": "success"
}
GET /api/v1/merchant/transaction/list

거래 목록 조회

가맹점 거래를 페이지 단위로 반환합니다. 선택 필터: status 열거값, 기간(최대 30일).

요청 파라미터

필드 필수 타입 설명
limit 아니요 integer 페이지당 항목 수(1–50)
page 아니요 integer 페이지 번호
from_date 아니요 string (date) 시작일(Y-m-d). to_date와 함께 지정해야 합니다. 최대 기간은 30일입니다.
to_date 아니요 string (date) 종료일(Y-m-d). from_date와 함께 지정해야 합니다. 최대 기간은 30일입니다.
status 아니요 enum 선택 항목. 지원 값: pending, confirmed, expired, cancelled.

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

응답 예시

json
{
    "status": 200,
    "data": {
        "items": [
            {
                "order_id": 1001,
                "status": "pending",
                "tracking_code": "AbC12XyZ",
                "payment_url": "https://pay.visualpay.net/AbC12XyZ",
                "currency_code": "usdt_trc20",
                "currency_name": "Tether",
                "network_code": "trc20",
                "network_name": "TRON (TRC20)",
                "pay_amount": "10.00000000",
                "amount_usd": "10.00000000",
                "platform_share": "0.20000000",
                "merchant_share": "9.80000000",
                "payment_fee_percent": 1,
                "payment_tolerance_percent": 1,
                "paid_amount": "",
                "is_canceled_by_user": false,
                "tx_id": "",
                "tx_explorer_url": "",
                "email": "",
                "comment": "",
                "paid_at": 0,
                "created_at": 0,
                "expired_at": 0
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 50,
            "total": 120,
            "last_page": 3
        }
    },
    "message": "success"
}
POST /api/v1/merchant/transaction/create

거래 생성

새 암호화폐 결제를 생성합니다.

amount_usd: USD/USDT 기준 결제 금액입니다. 보내는 값은 minimum_pay_usd 이상, maximum_pay_usd 이하여야 합니다.

ttl: 거래를 모니터링하는 유효 시간(분)입니다. 입력값은 max_ttl보다 클 수 없습니다.

order_id: 선택 항목입니다. 보낼 경우 6자리 숫자여야 합니다.

email: 선택 항목입니다.

comment: 선택 항목입니다.

callback_url: 선택 항목입니다. 고객님 사이트의 공개 HTTPS URL입니다. 제공하면 결제 페이지가 최종 상태(confirmed, expired, cancelled)에 도달한 뒤 결제자를 이 URL로 돌려보내며, order_id(제공한 경우), status, tracking_code 쿼리 파라미터를 붙입니다.

예시:
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000

요청 파라미터

필드 필수 타입 설명
currency_symbol 예 string 가맹점에 활성화된 통화 심볼(예: USDT, ETH).
network_code 예 string 선택한 통화의 네트워크 코드(예: TRC20, ERC20, BEP20).
amount_usd 예 number USD/USDT 기준 금액
ttl 예 integer 이 거래를 모니터링하는 유효 시간(분). 해당 통화의 max_ttl을 넘을 수 없습니다.
order_id 아니요 integer 선택 항목. 제공할 경우 6자리 숫자여야 합니다.
email 아니요 string (email) 선택 항목. 결제자 이메일.
comment 아니요 string 선택 항목. 결제자 메모.
callback_url 아니요 string (uri) 선택 항목. 결제자가 결제 페이지에서 결제를 완료하거나 실패하면, VisualPay가 결제자의 브라우저를 이 HTTPS URL로 리디렉션하고 쿼리 파라미터 order_id(생성 시 제공한 경우), status, tracking_code를 붙입니다. 모든 결과에 하나의 URL을 사용하고 status 파라미터로 결과를 구분하세요. 리디렉션에만 의존하지 말고 반드시 서버에서 웹훅이나 거래 조회 엔드포인트로 결제 상태를 검증하세요.

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/create?currency_symbol=value&network_code=value&amount_usd=value&ttl=value&order_id=value&email=value&comment=value&callback_url=value' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"currency_symbol":"USDT","network_code":"trc20","amount_usd":25.5,"ttl":15,"order_id":100001,"email":"payer@example.com","comment":"Invoice #1001","callback_url":"https://example.com/order"}'

응답 예시

json
{
    "status": 200,
    "data": {
        "payment_url": "http://127.0.0.1:6131/payment/AbC12XyZ",
        "tracking_code": "AbC12XyZ",
        "status": "pending",
        "order_id": 1001,
        "currency_name": "Tether",
        "currency_symbol": "USDT",
        "network": "tron",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "amount_usd": "25.50000000",
        "pay_amount": "25.50000000",
        "platform_share": "0.51000000",
        "merchant_share": "24.99000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "wallet_address": "TXyz...",
        "qr_code": "",
        "expired_at": 0
    },
    "message": "success"
}
GET /api/v1/merchant/transaction/status

거래 조회

tracking_code로 조회합니다. 인증된 가맹점에 속한 거래만 반환됩니다.

요청 파라미터

필드 필수 타입 설명
tracking_code 예 string 거래 생성 시 게이트웨이가 반환한 추적 코드

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/status?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

응답 예시

json
{
    "status": 200,
    "data": {
        "order_id": 1001,
        "status": "pending",
        "tracking_code": "AbC12XyZ",
        "payment_url": "https://pay.visualpay.net/AbC12XyZ",
        "currency_code": "usdt_trc20",
        "currency_name": "Tether",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "pay_amount": "10.00000000",
        "amount_usd": "10.00000000",
        "platform_share": "0.20000000",
        "merchant_share": "9.80000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "paid_amount": "",
        "is_canceled_by_user": false,
        "tx_id": "",
        "tx_explorer_url": "",
        "email": "",
        "comment": "",
        "paid_at": 0,
        "created_at": 0,
        "expired_at": 0
    },
    "message": "success"
}
GET /api/v1/merchant/transaction/recheck

거래 재확인

인증된 가맹점 소유의 만료 또는 취소된 거래에 대해 온체인 결제를 다시 검증합니다. tracking_code로 조회합니다.

요청 파라미터

필드 필수 타입 설명
tracking_code 예 string 거래 생성 시 게이트웨이가 반환한 추적 코드

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/recheck?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

응답 예시

json
{
    "status": 200,
    "data": {
        "order_id": 1001,
        "status": "pending",
        "tracking_code": "AbC12XyZ",
        "payment_url": "https://pay.visualpay.net/AbC12XyZ",
        "currency_code": "usdt_trc20",
        "currency_name": "Tether",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "pay_amount": "10.00000000",
        "amount_usd": "10.00000000",
        "platform_share": "0.20000000",
        "merchant_share": "9.80000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "paid_amount": "",
        "is_canceled_by_user": false,
        "tx_id": "",
        "tx_explorer_url": "",
        "email": "",
        "comment": "",
        "paid_at": 0,
        "created_at": 0,
        "expired_at": 0
    },
    "message": "Transaction confirmed successfully."
}
POST /api/v1/merchant/transaction/cancel

거래 취소

상태가 pending인 거래만 취소할 수 있습니다.

요청 파라미터

필드 필수 타입 설명
tracking_code 예 string 취소할 대기 중 거래의 게이트웨이 추적 코드.

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/cancel?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"tracking_code":"AbC12XyZ"}'

응답 예시

json
{
    "status": 200,
    "data": {
        "order_id": 1001,
        "status": "pending",
        "tracking_code": "AbC12XyZ",
        "payment_url": "https://pay.visualpay.net/AbC12XyZ",
        "currency_code": "usdt_trc20",
        "currency_name": "Tether",
        "network_code": "trc20",
        "network_name": "TRON (TRC20)",
        "pay_amount": "10.00000000",
        "amount_usd": "10.00000000",
        "platform_share": "0.20000000",
        "merchant_share": "9.80000000",
        "payment_fee_percent": 1,
        "payment_tolerance_percent": 1,
        "paid_amount": "",
        "is_canceled_by_user": false,
        "tx_id": "",
        "tx_explorer_url": "",
        "email": "",
        "comment": "",
        "paid_at": 0,
        "created_at": 0,
        "expired_at": 0
    },
    "message": "Transaction cancelled successfully."
}
GET /api/v1/merchant/withdrawals/list

출금 목록 조회

출금 내역을 페이지 단위로 반환합니다. 선택 필터: status 열거값, 기간(최대 30일).

요청 파라미터

필드 필수 타입 설명
limit 아니요 integer 페이지당 항목 수(1–50)
page 아니요 integer 페이지 번호
from_date 아니요 string (date) 시작일(Y-m-d). to_date와 함께 지정해야 합니다. 최대 기간은 30일입니다.
to_date 아니요 string (date) 종료일(Y-m-d). from_date와 함께 지정해야 합니다. 최대 기간은 30일입니다.
status 아니요 enum 선택 항목. 지원 값: pending, processing, confirmed.

요청 예시

bash
curl --location 'https://visualpay.net/api/v1/merchant/withdrawals/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

응답 예시

json
{
    "status": 200,
    "data": {
        "items": [
            {
                "tracking_code": "49e9f567-8c2a-4b1d-9f3e-2a1b0c9d8e7f",
                "currency_name": "Tether",
                "network_name": "TRON (TRC20)",
                "destination_address": "TXyz...",
                "amount_usd": "$98.50",
                "status": "Processing",
                "tx_id": "",
                "tx_explorer_url": "",
                "created_at": 0
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 50,
            "total": 120,
            "last_page": 3
        }
    },
    "message": "success"
}

거래 상태

거래 상태는 결제의 현재 단계를 나타냅니다. 가능한 값은 다음과 같습니다.

pending

온체인 결제를 기다리는 중입니다.

confirmed

결제가 정상적으로 완료되었습니다.

expired

결제 가능 시간이 지나 완료되지 않았습니다.

cancelled

거래가 취소되었습니다.

권장 사항: 결제자가 사이트로 돌아오면, 주문을 처리하기 전에 거래 조회 엔드포인트를 호출해 최종 결제 상태를 확인하세요.