Rihpig

Posted on Apr 23 • Originally published at apidog.com

문페이 API 사용법 (법정화폐 온램프 및 오프램프 연동)

법정화폐-암호화폐 온램프는 과거에는 긴 규정 준수 서류, 은행 연결, 임시방편 KYC 공급업체 연동이 필요했습니다. MoonPay API를 사용하면 이 모든 과정을 하나의 통합으로 간소화할 수 있습니다. 서명된 URL을 만들어 앱에 MoonPay 위젯을 삽입하면, MoonPay가 카드 결제, 은행 송금, KYC, 지갑 지급을 모두 처리합니다.

오늘 Apidog를 체험해보세요

이 가이드에서는 MoonPay API를 처음부터 끝까지 실제로 구현하는 방법을 다룹니다. 파트너 계정 설정, 위젯과 직접 API 비교, 서명된 URL 생성, 웹훅 검증, 판매(오프램프) 흐름, NFT 결제, 규정 준수 제한 사항 등을 실전 위주로 설명합니다. 아래 모든 요청은 샌드박스 환경에서 테스트되었으며, MoonPay 공식 개발자 포털에서 자세한 문서를 확인할 수 있습니다. 개발 과정에서는 Apidog에서 동일한 호출을 빠르게 실행해볼 수 있습니다.

여전히 온/오프램프 공급업체를 비교 중이라면, 최고의 법정화폐 온램프 및 오프램프 API 비교 글을 참고해 MoonPay와 Transak, Ramp, Stripe Crypto의 차이점을 확인하세요. 스택의 USDC 인프라가 궁금하다면 Circle API 사용법도 유용합니다.

요약 (TL;DR)

MoonPay: 160개국 이상에서 지갑, NFT 마켓, 거래소에 쓰이는 규제된 온/오프램프.
통합 방식: Ramps SDK/위젯(쉽고 빠름, MoonPay UI) 또는 직접 REST API(완전 제어, UI 직접 구축).
모든 위젯 URL: HMAC-SHA256(비밀키 사용)으로 서명 필수. 미서명 URL은 프로덕션에서 거부됨.
KYC, 결제, 은행 연결: MoonPay가 서버 측에서 처리. 웹훅도 HMAC 패턴으로 서명.
수수료: 카드 3.5%-4.5%, 은행 송금 더 저렴. 수수료는 사용자에게 투명하게 노출.
오프램프(판매): 구매와 거의 동일한 흐름. 서명 URL, 사용자 암호화폐 입금, MoonPay가 법정화폐 지급.

MoonPay란 무엇인가요?

MoonPay는 카드, 은행 송금, Apple Pay, Google Pay, SEPA 등 다양한 결제수단으로 암호화폐를 사고팔 수 있게 해주는 라이선스 결제사입니다. 미국 MSB, EU EMI 라이선스 등 각국 규정에 따라 운영되며, 개발자는 송금업자 등록 없이 카드 결제와 암호화폐 전송을 구현할 수 있습니다.

40개 이상 체인(이더리움, 솔라나, 비트코인, 폴리곤 등), 110+ 암호화폐, NFT 결제 기능 지원. MetaMask, Trust Wallet, OpenSea 등에서 사용 중입니다.

인증 및 설정

moonpay.com/business에서 파트너 계정 등록
승인 후 샌드박스/프로덕션용 키 2세트 수령: 공개키(pk_test_...), 비밀키(sk_test_...)
비밀키는 데이터베이스 암호처럼 안전하게 관리
모든 URL 서명, 웹훅 검증에 비밀키 필요

환경 변수 예시:

export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"

샌드박스 환경은 실제 결제는 일어나지 않으나, 대시보드에서 상태를 직접 변경하며 테스트할 수 있습니다. 개발 완료 후 프로덕션 키로 전환하세요.

핵심 엔드포인트

MoonPay 주요 REST API 엔드포인트는 통화, 견적, 거래, 웹훅 등입니다. 전체 REST 참조에서 모든 리소스 확인 가능.

지원 통화 목록 가져오기

국가별 가용성이 다르므로, 실시간 조회 및 클라이언트 위치 필터링이 필요합니다.

curl -X GET "https://api.moonpay.com/v3/currencies" \
  -H "Authorization: Api-Key $MOONPAY_API_KEY"

응답에는 code, name, type(crypto/fiat), minBuyAmount, maxBuyAmount 등 메타데이터와 네트워크별 정보가 포함됩니다.

실시간 견적 받기

사용자에게 수수료 포함 정확 견적을 제공해야 합니다.

curl -X GET "https://api.moonpay.com/v3/currencies/eth/buy_quote?apiKey=$MOONPAY_API_KEY&baseCurrencyAmount=100&baseCurrencyCode=usd" \
  -H "Content-Type: application/json"

quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmount 등 반환. 견적은 60초간 유효하니, 캐싱 권장.

서명된 구매 위젯 URL 생성(Node.js)

구매 위젯은 가장 빠른 통합 방법입니다. 쿼리 파라미터를 구성하고, 비밀키로 서명해 사용자를 리디렉션 또는 iframe으로 연결합니다.

import crypto from "node:crypto";

function buildMoonPayBuyUrl({ walletAddress, currencyCode, baseAmount, email }) {
  const params = new URLSearchParams({
    apiKey: process.env.MOONPAY_API_KEY,
    currencyCode,
    walletAddress,
    baseCurrencyCode: "usd",
    baseCurrencyAmount: String(baseAmount),
    email,
    redirectURL: "https://yourapp.com/moonpay/complete",
  });

  const originalUrl = `https://buy.moonpay.com?${params.toString()}`;

  const signature = crypto
    .createHmac("sha256", process.env.MOONPAY_SECRET_KEY)
    .update(new URL(originalUrl).search)
    .digest("base64");

  return `${originalUrl}&signature=${encodeURIComponent(signature)}`;
}

이 URL을 사용자에게 제공하세요. 서명 파라미터로 위변조 방지.

추가 파라미터는 구매 위젯 빠른 시작 가이드 참고.

웹훅 서명 검증

모든 MoonPay 웹훅 콜백에는 신뢰성 보장을 위한 Moonpay-Signature-V2 헤더가 포함됩니다. 페이로드 신뢰 전 반드시 검증하세요.

import crypto from "node:crypto";

export function verifyMoonPayWebhook(rawBody, header, secret) {
  const [tPart, sPart] = header.split(",");
  const timestamp = tPart.split("=")[1];
  const signature = sPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

5분 이상 지난 요청은 거부해 재실행 공격을 차단하세요.

이벤트 및 페이로드 상세는 웹훅 참조에서 확인.

판매(오프램프) 흐름

구매와 거의 동일하게, sell.moonpay.com을 서명된 URL로 호출합니다.

const sellParams = new URLSearchParams({
  apiKey: process.env.MOONPAY_API_KEY,
  baseCurrencyCode: "eth",
  baseCurrencyAmount: "0.5",
  quoteCurrencyCode: "usd",
  refundWalletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbc",
});

const sellUrl = `https://sell.moonpay.com?${sellParams.toString()}`;
// 구매 URL과 동일하게 서명해서 사용

refundWalletAddress는 KYC 실패/오입금 등 예외 시 환불용으로 반드시 전달해야 합니다.

NFT 결제

NFT 결제는 카드로 NFT를 직접 구매할 수 있게 해줍니다.

MoonPay에 컬렉션을 등록(또는 지원 마켓플레이스 연동) 후,

contractAddress, tokenId, listingId가 포함된 서명 URL을 생성합니다.

MoonPay가 법정화폐 결제부터 온체인 전송까지 자동 처리합니다.

일반적인 오류 및 속도 제한

400 invalid_signature: HMAC 입력이 서버와 불일치. 서명 시 쿼리 문자열이 정확히 일치하도록 주의.
403 geo_restricted: 해당 국가 미지원. 통화 객체의 isAllowed 필드 확인.
422 transaction_limit_exceeded: 일/주/월 한도 초과. 기본 카드 한도는 일 $2,000, 월 $10,000(강화 KYC 전).
429 rate_limited: 분당 약 100회 초과 시 발생. 통화 목록, 견적 등은 캐싱 필수.

상태 관리는 웹훅을 신뢰하세요. 사용자가 브라우저를 닫아도 transaction_updated에서 status: completed 수신 시 자금이 입금된 상태입니다.

다중 지갑 지원 시, MetaMask API 사용법, 최고의 암호화폐 지갑 API 가이드도 참고하세요. KYC는 최고의 KYC API 비교 글을 참고.

MoonPay 가격

카드 구매: 3.5%-4.5%(최소 $3.99)
은행 송금(ACH, SEPA 등): 1%-1.9% (대량 거래에 더 저렴)
네트워크 수수료: 실제 체인 수수료가 원가로 전달됨
판매(오프램프): 구조 유사, 지급 수수료는 결제 종류별 상이

대량 거래/통합 시 수익 분배 및 맞춤형 가격 책정 협상 가능.

Apidog로 MoonPay 테스트하기

MoonPay 통합의 장애 포인트는 주로 서명 URL, HMAC 웹훅입니다. 이는 애플리케이션 코드보다 강력한 API 클라이언트에서 디버깅하는 것이 효과적입니다.

Apidog에서는 MoonPay OpenAPI 스펙을 가져와 샌드박스 키를 환경 변수로 지정하고,

구매 견적, 거래 상태, 웹훅 재실행을 백엔드 수정 없이 빠르게 반복 테스트할 수 있습니다.

실전 워크플로:

sandbox/production 환경 분리
Node 서명 스니펫을 사전 요청 훅에 추가
거래 ID를 변수로 저장해 createTransaction→getTransactionStatus로 바로 이동
프로덕션 웹훅 도착 시, 원본 바디를 Apidog 모의 서버에 복사해 로컬 엔드포인트에 재실행
서명 훅, 모의 서버, 환경 전환기를 한 곳에서 사용하려면 Apidog를 다운로드하세요.

자주 묻는 질문

MoonPay 외에 별도 KYC 공급업체가 필요한가요?

필요 없습니다. MoonPay가 서버 측에서 신원 검증을 처리하며, 앱에서는 신분증을 볼 필요가 없습니다.

다른 영역에서 사전 KYC 검증이 필요하다면 최고의 KYC API 글 참고.

MoonPay 브랜드 위젯 없이 직접 구현 가능?

네, 직접 REST API나 헤드리스 SDK로 구현할 수 있습니다. 브랜드 위젯이 자동 처리하는 공개사항들이 많으므로, 비브랜드 방식은 추가 규정 준수 검토가 필요합니다. 대부분 팀은 위젯 기반 MVP로 시작 후 거래량 증가 시 마이그레이션합니다.

MoonPay 지원 국가는?

구매: 160개국 이상, 판매: 약 50개국. 통화/결제수단 가용성은 국가별 상이. 통화 엔드포인트로 실시간 확인 가능.

거래 소요 시간은?

카드 결제는 보통 5분 이내, 은행 송금은 1~3영업일 후 암호화폐 지급. 판매(오프램프)는 온체인 확인 후 1~3일 이내 법정화폐 지급.

웹훅 실패 시?

MoonPay는 최대 24시간 동안 지수 백오프로 재시도합니다. 이벤트 처리 후 2xx 응답만 반환하세요. 중복 수신 방지를 위해 id 기준 dedupe 필요.

샌드박스와 프로덕션의 차이점?

거의 유사하나, 샌드박스는 지리적 제한 완화, 테스트 KYC, 거래 상태 수동 변경 등 차이 있음. 키 발급 후 반드시 프로덕션 스모크 테스트 필수.

DEV Community