Quickstart빠른 시작

Take one test payment end to end: create a session, pay it on a testnet, and receive the signed webhook. About ten minutes.

테스트 결제 한 건을 처음부터 끝까지 진행합니다. 세션을 만들고, 테스트넷에서 결제하고, 서명된 웹훅을 받습니다. 약 10분이면 됩니다.

Before you start시작하기 전에

1. Console account in test mode. Everything below uses testnets and test keys — no real funds.
2. Payout wallet. Console → Settings → Payout Wallet. Each deposit address is committed to this wallet, so a session cannot issue an address without one. Register an address for every network family you accept (EVM 0x…, Tron T…, Solana) — see Payout wallets below.
3. Test API key. Console → Developers → API Keys → create a bp_test_… key. It is shown once. Keep it on your server — never in a browser or app bundle.
4. A testnet wallet with a little gas (for example Base Sepolia ETH) to send the payment. The checkout page's test faucet mints test tokens, not gas.

1. 테스트 모드의 콘솔 계정. 아래 과정은 모두 테스트넷과 테스트 키를 사용하며, 실제 자금은 쓰이지 않습니다.
2. 정산 지갑. 콘솔 → 설정 → 정산 지갑. 모든 입금 주소는 이 지갑에 고정(commit)되므로, 정산 지갑이 없으면 세션이 입금 주소를 발급할 수 없습니다. 결제받을 네트워크 계열마다(EVM 0x…, Tron T…, Solana) 주소를 등록하세요 — 아래 정산 지갑을 참고하세요.
3. 테스트 API 키. 콘솔 → 개발자 → API 키에서 bp_test_… 키를 만듭니다. 키는 한 번만 표시됩니다. 서버에만 보관하고, 브라우저나 앱 번들에는 절대 넣지 마세요.
4. 결제를 보낼 테스트넷 지갑과 약간의 가스비(예: Base Sepolia ETH). 결제 페이지의 테스트 faucet은 가스가 아니라 테스트 토큰만 발행합니다.

Payout wallets정산 지갑

Payments settle straight to your own wallet — BitPal never holds them. You register one payout address per network family (VM) in Console → Settings → Payout Wallet. There is no API for this; it is console-only.

결제 대금은 판매자 본인의 지갑으로 바로 정산되며, BitPal은 자금을 보관하지 않습니다. 정산 주소는 네트워크 계열(VM)마다 하나씩 콘솔 → 설정 → 정산 지갑에서 등록합니다. 이 설정용 API는 없으며 콘솔에서만 할 수 있습니다.

• Test and live are separate. Wallets are registered per mode: switch the console to TEST to register test payout wallets, and to LIVE for live ones. A test wallet is never used for live payments, or the other way round.
• A family without a wallet is not offered. If the buyer can choose, networks of a family with no payout wallet in that mode are left out of the payment options. If you fix the network with pay_chain (or a deposit address is requested on it), the call fails with 400 SELLER_WALLET_NOT_CONFIGURED. There is no fallback to another family or another wallet. A session created without pay_chain needs at least one payout wallet (any family) in that mode — if allowed_pay_chains / allowed_assets are set, a wallet for one of the listed networks' families. Without any network restriction, a session offers Base USDC if you have an EVM wallet, otherwise the networks of the families you registered.
• Changing a wallet applies to deposit addresses issued afterwards. An address that was already issued is committed to the payout wallet of that moment (the commitment is part of the address), so a payment to it still settles there.

• 테스트와 라이브는 분리되어 있습니다. 지갑은 모드별로 등록합니다. 테스트 정산 지갑은 콘솔을 TEST로, 라이브 정산 지갑은 LIVE로 전환한 뒤 등록하세요. 테스트 지갑이 라이브 결제에 쓰이거나 그 반대가 되는 일은 없습니다.
• 지갑이 없는 계열은 결제 옵션에 나오지 않습니다. 구매자가 네트워크를 고를 수 있는 경우, 해당 모드에 정산 지갑이 없는 계열의 네트워크는 결제 옵션에서 빠집니다. pay_chain으로 네트워크를 고정했거나 그 네트워크로 입금 주소를 요청하면 400 SELLER_WALLET_NOT_CONFIGURED로 실패합니다. 다른 계열이나 다른 지갑으로 대체되지 않습니다. pay_chain 없이 만드는 세션은 해당 모드에 정산 지갑이 계열과 무관하게 하나 이상 있어야 합니다(allowed_pay_chains / allowed_assets를 지정했다면 그중 한 네트워크 계열의 지갑). 네트워크 제한이 없는 세션은 EVM 지갑이 있으면 Base USDC를, 없으면 등록한 계열의 네트워크를 결제 옵션으로 제시합니다.
• 지갑을 변경하면 그 이후 발급되는 입금 주소부터 적용됩니다. 이미 발급된 주소는 발급 시점의 정산 지갑에 고정되어 있으므로(주소 자체에 포함됨), 그 주소로 들어온 결제는 계속 기존 지갑으로 정산됩니다.

1. Create a checkout session1. 결제 세션 만들기

Install the SDK, or call the REST API directly.

SDK를 설치하거나 REST API를 직접 호출합니다.

npm install @bitpal/checkout

import { BitPal } from '@bitpal/checkout';

const bitpal = new BitPal(process.env.BITPAL_API_KEY); // bp_test_…

const { data: session } = await bitpal.checkout.createSession({
  line_items: [{ name: 'Pro plan', amount: '29', currency: 'USDC' }],
  pay_chain: 'eip155:84532',            // Base Sepolia (test key → testnet values only)
  expires_in_minutes: 30,               // payment window, 1–60 (default 15)
  success_url: 'https://your.store/thanks?session={CHECKOUT_SESSION_ID}',
});
// store session.id with your order, then send the buyer to session.checkout_url

The same request over HTTP:

같은 요청을 HTTP로 보내면 다음과 같습니다.

curl -X POST https://api.bitpal.io/v1/checkout/sessions \
  -H "Authorization: Bearer $BITPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024" \
  -d '{
    "line_items": [{ "name": "Pro plan", "amount": "29", "currency": "USDC" }],
    "pay_chain": "eip155:84532",
    "expires_in_minutes": 30,
    "success_url": "https://your.store/thanks?session={CHECKOUT_SESSION_ID}"
  }'

Response 201:

응답 201:

{
  "data": {
    "id": "cs_Q2FxKhomCEju_OqvKfrQsTOh",
    "checkout_url": "https://bitpal.io/pay/cs_Q2FxKhomCEju_OqvKfrQsTOh?token=<session_token>",
    "session_token": "<session_token>",
    "status": "created",
    "amount_total": "29000000",
    "currency": "USDC",
    "expires_at": "2026-11-06T07:58:28.776Z",
    "tax": { "tax_amount": "0", "total_with_tax": "29000000" }
  },
  "meta": { "mode": "TEST", "requestId": "ec091faf-…" }
}

• amount is a plain number string in the line item's currency — no decimals to compute. amount_total comes back as a 6-decimal integer string ("29000000" = 29).
• Minimum: the session total (sum of amount × quantity) must be at least 1.00 in the session currency ($1 for USDC/USDT, ¥1 for JPYC), otherwise 400 CHECKOUT_AMOUNT_TOO_LOW. Some networks have a higher minimum — Tron currently $300 (testnet included), JPYC ¥100 on every network; such a network is not offered for a smaller total (or 400 CHECKOUT_BELOW_MIN_PAYMENT if you fixed it with pay_chain).
• Idempotency-Key (8–128 chars) makes retries safe: the same key and body within 24 hours returns the original response with X-Idempotency-Replayed: true.
• {CHECKOUT_SESSION_ID} in success_url is replaced with the session id when the buyer returns.

• amount는 line item의 통화 단위로 쓴 일반 숫자 문자열입니다 — decimals를 계산할 필요가 없습니다. amount_total은 소수점 6자리 정수 문자열로 반환됩니다("29000000" = 29).
• 최소 금액: 세션 총액(amount × quantity의 합)은 세션 통화 기준 1.00 이상이어야 합니다(USDC/USDT는 $1, JPYC는 ¥1). 미만이면 400 CHECKOUT_AMOUNT_TOO_LOW가 반환됩니다. 일부 네트워크는 최소 금액이 더 높습니다 — 현재 Tron은 $300(테스트넷 포함), JPYC는 모든 네트워크에서 ¥100입니다. 총액이 그보다 작으면 해당 네트워크는 결제 옵션에 나오지 않습니다(pay_chain으로 고정했다면 400 CHECKOUT_BELOW_MIN_PAYMENT).
• Idempotency-Key(8–128자)를 보내면 재시도가 안전해집니다. 24시간 안에 같은 키와 같은 본문으로 다시 요청하면 원래 응답이 X-Idempotency-Replayed: true와 함께 반환됩니다.
• success_url의 {CHECKOUT_SESSION_ID}는 구매자가 돌아올 때 세션 id로 바뀝니다.

2. Send the buyer to the checkout page2. 구매자를 결제 페이지로 보내기

Redirect to checkout_url, or open it in a popup so the buyer stays on your page (see Popup & headless). On the page the buyer:

checkout_url로 리다이렉트하거나, 구매자가 페이지를 떠나지 않도록 팝업으로 엽니다(팝업 & 헤드리스 참고). 결제 페이지에서 구매자는 다음을 진행합니다.

1. picks a network and token (if you allowed more than one),
2. enters a refund address — over/under-payments are returned there,
3. gets a one-time deposit address and the exact amount, and sends it from any wallet or exchange.

1. 네트워크와 토큰을 고릅니다(둘 이상 허용한 경우).
2. 환불 주소를 입력합니다 — 과다·과소 입금액은 이 주소로 반환됩니다.
3. 일회용 입금 주소와 정확한 금액을 받고, 아무 지갑이나 거래소에서 송금합니다.

In test mode the page shows Get test assets: it mints test tokens to the buyer's wallet so you can complete a real on-chain payment.

테스트 모드에서는 결제 페이지에 테스트 자산 받기가 표시됩니다. 구매자 지갑으로 테스트 토큰을 발행해 주므로 실제 온체인 결제를 끝까지 해볼 수 있습니다.

3. Receive the webhook3. 웹훅 받기

Console → Developers → Webhooks → Add Endpoint. The URL must be publicly reachable over HTTPS (for local development use a tunnel such as ngrok or cloudflared). Copy the signing secret (whsec_…) — it is shown once.

콘솔 → 개발자 → 웹훅 → 엔드포인트 추가. URL은 HTTPS로 외부에서 접근할 수 있어야 합니다(로컬 개발 중이라면 ngrok, cloudflared 같은 터널을 쓰세요). 서명 시크릿(whsec_…)은 한 번만 표시되니 복사해 두세요.

import express from 'express';
import { verifyWebhookSignature, parseWebhookEvent, WEBHOOK_HEADERS } from '@bitpal/checkout';

const app = express();

app.post('/webhooks/bitpal', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8');                     // exact bytes BitPal signed
  const ok = await verifyWebhookSignature(                   // async — always await it
    raw,
    req.header(WEBHOOK_HEADERS.signature) ?? '',
    process.env.BITPAL_WEBHOOK_SECRET,                       // whsec_…
    { timestamp: req.header(WEBHOOK_HEADERS.timestamp) ?? '' },
  );
  if (!ok) return res.status(400).send('invalid signature');

  const event = parseWebhookEvent(raw);
  if (await alreadyProcessed(event.id)) return res.sendStatus(200); // at-least-once delivery

  if (event.event === 'checkout.session.paid') {
    await fulfilOrder(event.data.session_id, { late: event.data.late === true });
  }
  await markProcessed(event.id);
  res.sendStatus(200);                                       // any 2xx within 10 s = delivered
});

For one successful payment you receive, in order: checkout.session.created → checkout.session.deposit_detected → checkout.session.paid → checkout.session.settled. deposit_detected is not guaranteed: paid can arrive without it (a late payment, or a deposit that was already fully confirmed when BitPal first saw it), so never wait for it before fulfilling. Use Send Test in the console to check your endpoint before paying.

결제 한 건이 성공하면 다음 순서로 이벤트를 받습니다: checkout.session.created → checkout.session.deposit_detected → checkout.session.paid → checkout.session.settled. deposit_detected는 보장되지 않습니다. 늦은 결제이거나 BitPal이 처음 확인했을 때 이미 블록 확정이 끝난 입금이면 paid가 단독으로 올 수 있으니, 주문 처리 전에 이 이벤트를 기다리지 마세요. 결제 전에 콘솔의 테스트 전송으로 엔드포인트를 먼저 확인할 수 있습니다.

4. Fulfil on checkout.session.paid4. checkout.session.paid에서 주문 처리하기

• paid means the deposit reached the required confirmations — safe to fulfil. settled follows when funds are swept to your payout wallet.
• Treat the webhook (or a server-side getSession(id)) as the source of truth. The redirect to success_url and popup messages are hints for your UI only.
• Check data.late: true means the full amount arrived after the payment window (accepted for up to 7 days). Decide whether to fulfil or refund it from the console — or create sessions with "late_payments": "refund" so late payments are refunded automatically instead (Payment lifecycle).

• paid는 입금이 필요한 블록 확정 수에 도달했다는 뜻입니다 — 주문을 처리해도 안전합니다. 이어서 자금이 정산 지갑으로 옮겨지면 settled가 옵니다.
• 웹훅(또는 서버에서 호출한 getSession(id))을 기준으로 판단하세요. success_url 리다이렉트와 팝업 메시지는 UI용 힌트일 뿐입니다.
• data.late를 확인하세요. true는 결제 기한이 지난 뒤 전액이 도착했다는 뜻입니다(최대 7일까지 인정). 주문을 처리할지, 콘솔에서 환불할지 판단하세요. 늦은 결제를 아예 받지 않으려면 세션을 "late_payments": "refund"로 만들어 자동 환불되게 할 수 있습니다(결제 생애주기).

Going live라이브 전환

1. Create a bp_live_… key and switch chain values to mainnet (Chains & contracts).
2. Register live payout wallets — test and live are separate environments.
3. Add the webhook endpoint again in live mode. It gets its own whsec_… secret.
4. Handle the non-happy paths: checkout.session.unresolved, checkout.session.expired, checkout.refund.recorded and late payments (Payment lifecycle).

1. bp_live_… 키를 만들고 체인 값을 메인넷으로 바꿉니다(체인 & 컨트랙트).
2. 라이브 정산 지갑을 등록합니다 — 테스트와 라이브는 별도 환경입니다.
3. 라이브 모드에서 웹훅 엔드포인트를 다시 추가합니다. 별도의 whsec_… 시크릿이 발급됩니다.
4. 정상 흐름 외의 경우도 처리하세요: checkout.session.unresolved, checkout.session.expired, checkout.refund.recorded, 늦은 결제(결제 생애주기).

SDK

Create checkout sessions from your backend and redirect buyers to the hosted page.

백엔드에서 결제 세션을 만들고 구매자를 호스티드 결제 페이지로 보냅니다.

Install & create a session설치 & 세션 생성

npm install @bitpal/checkout

import { BitPal } from '@bitpal/checkout';
const bitpal = new BitPal(process.env.BITPAL_API_KEY); // bp_test_… or bp_live_…

// A CAIP-2 id is absolute: 'eip155:8453' (Base mainnet) works only with a live key —
// with a test key it fails with CHAIN_MODE_MISMATCH. Use 'eip155:84532' for test, or a short name.
const { data: session } = await bitpal.checkout.createSession({
  line_items: [{ name: 'Pro plan', amount: '29', currency: 'USDC' }],
  pay_chain: 'base',                 // short name → Base Sepolia with bp_test_, Base with bp_live_
  expires_in_minutes: 30,                // payment window 1–60, default 15
  success_url: 'https://your.store/thanks?s={CHECKOUT_SESSION_ID}',
});
redirect(session.checkout_url);

Amounts — just pass the number금액 — 숫자만 넣으세요

Set amount to a plain number ("29", "0.5") in the line item's currency. No decimals to compute.

amount에는 line item currency 기준의 일반 숫자("29", "0.5")를 넣습니다. decimals를 계산할 필요가 없습니다.

Example: buyer chooses chain & token예시: 구매자가 체인·토큰 선택

await bitpal.checkout.createSession({
  line_items: [{ name: 'Order #1024', amount: '49.90', currency: 'USDC' }], // currency = price denomination
  allowed_assets: [                            // (chain, token) pairs — the buyer picks one; mix tokens freely
    { chain: 'base',     token: 'USDC' },
    { chain: 'arbitrum', token: 'USDC' },
    { chain: 'tron',     token: 'USDT' },
    { chain: 'solana',   token: 'USDC' },
  ],
  // shorthand for one token across chains: allowed_pay_chains: ['base','arbitrum','solana']
});

Example: poll status예시: 상태 폴링

const { data } = await bitpal.checkout.getStatus(sessionId);
if (data.status === 'paid_confirmed' || data.status === 'swept') showSuccess(); // UI only — fulfil from the webhook

Status values: created → awaiting_deposit → deposit_detected → paid_confirmed → swept, plus expired, unresolved_underpaid, wrong_token. (Sessions opened through the legacy wallet-connect flow may report pending_payment; treat it like created.) See Payment lifecycle.

상태값: created → awaiting_deposit → deposit_detected → paid_confirmed → swept, 그 밖에 expired, unresolved_underpaid, wrong_token이 있습니다. (예전 지갑 연결 방식으로 열린 세션은 pending_payment를 반환할 수 있으며, created와 같이 취급하면 됩니다.) 자세한 내용은 결제 생애주기를 참고하세요.

Method reference메서드 레퍼런스

Amount helpers (advanced, for amount_atomic): toAtomic(v, decimals) / fromAtomic(v, decimals).

금액 헬퍼(고급, amount_atomic용): toAtomic(v, decimals) / fromAtomic(v, decimals).

Popup & headless팝업 & 헤드리스

Choose how the buyer sees the payment. Every flow ends the same way: you fulfil from the webhook.

구매자에게 결제 화면을 어떻게 보여 줄지 고릅니다. 어떤 방식이든 마무리는 같습니다 — 주문 처리는 웹훅을 기준으로 합니다.

Choose a flow방식 고르기

Popup팝업

Browsers block window.open unless it runs directly in the click handler. Open an empty window first, then point it at the checkout URL once your backend has created the session.

브라우저는 클릭 핸들러 안에서 바로 실행되지 않은 window.open을 차단합니다. 먼저 빈 창을 열어 두고, 백엔드가 세션을 만든 뒤 그 창을 결제 URL로 이동시키세요.

async function onPayClick() {
  // 1) open synchronously, inside the click handler
  const popup = window.open('', 'bitpal_checkout', 'width=460,height=720');

  // 2) your backend creates the session (secret key stays on the server)
  const { checkout_url, session_id } = await fetch('/api/checkout', { method: 'POST' }).then((r) => r.json());

  // 3) navigate the popup — or fall back to a full redirect if it was blocked
  if (popup && !popup.closed) popup.location.href = checkout_url;
  else window.location.href = checkout_url;

  const origin = new URL(checkout_url).origin;
  window.addEventListener('message', function onMessage(e) {
    if (e.origin !== origin) return;                       // trust only the checkout page
    const m = e.data;
    if (!m || m.source !== 'bitpal-checkout' || m.type !== 'terminal') return;
    window.removeEventListener('message', onMessage);
    refreshOrderFromServer(session_id);                     // m.step: done | expired | error
  });
}

When the payment reaches a final screen, the checkout page posts one message to its opener:

결제가 최종 화면에 도달하면 결제 페이지가 자신을 연 창(opener)으로 메시지를 하나 보냅니다.

{ "source": "bitpal-checkout", "type": "terminal", "step": "done", "session_id": "cs_…" }

• step is done, expired or error. One terminal message is sent per final screen.
• If the buyer sends the wrong token, the page posts { "type": "status", "step": "wrong_token" } instead. It is not final: the wrong token is returned and the session can still be paid with the right one, so keep listening for terminal.
• The message is a UI hint. Re-read the order from your server (which learned the result from the webhook) before showing success.
• Messages can be lost (the buyer closes the window, browser privacy settings). Keep a fallback: poll your own backend for the order status.
• Don't close the popup yourself — the completion screen lets the buyer email a receipt. The popup closes itself only after the buyer sends that receipt; otherwise the buyer closes it with the Close button, so don't wait for the window to close.

• step은 done, expired, error 중 하나입니다. 최종 화면마다 terminal 메시지가 한 번 전송됩니다.
• 구매자가 잘못된 토큰을 보내면 대신 { "type": "status", "step": "wrong_token" }이 전송됩니다. 이는 최종 상태가 아닙니다. 잘못 보낸 토큰은 반환되고 올바른 토큰으로 계속 결제할 수 있으니, terminal 메시지를 계속 기다리세요.
• 이 메시지는 UI 힌트입니다. 성공 화면을 보여 주기 전에 서버(웹훅으로 결과를 받은)에서 주문 상태를 다시 읽으세요.
• 메시지는 유실될 수 있습니다(구매자가 창을 닫거나 브라우저 개인정보 설정 등). 대비책으로 자체 백엔드에서 주문 상태를 폴링하세요.
• 팝업을 직접 닫지 마세요 — 완료 화면에서 구매자가 영수증을 이메일로 받을 수 있습니다. 팝업은 구매자가 영수증을 보낸 뒤에만 스스로 닫히고, 그 밖에는 구매자가 닫기 버튼으로 닫습니다. 창이 닫히기를 기다리지 마세요.

Headless (your own UI)헤드리스 (직접 만든 UI)

Use this when you render the payment screen yourself. The buyer still pays to a per-order deposit address; you just display it.

결제 화면을 직접 렌더링할 때 사용합니다. 구매자는 여전히 주문별 입금 주소로 결제하며, 판매자는 그 주소를 화면에 보여 주기만 하면 됩니다.

1. Create the session on your server (as in the Quickstart). Keep id and session_token.서버에서 세션을 만듭니다(빠른 시작과 동일). id와 session_token을 보관하세요.
2. Show the payment options. getPublicSession(id) returns payment_options — one entry per allowed (chain, token) with caip2, token_symbol, decimals and the exact amount_atomic.결제 옵션을 보여 줍니다. getPublicSession(id)는 payment_options를 반환합니다. 허용된 (체인, 토큰)마다 항목이 하나씩 있으며 caip2, token_symbol, decimals, 정확한 amount_atomic이 담겨 있습니다.
3. Collect a refund address from the buyer, in the format of the chosen network (EVM 0x…, Tron T…, Solana base58). It is committed into the deposit address and cannot change.구매자에게서 선택한 네트워크 형식(EVM 0x…, Tron T…, Solana base58)의 환불 주소를 받습니다. 환불 주소는 입금 주소에 고정되며 바꿀 수 없습니다.
4. Issue the deposit address (backend):입금 주소를 발급합니다(백엔드):

   const { data } = await bitpal.checkout.issueDepositAddress(session.id, {
     session_token: session.session_token,
     refundAddress: '0xBuyerRefundWallet…',
     chain: 'eip155:84532',
     token: 'USDC',
   });
   // {
   //   "sessionId": "cs_…",
   //   "chain": "eip155:84532",
   //   "depositAddress": "0x6b19e871c934aB52775B6712e110f3e4b0626347",
   //   "expectedToken": "0x943b94dacf1507f2658f1cfe103ac36ebc13ef65",
   //   "expectedAmount": "29000000",     // in the token's own decimals
   //   "feeAmount": "435000",
   //   "refundAddress": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720",
   //   "deadline": "1793957308",       // on-chain deadline (unix s) = expiresAt + 5400 (90-minute grace)
   //   "expiresAt": "2026-11-06T07:58:28.776Z"
   // }

5. Display the address, a QR code and the exact amount — format expectedAmount with the token's decimals (6 for USDC, 18 for BNB USDT and JPYC). Show the countdown to expiresAt.주소, QR 코드, 정확한 금액을 표시합니다 — expectedAmount는 토큰의 decimals(USDC 6, BNB USDT·JPYC 18)로 변환해 보여 주세요. expiresAt까지 남은 시간도 표시합니다.
6. Track status through your backend (getStatus(id)) for the UI, and fulfil from the webhook.UI용 상태는 백엔드를 통해 확인하고(getStatus(id)), 주문 처리는 웹훅을 기준으로 합니다.

Calling issueDepositAddress again for the same session returns the same address and keeps the first refund address — a later call cannot change it. A deposit address belongs to one order; don't reuse it.

같은 세션에 issueDepositAddress를 다시 호출하면 같은 주소가 반환되고 처음 입력한 환불 주소가 유지됩니다 — 이후 호출로는 바꿀 수 없습니다. 입금 주소는 주문 하나에만 속하므로 재사용하지 마세요.

Payment links결제 링크 no code

A shareable URL for a price. The flow is Product → Price → Payment link.

가격(price)마다 공유할 수 있는 URL입니다. 흐름은 상품 → 가격 → 결제 링크입니다.

From the dashboard (no code)대시보드에서 (코드 없이)

1. Create a product (e.g. "Pro plan").
2. Add a price — amount + token.
3. Generate a payment link from that price and share the URL.

1. 상품을 만듭니다(예: "Pro plan").
2. 가격을 추가합니다 — 금액과 토큰.
3. 그 가격으로 결제 링크를 만들고 URL을 공유합니다.

Buyers pay on the hosted page; you still get webhooks and dashboard orders.

구매자는 호스티드 결제 페이지에서 결제하며, 웹훅과 대시보드 주문 내역도 동일하게 받습니다.

From the API / SDKAPI / SDK에서

Same three steps in code: create a product, add a price, then a payment link from that price.

코드에서도 세 단계는 같습니다: 상품을 만들고, 가격을 추가하고, 그 가격으로 결제 링크를 만듭니다.

// 1. Product
const { data: product } = await bitpal.checkout.products.create({ name: 'Pro plan' });

// 2. Price — just the number (no decimals to compute). The asset is token_symbol (USDC / USDT = USD, JPYC = JPY).
const { data: price } = await bitpal.checkout.prices.create(product.id, {
  amount: '29', token_symbol: 'USDC',
});

// 3. Payment link from the price → share link.share_token.
const { data: link } = await bitpal.checkout.paymentLinks.create({
  price_id: price.id,
  allowed_pay_chains: ['eip155:8453', 'solana:5eykt4…'],
});
// Hosted URL: `${checkoutBase}/plink/${link.share_token}`

x402

Charge per API call. The caller pays with a signed authorization and retries — no checkout page, no redirect.

API 호출 단위로 과금합니다. 호출자가 서명으로 결제하고 재요청 — 결제 페이지도 리다이렉트도 없습니다.

How it works동작 방식

1. An unpaid request to your route returns 402 with the payment terms.
2. The caller signs an EIP-3009 authorization (gasless — signature only) and retries with an X-PAYMENT header.
3. BitPal verifies the signature and broadcasts it. Funds move from the payer through a per-terms settlement address that pays you and the fee wallet in the same transaction — BitPal never holds them.
4. Your handler runs and the response carries X-PAYMENT-RESPONSE with the transaction hash.

1. 결제되지 않은 요청에는 라우트가 402와 결제 조건을 반환합니다.
2. 호출자가 EIP-3009 authorization에 서명하고(가스 불필요 — 서명만) X-PAYMENT 헤더를 붙여 다시 요청합니다.
3. BitPal이 서명을 검증하고 브로드캐스트합니다. 자금은 결제자에서 결제 조건별 정산 주소로 이동하고, 같은 트랜잭션 안에서 판매자 정산 지갑과 수수료 지갑으로 나뉘어 지급됩니다 — BitPal은 자금을 보관하지 않습니다.
4. 핸들러가 실행되고, 응답에 트랜잭션 해시가 담긴 X-PAYMENT-RESPONSE가 붙습니다.

Add it to a route라우트에 붙이기

npm install @bitpal/checkout

import { x402 } from '@bitpal/checkout';

// $1.00 USDC per call
app.get('/report', x402({
  apiKey: process.env.BITPAL_API_KEY,   // bp_test_… or bp_live_…
  payTo: '0xYourPayoutWallet', // the payout wallet registered in Console for this mode — anything else: PAYTO_NOT_MERCHANT_WALLET
  network: 'base',                  // test key → 'base-sepolia'
  amount: '1.00',                    // 사람 표기 — decimals 계산 불필요
}), (req, res) => {
  res.json({ report: '…' });
});

Other runtimes — Hono, Fastify, Next.js다른 런타임 — Hono, Fastify, Next.js

The x402() adapter above is Express-shaped. Everywhere else, use X402Gate directly — it takes the incoming header and hands back what to send. Same logic, no framework assumptions.

위 x402() 어댑터는 Express 모양입니다. 그 외 런타임은 X402Gate 를 직접 쓰세요 — 들어온 헤더를 넣으면 무엇을 응답할지 돌려줍니다. 로직은 같고 프레임워크 가정만 없습니다.

import { X402Gate, createMemoryReplayStore, X402_PAYMENT_RESPONSE_HEADER } from '@bitpal/checkout';

// 반드시 모듈 스코프에 하나 — 아래 경고 참조
const replayStore = createMemoryReplayStore();

const gate = new X402Gate({
  apiKey: process.env.BITPAL_API_KEY,
  payTo: '0xYourPayoutWallet',
  network: 'base',
  amount: '1.00',
  replayStore,
});

// Hono 예시 — Next.js Route Handler 도 모양이 같다
app.get('/report', async (c) => {
  const url = new URL(c.req.url);
  // 결제는 이 문자열에 묶인다. 402 와 재요청에서 같은 값이어야 한다(쿼리 제외).
  const resource = `${url.origin}${url.pathname}`;

  const result = await gate.collect({ header: c.req.header('x-payment'), resource });
  if (result.kind !== 'settled') {
    // 402(미결제) · 409(재사용) · 503(미확정) 을 그대로 옮긴다
    return c.json(result.body, result.status);
  }

  c.header(X402_PAYMENT_RESPONSE_HEADER, result.paymentResponseHeader);
  return c.json({ report: '…' });   // 결제된 요청만 여기 도달
});

The 402 response402 응답

This is standard x402 — a stock client such as x402-fetch can pay it. payTo is not your wallet: it is a CREATE2 address derived from the payment terms, which is what lets the caller sign a single authorization and still have the fee split correctly. feeBreakdown is a BitPal extension and is informational — a caller may ignore it and still pay correctly.

x402 표준 그대로라 x402-fetch 같은 순정 클라이언트도 결제할 수 있습니다. payTo 는 정산 지갑이 아닙니다 — 결제 조건에서 유도된 CREATE2 주소이고, 그 덕에 호출자가 authorization 1건만 서명해도 수수료가 정확히 나뉩니다. feeBreakdown 은 BitPal 확장이며 참고용입니다 — 호출자가 무시해도 정상 결제됩니다.

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    // 정산 지갑이 아니라 조건에서 유도된 정산 주소 (CREATE2)
    "payTo": "0xSettlementAddressDerivedFromTerms",
    // gross — 수수료 차감 전 총액. 호출자는 이 금액을 payTo 로 서명한다.
    "maxAmountRequired": "1000000",
    "resource": "https://your.api/report",
    "extra": { "name": "USD Coin", "version": "2", "chainId": 8453 },
    "feeBreakdown": {
      "netAmount": "985000",
      "feeAmount": "15000",
      "feeBps": 150,
      "feeRecipient": "0x…"
    }
  }]
}

Rules worth knowing알아둘 규칙

• Exact amounts only. Over- and underpayment are both rejected — there is no refund path on this lane.
• One payment, one response. A given authorization unlocks a single response; replaying it does not buy another call.
• Bound to the resource. A payment verified for one route cannot be settled against another.
• EOA signers only. Smart-contract wallets cannot sign EIP-3009 authorizations.
• Standard x402 payload. The caller signs one authorization — any x402 client works, including ones that have never heard of BitPal.
• If settle times out, poll the payment status instead of retrying blindly — the call is idempotent either way.

• 정확한 금액만. 과다·과소 지급 모두 거부됩니다 — 이 레인엔 환불 경로가 없습니다.
• 결제 1건 = 응답 1건. 한 authorization 은 한 번의 응답만 열어줍니다. 재전송해도 추가 호출이 되지 않습니다.
• 리소스에 묶입니다. 한 라우트로 검증된 결제를 다른 라우트에 정산할 수 없습니다.
• EOA 서명자만. 스마트컨트랙트 지갑은 EIP-3009 서명을 만들 수 없습니다.
• x402 표준 payload. 호출자는 authorization 1건만 서명합니다 — BitPal 을 모르는 x402 클라이언트도 그대로 결제할 수 있습니다.
• settle 이 타임아웃되면 무작정 재시도하지 말고 결제 상태를 조회하세요 — 어느 쪽이든 멱등합니다.

When settle is uncertain정산이 불확실할 때

If the chain is slow or the broadcast result is unknown, the gate returns 503 instead of your resource. Do not retry blindly — the payment may well have gone through. You have two ways to learn the outcome, and they carry the same answer:

체인이 느리거나 브로드캐스트 결과가 불확실하면 게이트가 리소스 대신 503 을 돌려줍니다. 무작정 재시도하지 마세요 — 결제는 이미 나갔을 수 있습니다. 결말을 아는 방법이 둘이고, 답은 같습니다:

• Poll — GET /v1/x402/payments/:id with the paymentId from the 503 body.폴링 — 503 바디의 paymentId 로 GET /v1/x402/payments/:id.
• Webhook — x402.payment.resolved is pushed once BitPal settles the question, so you do not have to sit on a polling loop.웹훅 — BitPal 이 결말을 내면 x402.payment.resolved 가 날아옵니다. 폴링 루프를 붙들고 있을 필요가 없습니다.

Supported지원 범위

Test keys accept only base-sepolia; live keys only base. More chains follow the same flow as they are enabled — see Chains & contracts.

테스트 키는 base-sepolia 만, 라이브 키는 base 만 받습니다. 체인이 추가되면 동일한 흐름을 따릅니다 — 체인 & 컨트랙트 참조.

Payment lifecycle결제 생애주기

What a session goes through, what each state means for you, and how amounts, late payments and refunds work.

세션이 거치는 상태와 각 상태에서 판매자가 할 일, 그리고 금액·늦은 결제·환불이 어떻게 처리되는지 설명합니다.

States상태

created ──▶ awaiting_deposit ──▶ deposit_detected ──▶ paid_confirmed ──▶ swept
               │      ▲   │                 │
               │      │   └─▶ unresolved_underpaid ──(deadline)──▶ expired  (partial refund)
               │      └────── wrong_token  (wrong asset returned; still payable)
               └──(deadline, nothing paid)──▶ expired

Amounts금액

Handle all amounts as strings or big integers — never as floating-point numbers.

모든 금액은 문자열이나 큰 정수(BigInt 등)로 다루고, 부동소수점 숫자로 계산하지 마세요.

Minimum amount. A session's total (sum of amount × quantity) must be at least 1.00 in the session currency (USDC/USDT: $1, JPYC: ¥1) — a lower total returns 400 CHECKOUT_AMOUNT_TOO_LOW. The schema can't express this (it is a rule on the sum, and amount alone may be "0"), so check it before calling. Per-network minimums come on top: Tron currently $300 (testnet included) and JPYC ¥100 on every network. A network whose minimum is above the total is not offered to the buyer; requesting a deposit address on it returns 400 CHECKOUT_BELOW_MIN_PAYMENT.

최소 금액. 세션 총액(amount × quantity의 합)은 세션 통화 기준 1.00 이상이어야 합니다(USDC/USDT: $1, JPYC: ¥1). 이보다 적으면 400 CHECKOUT_AMOUNT_TOO_LOW가 반환됩니다. 합계에 대한 규칙이고 amount 하나는 "0"일 수도 있어서 스키마로는 표현되지 않으니, 호출 전에 직접 확인하세요. 네트워크별 최소 금액이 추가로 적용됩니다 — 현재 Tron은 $300(테스트넷 포함), JPYC는 모든 네트워크에서 ¥100입니다. 최소 금액이 총액보다 큰 네트워크는 구매자에게 제시되지 않으며, 그 네트워크로 입금 주소를 요청하면 400 CHECKOUT_BELOW_MIN_PAYMENT가 반환됩니다.

Session fields worth knowing알아 둘 세션 필드

• deposit_tx_hash is the buyer's payment into the deposit address; sweep_tx_hash is the transaction that settled it to your payout wallet (or, for a refunded or rescued session, that on-chain action).
• tx_hash is deprecated. It belonged to an earlier payment path and is kept only for compatibility — it now returns the same value as deposit_tx_hash. Use deposit_tx_hash / sweep_tx_hash.
• received_token is the address of the token contract (or Solana mint) that actually arrived — not a symbol. received_token_symbol gives the symbol (USDC, USDT …), or null for a token BitPal doesn't know (for example a wrong token).
• payer_wallet is the address the deposit came from (or the wallet the buyer connected), in the network's own format — Tron addresses are base58 T…. It may be an exchange's hot wallet, so don't use it as the buyer's identity or refund destination; refunds go to refund_address.
• metadata is returned on the session as you sent it, and is also included in every webhook's data (see Webhooks → Event data). Keys BitPal writes itself — _bitpal, payer_email, allowed_pay_chains, allowed_assets — are reserved and are left out of both; don't use them for your own data.

• deposit_tx_hash는 구매자가 입금 주소로 보낸 결제 트랜잭션이고, sweep_tx_hash는 그 자금을 정산 지갑으로 정산한 트랜잭션입니다(환불되거나 복구(rescue)된 세션이라면 해당 온체인 처리 트랜잭션).
• tx_hash는 deprecated입니다. 예전 결제 경로에서 쓰던 필드로 호환성을 위해서만 남아 있으며, 지금은 deposit_tx_hash와 같은 값을 반환합니다. deposit_tx_hash / sweep_tx_hash를 사용하세요.
• received_token은 실제로 입금된 토큰 컨트랙트(또는 Solana mint)의 주소이며, 심볼이 아닙니다. 심볼은 received_token_symbol(USDC, USDT …)에 있고, BitPal이 모르는 토큰(예: 잘못 보낸 토큰)이면 null입니다.
• payer_wallet은 입금을 보낸 주소(또는 구매자가 연결한 지갑)이며 네트워크 고유 형식입니다 — Tron 주소는 base58 T…입니다. 거래소 핫월렛일 수 있으므로 구매자 식별이나 환불 대상으로 쓰지 마세요. 환불은 refund_address로 갑니다.
• metadata는 세션 조회 시 보낸 그대로 반환되며, 모든 웹훅의 data에도 포함됩니다(웹훅 → 이벤트 데이터 참고). BitPal이 직접 쓰는 키 — _bitpal, payer_email, allowed_pay_chains, allowed_assets — 는 예약되어 있어 두 곳 모두에서 빠지니 자체 데이터에 쓰지 마세요.

Buyer experience구매자 경험

• Receipts. BitPal does not email the buyer automatically. After paying, the buyer can request an emailed receipt on the payment completion screen; customer_email only pre-fills that form. If every buyer needs a receipt or order confirmation, send it yourself from your checkout.session.paid handler.
• Status link. checkout_url (/pay/{id}?token=…) is also the buyer's status page — opening it later shows the payment's current state, and the receipt email links back to it. The token grants access to that page, so share the URL only with the buyer.
• Language. The payment page picks its language from the buyer's browser (12 languages, English as fallback), and the buyer can switch it. You can't set the language from the session or the URL yet.
• Your name and logo. The payment page does not show a merchant name or logo yet. Buyers see the line item names and amounts — make item names recognisable (for example include your store name).
• Support. BitPal doesn't contact your buyers. Product, order and refund questions are yours to answer (completed payments are refunded by you — see Refunds above). For payment problems — funds sent but not detected, a wrong network, a late transfer — contact BitPal support with the session id and the transaction hash.

• 영수증. BitPal은 구매자에게 자동으로 이메일을 보내지 않습니다. 구매자는 결제 완료 화면에서 영수증 이메일을 요청할 수 있고, customer_email은 그 입력란을 미리 채우는 용도일 뿐입니다. 모든 구매자에게 영수증이나 주문 확인이 필요하다면 checkout.session.paid 핸들러에서 직접 보내세요.
• 상태 링크. checkout_url(/pay/{id}?token=…)은 구매자의 결제 상태 페이지이기도 합니다 — 나중에 열면 결제의 현재 상태가 보이고, 영수증 이메일도 이 페이지로 연결됩니다. token이 페이지 접근 권한이므로 URL은 구매자에게만 공유하세요.
• 언어. 결제 페이지는 구매자의 브라우저 설정에 따라 언어를 고르며(12개 언어, 기본은 영어), 구매자가 직접 바꿀 수도 있습니다. 세션이나 URL로 언어를 지정하는 기능은 아직 없습니다.
• 가맹점 이름과 로고. 결제 페이지에는 아직 가맹점 이름이나 로고가 표시되지 않습니다. 구매자는 line item의 name과 금액을 보게 되니, 품목 이름을 알아보기 쉽게 지으세요(예: 스토어 이름 포함).
• 고객 지원. BitPal은 구매자에게 직접 연락하지 않습니다. 상품·주문·환불 문의는 가맹점이 응대합니다(완료된 결제의 환불은 가맹점이 직접 처리합니다 — 아래 환불 참고). 송금했는데 감지되지 않음, 잘못된 네트워크, 늦은 송금 같은 결제 문제는 세션 id와 트랜잭션 해시를 함께 BitPal 지원팀에 문의하세요.

Payment window and late payments결제 기한과 늦은 결제

• The buyer has expires_in_minutes (1–60, default 15) from session creation to pay. That deadline is the session's expires_at.
• late compares the block time of the deposit transaction with expires_at. A transfer sent in time is "late": false even if its confirmations finish after the deadline; checkout.session.settled carries the same value as paid.
• Once a deposit address has been issued, BitPal keeps the session open for 90 minutes after expires_at so transfers already in flight can confirm. Underpayment refunds and checkout.session.expired for an issued session happen at the end of that window.
• A full payment that arrives after the deadline is accepted as a late payment for up to 7 days by default: you get checkout.session.paid with "late": true and the funds settle normally. Decide whether to fulfil, or refund it from the console (see Refunds below).
• Don't want late payments? Create the session with "late_payments": "refund". A full payment that arrives after the deadline (expires_at + 90 minutes) is then never accepted: it stays in the deposit address and is refunded automatically to the buyer's refund address about 7 days after the deadline (refund kind late_deposit, checkout.refund.recorded). The refund can't be instant — BitPal is non-custodial and the deposit contract only lets anyone but you take the funds back after that 7-day window. A transfer sent before expires_at whose confirmations finish later is still accepted.
• This only applies to a session with no earlier on-chain action. If a wrong token was already returned or an underpayment already refunded, the expired session is closed for good: later deposits to its address are not accepted as payment (contact support with the session id and transaction hash).
• Acceptance ends 1 hour before the on-chain refund window opens (expires_at + 90 minutes + 7 days). A full payment that arrives after that cutoff is not accepted; it is refunded automatically once the window opens (refund kind late_deposit).
• A partial payment after the deadline is refunded automatically (refund kind late_deposit).
• Funds sent more than 7 days after the deadline are not watched automatically. Contact support with the session id and transaction hash.

• 구매자는 세션 생성 후 expires_in_minutes(1–60, 기본 15) 안에 결제해야 합니다. 이 기한이 세션의 expires_at입니다.
• late는 입금 트랜잭션의 블록 시간을 expires_at과 비교해 정해집니다. 기한 안에 보낸 송금은 블록 확정이 기한 뒤에 끝나도 "late": false이며, checkout.session.settled에도 paid와 같은 값이 담깁니다.
• 입금 주소가 발급된 세션은 이미 전송 중인 송금이 확정될 수 있도록 expires_at 후 90분 동안 열려 있습니다. 주소가 발급된 세션의 과소 입금 환불과 checkout.session.expired는 이 90분이 끝날 때 처리됩니다.
• 기한 뒤에 도착한 전액 결제는 늦은 결제로 인정됩니다(기본값, 최대 7일). "late": true가 담긴 checkout.session.paid를 받고 자금은 정상적으로 정산됩니다. 주문을 처리할지, 콘솔에서 환불할지 판단하세요(아래 환불 참고).
• 늦은 결제를 받지 않으려면 세션을 "late_payments": "refund"로 만드세요. 그러면 기한(expires_at + 90분) 뒤에 도착한 전액 결제는 결제로 인정되지 않고, 입금 주소에 머물러 있다가 기한 약 7일 뒤 구매자의 환불 주소로 자동 환불됩니다(환불 kind late_deposit, checkout.refund.recorded). 즉시 환불은 불가능합니다 — BitPal은 비수탁 방식이고, 입금 컨트랙트상 판매자가 아닌 쪽은 그 7일이 지나야 자금을 되돌릴 수 있습니다. expires_at 전에 보냈고 확정만 늦게 끝난 송금은 여전히 결제로 인정됩니다.
• 이 규칙은 이전에 온체인 처리가 없었던 세션에만 적용됩니다. 잘못된 토큰을 이미 반환했거나 과소 입금을 이미 환불했다면, 만료된 세션은 완전히 닫힙니다. 이후 그 주소로 들어온 입금은 결제로 인정되지 않습니다(세션 id와 트랜잭션 해시를 함께 지원팀에 문의하세요).
• 늦은 결제 인정은 온체인 환불 창이 열리기(expires_at + 90분 + 7일) 1시간 전에 끝납니다. 그 이후 도착한 전액 결제는 인정되지 않으며, 환불 창이 열리면 자동으로 환불됩니다(환불 kind late_deposit).
• 기한 뒤에 들어온 일부 결제는 자동으로 환불됩니다(환불 kind late_deposit).
• 기한 후 7일이 지나서 보낸 자금은 자동으로 감시되지 않습니다. 세션 id와 트랜잭션 해시를 함께 지원팀에 문의하세요.

Refunds환불

BitPal is non-custodial. A payment goes from the buyer to a one-time deposit address and then straight to your payout wallet — BitPal never holds it and has no right to pull it back. So there is no refund API. There are two kinds of refund, and both fire checkout.refund.recorded:

BitPal은 비수탁(non-custodial) 방식입니다. 결제 대금은 구매자에게서 일회용 입금 주소를 거쳐 곧바로 판매자 정산 지갑으로 갑니다 — BitPal은 자금을 보관하지 않으며 되돌려 가져올 권한도 없습니다. 그래서 환불 API는 없습니다. 환불은 두 종류이며, 둘 다 checkout.refund.recorded를 발생시킵니다.

1. Automatic refunds (mismatched payments)1. 자동 환불 (주문과 맞지 않는 결제)

Payments that don't match the order are returned on-chain from the deposit address to the buyer's refund address — automatically, with no action from you.

주문과 맞지 않는 결제는 입금 주소에서 구매자의 환불 주소로 온체인 반환됩니다 — 판매자가 할 일 없이 자동으로 처리됩니다.

2. Refunding a completed payment (from the console)2. 완료된 결제 환불 (콘솔에서)

Like an app store, a completed payment is refunded by you, in the BitPal console:

앱스토어처럼, 완료된 결제는 판매자가 BitPal 콘솔에서 직접 환불합니다.

1. Open Console → Sessions → the session → Refund. It shows the network, token, the buyer's refund address (entered at payment time) and how much is still refundable (received minus refunds so far). Partial refunds are fine.
2. Send the refund from your own wallet — one click with a connected EVM wallet, or copy the address, amount and token contract (with a QR code) for Tron, Solana or any other wallet.
3. Record the transaction hash. BitPal checks it on-chain (confirmed, successful, the session's token sent to the refund address, after the payment, not more than what is left) and records it. You get checkout.refund.recorded with kind: "merchant", the reason_code you picked and from_address; GET /v1/checkout/sessions/{id}/refunds lists it.

1. 콘솔 → 세션 → 해당 세션 → 환불을 엽니다. 네트워크, 토큰, 구매자의 환불 주소(결제 시 입력), 환불 가능한 잔액(받은 금액에서 지금까지의 환불액을 뺀 값)이 표시됩니다. 부분 환불도 가능합니다.
2. 판매자 본인의 지갑에서 환불액을 보냅니다 — EVM 지갑을 연결했다면 클릭 한 번으로, Tron·Solana나 다른 지갑이라면 주소·금액·토큰 컨트랙트를 복사(QR 코드 제공)해서 보냅니다.
3. 트랜잭션 해시를 기록합니다. BitPal이 온체인에서 확인한 뒤(확정·성공 여부, 세션 토큰이 환불 주소로 전송되었는지, 결제 이후의 거래인지, 남은 금액을 넘지 않는지) 기록합니다. kind: "merchant", 선택한 reason_code, from_address가 담긴 checkout.refund.recorded를 받게 되며, GET /v1/checkout/sessions/{id}/refunds로 조회할 수 있습니다.

Current policy: you pay the network fee and the refund amount; the BitPal fee on the original payment is not returned. Recording is console-only — an API key gets 403 REFUND_CONSOLE_ONLY. Recording the same transaction again returns the existing record.

현재 정책: 네트워크 수수료(가스비)와 환불액은 판매자가 부담하며, 원래 결제의 BitPal 수수료는 돌려주지 않습니다. 환불 기록은 콘솔에서만 할 수 있습니다 — API 키로 요청하면 403 REFUND_CONSOLE_ONLY가 반환됩니다. 같은 트랜잭션을 다시 기록하면 기존 기록이 반환됩니다.

Treat kind as open: new values may be added. Handle unknown kinds as a generic refund.

kind에는 새 값이 추가될 수 있습니다. 알 수 없는 kind는 일반 환불로 처리하세요.

Webhooks웹훅

Signed JSON events as a session moves through its lifecycle. Delivered at least once — keep handlers idempotent.

세션이 생애주기를 거칠 때마다 서명된 JSON 이벤트를 보냅니다. 최소 한 번(at-least-once) 전달되므로 핸들러는 멱등하게 만드세요.

Events이벤트

Verify & handle검증 & 처리

Each request carries X-Webhook-Signature-256 (sha256=<hex>) and X-Webhook-Timestamp. Verify both, against the raw bytes.

모든 요청에는 X-Webhook-Signature-256(sha256=<hex>)과 X-Webhook-Timestamp가 담깁니다. 두 값 모두 원본(raw) 바이트를 기준으로 검증하세요.

import express from 'express';
import { verifyWebhookSignature, parseWebhookEvent, WEBHOOK_HEADERS } from '@bitpal/checkout';

app.post('/webhooks/bitpal', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8');            // exact bytes, not re-serialized JSON
  const ok = await verifyWebhookSignature(           // returns a Promise — always await it
    raw,
    req.header(WEBHOOK_HEADERS.signature) ?? '',
    process.env.BITPAL_WEBHOOK_SECRET,
    { timestamp: req.header(WEBHOOK_HEADERS.timestamp) ?? '' }, // replay defense — required
  );
  if (!ok) return res.status(400).send('invalid signature');
  const event = parseWebhookEvent(raw);
  if (event.event === 'checkout.session.paid') await fulfil(event.data.session_id); // idempotent, dedup on event.id
  res.sendStatus(200);
});

Request format요청 형식

Every delivery is an HTTP POST with a JSON body:

모든 전달은 JSON 본문을 담은 HTTP POST입니다.

{
  "id": "1ff63374-9417-4f87-850d-e869a3bd2dbe",   // event id — dedup on this
  "event": "checkout.session.paid",
  "created_at": "2026-11-06T07:20:49.549Z",       // when the event happened (unchanged on retries)
  "data": { "session_id": "cs_…", … }
}

Verifying the signature서명 검증

1. Read the raw request body as bytes, before any JSON parsing.
2. Reject the request if X-Webhook-Timestamp is more than 5 minutes from your clock (replay protection).
3. Compute HMAC-SHA256(key = your whsec_… secret, message = timestamp + "." + raw body) as lowercase hex.
4. Compare it with the part after sha256= using a constant-time comparison.

1. JSON을 파싱하기 전에 원본 요청 본문을 바이트로 읽습니다.
2. X-Webhook-Timestamp가 서버 시계와 5분 넘게 차이 나면 요청을 거부합니다(재전송 공격 방지).
3. HMAC-SHA256(key = your whsec_… secret, message = timestamp + "." + raw body)를 소문자 hex로 계산합니다.
4. sha256= 뒤의 값과 상수 시간(constant-time) 비교로 대조합니다.

Python

import hmac, hashlib, time
from datetime import datetime

def verify_bitpal_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str, tolerance_sec: int = 300) -> bool:
    if not signature.startswith("sha256=") or not timestamp:
        return False
    try:
        sent = datetime.fromisoformat(timestamp.replace("Z", "+00:00")).timestamp()
    except (ValueError, OverflowError, OSError):
        return False
    if abs(time.time() - sent) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    # compare bytes: compare_digest raises TypeError on non-ASCII str input
    return hmac.compare_digest(signature[len("sha256="):].encode(), expected.encode())

# Flask: verify_bitpal_webhook(request.get_data(), request.headers.get("X-Webhook-Signature-256", ""),
#                              request.headers.get("X-Webhook-Timestamp", ""), os.environ["BITPAL_WEBHOOK_SECRET"])

Go

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strings"
	"time"
)

func VerifyBitPalWebhook(rawBody []byte, signature, timestamp, secret string) bool {
	const prefix = "sha256="
	if !strings.HasPrefix(signature, prefix) || timestamp == "" {
		return false
	}
	sent, err := time.Parse(time.RFC3339Nano, timestamp)
	if err != nil {
		return false
	}
	if d := time.Since(sent); d > 5*time.Minute || d < -5*time.Minute {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(signature[len(prefix):]), []byte(expected))
}

PHP

function verify_bitpal_webhook(string $rawBody, string $signature, string $timestamp, string $secret, int $toleranceSec = 300): bool {
    if (strpos($signature, 'sha256=') !== 0 || $timestamp === '') return false;
    $sent = strtotime($timestamp);
    if ($sent === false || abs(time() - $sent) > $toleranceSec) return false;
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, substr($signature, 7));
}

$secret = getenv('BITPAL_WEBHOOK_SECRET');   // false when unset
if ($secret === false || $secret === '') {
    http_response_code(500);                  // misconfigured — never verify against an empty key
    exit;
}
$ok = verify_bitpal_webhook(
    (string) file_get_contents('php://input'),
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_256'] ?? '',
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '',
    $secret
);

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.DateTimeException;
import java.time.Duration;
import java.time.Instant;

public static boolean verifyBitPalWebhook(byte[] rawBody, String signature, String timestamp, String secret) throws Exception {
    if (signature == null || !signature.startsWith("sha256=") || timestamp == null || timestamp.isEmpty()) return false;
    Instant sent;
    try { sent = Instant.parse(timestamp); } catch (DateTimeException e) { return false; }
    if (Duration.between(sent, Instant.now()).abs().getSeconds() > 300) return false;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    mac.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
    byte[] digest = mac.doFinal(rawBody);
    StringBuilder hex = new StringBuilder();
    for (byte b : digest) hex.append(String.format("%02x", b));
    return MessageDigest.isEqual(hex.toString().getBytes(StandardCharsets.UTF_8),
                                 signature.substring(7).getBytes(StandardCharsets.UTF_8));
}

Event data이벤트 데이터

Every data object has session_id and metadata — the metadata you set when creating the session ({} if none), so you can map an event to your order without a lookup. BitPal's reserved keys (_bitpal, payer_email, allowed_pay_chains, allowed_assets) are left out. Session events also carry amount_total (6-decimal integer string), currency and late. Token amounts are in the pay token's decimals — see Payment lifecycle → Amounts.

모든 data 객체에는 session_id와 metadata가 있습니다. metadata는 세션을 만들 때 넣은 값이며(없으면 {}), 별도 조회 없이 이벤트를 주문과 연결할 수 있습니다. BitPal 예약 키(_bitpal, payer_email, allowed_pay_chains, allowed_assets)는 제외됩니다. 세션 이벤트에는 amount_total(소수점 6자리 정수 문자열), currency, late도 담깁니다. 토큰 금액은 결제 토큰의 decimals 기준입니다 — 결제 생애주기 → 금액을 참고하세요.

Example: checkout.session.paid예시: checkout.session.paid

{
  "id": "1ff63374-9417-4f87-850d-e869a3bd2dbe",
  "event": "checkout.session.paid",
  "created_at": "2026-11-06T07:20:49.549Z",
  "data": {
    "session_id": "cs_HFoj91aFFbHSRk1LN1-9K01q",
    "amount_total": "1000000",
    "currency": "USDC",
    "late": false,
    "tx_hash": "0xd9a75dfe753b20027a0a93841c4e70af1b6be061b59e530d1bc381e88c196fe3",
    "metadata": { "order_id": "ord_1042" }
  }
}

Example: checkout.session.unresolved (underpaid)예시: checkout.session.unresolved (과소 입금)

{
  "id": "18d80275-45be-43d7-a57b-4b5038bd2736",
  "event": "checkout.session.unresolved",
  "created_at": "2026-11-06T07:14:19.252Z",
  "data": {
    "session_id": "cs_1ATJ7V5QknzeFpTNPMU_449s",
    "amount_total": "5000000",
    "currency": "USDC",
    "late": false,
    "reason": "underpaid",
    "amount_expected": "5000000",
    "amount_received": "2500000",
    "received_token": "0x943b94Dacf1507F2658f1CfE103Ac36Ebc13Ef65",
    "tx_hash": "0x4461291b5d743d3950a474c015098b8cb53b4373346bd510f74481dd8dbb9d65",
    "metadata": { "order_id": "ord_1041" }
  }
}

Example: checkout.refund.recorded예시: checkout.refund.recorded

{
  "id": "f2fdcce6-1880-44b2-8351-906c42b7c4cd",
  "event": "checkout.refund.recorded",
  "created_at": "2026-11-06T07:20:29.547Z",
  "data": {
    "session_id": "cs_YsrZGcZzVsVHJo8ZNVmsTL1D",
    "kind": "overpay_excess",
    "amount": "1000000",
    "token": "0x943b94Dacf1507F2658f1CfE103Ac36Ebc13Ef65",
    "tx_hash": "0xe943412e2be8b3e3fc6359b47a8eea0cc4de17768b069f52ebab1aacd873aec4",
    "refund_address": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720",
    "metadata": { "order_id": "ord_1040" }
  }
}

Delivery, retries and ordering전달, 재시도, 순서

• Respond with any 2xx within 10 seconds. Do slow work after responding (queue it).
• A failed delivery (non-2xx, timeout or connection error) is retried right away twice (after 1 s and 2 s), then after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h — 10 attempts over about a day. After the last one the delivery moves to the dead-letter queue; resend it from Console → Developers → Webhooks once your endpoint is fixed (dead-lettered deliveries can be resent for 30 days).
• Delivery is at least once: the same event can arrive more than once. Deduplicate on the body id and store it in the same transaction as your side effect.
• Order is not guaranteed — a retried paid can arrive after settled. Keep the furthest state you have seen instead of overwriting it with an older one. Not every event is sent for every payment: paid can arrive with no deposit_detected before it (a late payment, or a deposit already confirmed when it was first seen).
• Test and live are separate: each environment has its own endpoints and secrets.

• 10초 안에 2xx로 응답하세요. 오래 걸리는 작업은 응답한 뒤에 처리하세요(큐 사용).
• 전달에 실패하면(2xx 외 응답, 타임아웃, 연결 오류) 바로 두 번(1초, 2초 후) 재시도하고, 이후 1분, 5분, 30분, 2시간, 6시간, 12시간, 24시간 뒤에 재시도합니다 — 약 하루 동안 총 10회입니다. 마지막 시도까지 실패하면 dead-letter queue로 옮겨지며, 엔드포인트를 고친 뒤 콘솔 → 개발자 → 웹훅에서 다시 보낼 수 있습니다(dead-letter 전달은 30일 동안 재전송 가능).
• 전달은 최소 한 번(at-least-once) 보장입니다. 같은 이벤트가 여러 번 올 수 있으니 본문의 id로 중복을 제거하고, 그 id를 부수 효과와 같은 트랜잭션에서 저장하세요.
• 순서는 보장되지 않습니다 — 재시도된 paid가 settled보다 늦게 올 수 있습니다. 더 오래된 상태로 덮어쓰지 말고, 지금까지 본 가장 앞선 상태를 유지하세요. 모든 결제에 모든 이벤트가 오는 것도 아닙니다. paid 전에 deposit_detected가 없을 수 있습니다(늦은 결제이거나, 처음 확인했을 때 이미 확정된 입금).
• 테스트와 라이브는 분리되어 있습니다. 환경마다 엔드포인트와 시크릿이 따로 있습니다.

Testing테스트

• Send Test (Console → Developers → Webhooks) posts a signed sample event to your endpoint. Its id starts with test_.
• In the Sandbox event list (and the MCP list_test_events tool) every event is a test-mode event. The is_test field does not mean test mode: it is true only for Send Test samples and false for events produced by a (simulated) payment.
• For local development, expose your server with a tunnel (ngrok, cloudflared) and register the tunnel URL in test mode.
• Run a real test payment (Quickstart) to receive the full sequence of events.

• 테스트 전송(콘솔 → 개발자 → 웹훅)은 서명된 샘플 이벤트를 엔드포인트로 보냅니다. 이 이벤트의 id는 test_로 시작합니다.
• 샌드박스 이벤트 목록(과 MCP list_test_events 도구)에 보이는 이벤트는 모두 테스트 모드 이벤트입니다. is_test 필드는 테스트 모드를 뜻하지 않습니다. 테스트 전송 샘플일 때만 true이고, (시뮬레이션) 결제로 발생한 이벤트는 false입니다.
• 로컬 개발 중에는 터널(ngrok, cloudflared)로 서버를 노출하고, 그 터널 URL을 테스트 모드에 등록하세요.
• 실제 테스트 결제(빠른 시작)를 진행하면 전체 이벤트 흐름을 받아 볼 수 있습니다.

Errors에러

How the API reports failures, and what to do about the ones you are likely to see.

API가 실패를 어떻게 알려 주는지, 그리고 자주 마주칠 에러에 어떻게 대응하는지 설명합니다.

Response format응답 형식

Successful responses are { "data": … }. Failed responses use an HTTP status code and this JSON body:

성공 응답은 { "data": … } 형식입니다. 실패 응답은 HTTP 상태 코드와 함께 다음 JSON 본문을 반환합니다.

{
  "error": "checkout not enabled for USDC on eip155:8453",   // human-readable
  "code": "FEATURE_NOT_ENABLED",                                // machine-readable
  "retryable": false,
  "trace_id": "4f1c…"                                           // quote it to support
}

error is a human-readable message and may change — branch on code (after the HTTP status), never on the text of error. Validation failures add a details array. The SDK exposes the same fields:

error는 사람이 읽기 위한 메시지이며 바뀔 수 있습니다 — error 문구가 아니라 (HTTP 상태 다음으로) code로 분기하세요. 유효성 검사 실패에는 details 배열이 추가됩니다. SDK도 같은 필드를 제공합니다.

import { BitPalError } from '@bitpal/checkout';

try {
  await bitpal.checkout.createSession(params);
} catch (err) {
  if (err instanceof BitPalError) {
    err.statusCode;   // 400, 404, 429, …
    err.code;         // 'CHECKOUT_AMOUNT_TOO_LOW' (when the API sent one)
    err.apiMessage;   // the API's description
    err.retryable;    // true / false / undefined
    err.traceId;      // for support
  }
  throw err;
}

HTTP status codesHTTP 상태 코드

Common error codes자주 보는 에러 코드

Retrying safely안전하게 재시도하기

• Send an Idempotency-Key (8–128 characters, unique per operation — an order id works) on any merchant POST (sessions, products, prices, payment links, webhook endpoints, …) — it is honoured on all of them. Replays within 24 hours return the original response with X-Idempotency-Replayed: true. A key is bound to one request: reusing it with a different body or on a different endpoint returns 422 IDEMPOTENCY_KEY_REUSED. Failed requests (4xx/5xx) are not cached, so you can retry them with the same key.
• Retry only 429, 5xx and network errors, with exponential backoff.
• Rate-limited responses carry Retry-After and X-RateLimit-Limit / -Remaining / -Reset.

• 가맹점 POST 요청(세션, 상품, 가격, 결제 링크, 웹훅 엔드포인트 등)에는 Idempotency-Key(8–128자, 작업마다 고유 — 주문 id면 충분합니다)를 보내세요. 모든 POST에서 지원됩니다. 24시간 안의 재요청은 원래 응답을 X-Idempotency-Replayed: true와 함께 반환합니다. 키는 요청 하나에 묶입니다. 다른 본문이나 다른 엔드포인트에 재사용하면 422 IDEMPOTENCY_KEY_REUSED가 반환됩니다. 실패한 요청(4xx/5xx)은 캐시되지 않으므로 같은 키로 재시도할 수 있습니다.
• 429, 5xx, 네트워크 오류만 지수 백오프로 재시도하세요.
• 요청 한도에 걸린 응답에는 Retry-After와 X-RateLimit-Limit / -Remaining / -Reset 헤더가 담깁니다.

Use with AIAI와 함께 쓰기

Give your AI coding tool BitPal's docs, API spec and webhook schemas so it writes integrations against the real API — and, with a test key, runs a test payment for you.

AI 코딩 도구에 BitPal 문서, API 스펙, 웹훅 스키마를 제공해 실제 API에 맞는 연동 코드를 작성하게 하세요. 테스트 키를 주면 테스트 결제까지 대신 실행합니다.

BitPal MCP serverBitPal MCP 서버

• Remote: https://mcp.bitpal.io/mcp (Streamable HTTP). Nothing to install.
• Local: npx -y @bitpal/mcp (stdio).
• Docs tools work without a key. Add a bp_test_… key to unlock test-mode tools. Live keys are rejected. The server checks the key with BitPal: a revoked or unknown key keeps the test-mode tools hidden and says why in the server instructions.

• 원격: https://mcp.bitpal.io/mcp (Streamable HTTP). 설치할 것이 없습니다.
• 로컬: npx -y @bitpal/mcp (stdio).
• 문서 도구는 키 없이 동작합니다. bp_test_… 키를 추가하면 테스트 모드 도구가 열립니다. 라이브 키는 거부됩니다. 서버는 BitPal에 키를 확인하며, 폐기되었거나 알 수 없는 키라면 테스트 모드 도구를 숨긴 채 그 이유를 서버 instructions에 알려 줍니다.

Setup설정

Replace bp_test_… with your test key (Console → Developers → API Keys), or leave the key out for docs only.

bp_test_…를 본인의 테스트 키(콘솔 → 개발자 → API 키)로 바꾸세요. 문서만 쓸 거라면 키를 빼도 됩니다.

Claude Code

# remote
claude mcp add --transport http bitpal https://mcp.bitpal.io/mcp --header "Authorization: Bearer bp_test_…"
# local
claude mcp add bitpal -e BITPAL_API_KEY=bp_test_… -- npx -y @bitpal/mcp

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "bitpal": { "url": "https://mcp.bitpal.io/mcp", "headers": { "Authorization": "Bearer bp_test_…" } }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "bitpal": { "type": "http", "url": "https://mcp.bitpal.io/mcp", "headers": { "Authorization": "Bearer bp_test_…" } }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "bitpal": { "serverUrl": "https://mcp.bitpal.io/mcp", "headers": { "Authorization": "Bearer bp_test_…" } }
  }
}

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "bitpal": { "command": "npx", "args": ["-y", "@bitpal/mcp"], "env": { "BITPAL_API_KEY": "bp_test_…" } }
  }
}

Codex CLI — ~/.codex/config.toml

[mcp_servers.bitpal]
command = "npx"
args = ["-y", "@bitpal/mcp"]
env = { BITPAL_API_KEY = "bp_test_…" }

Without MCPMCP 없이 쓰기

• llms.txt — an index of every page plus the rules below.
• llms-full.txt — all docs in one file.
• Every page has Copy as Markdown and a .md version (/docs/md/<page>.md).
• openapi.json — the OpenAPI 3.1 spec, generated from the API code.

• llms.txt — 모든 페이지의 색인과 아래 규칙.
• llms-full.txt — 전체 문서를 파일 하나로.
• 모든 페이지에 Copy as Markdown 버튼과 .md 버전(/docs/md/<page>.md)이 있습니다.
• openapi.json — API 코드에서 생성한 OpenAPI 3.1 스펙.

Rules for your AGENTS.mdAGENTS.md에 넣을 규칙

Paste this into AGENTS.md, CLAUDE.md or your editor's rules file so every session follows it.

아래 내용을 AGENTS.md, CLAUDE.md 또는 에디터의 규칙 파일에 붙여 넣으면 모든 세션이 이 규칙을 따릅니다. (AI 도구용 규칙이라 영어로 제공합니다.)

## BitPal integration rules
- Keep bp_test_/bp_live_ API keys and the whsec_ webhook secret on the server. Browsers only get checkout_url.
- Fulfil orders from the checkout.session.paid webhook (signature verified) or a server-side session lookup —
  never from the success_url redirect or a popup message.
- Verify webhooks on the raw body with X-Webhook-Signature-256 + X-Webhook-Timestamp; await verifyWebhookSignature.
- Webhooks are at-least-once and unordered: dedupe on the body id, keep the furthest session state.
- Amounts are strings: amount = plain number in the line-item currency ("29"); amount_total = 6-decimal integer;
  deposit amounts use the token's decimals. No floating-point math.
- Paid statuses are paid_confirmed and swept (there is no "paid"/"settled" status value).
- Payment window: expires_in_minutes (1–60). Full payments up to 7 days late arrive with late: true — handle them.
- Test keys take testnet chain ids only; live keys mainnet only.
- Headless UIs call BitPal through your backend (CORS); only the public session endpoint works from the browser.
- Send Idempotency-Key when creating sessions.
- Session total must be at least 1.00 in the session currency (CHECKOUT_AMOUNT_TOO_LOW); Tron needs $300.
- Webhook data carries your session metadata — put your order id there.
- Docs: https://bitpal.io/docs/ · MCP: https://mcp.bitpal.io/mcp

Chains & contracts체인 & 컨트랙트

Chains & identifiers체인 & 식별자

The pay_chain / allowed_pay_chains values are CAIP-2 identifiers. Use the value from the column matching your API key's mode.

pay_chain / allowed_pay_chains 값은 CAIP-2 식별자입니다. API 키 모드에 맞는 열의 값을 사용하세요.

Contract addresses컨트랙트 주소

The deposit-address contracts (EVM/Tron deterministic forwarder factory, Solana program). Published here as each network goes live.

입금 주소용 컨트랙트입니다(EVM/Tron은 결정적 forwarder factory, Solana는 프로그램). 각 네트워크가 라이브되는 대로 여기에 게시합니다.

These are the factories that derive deposit addresses. Always treat the deposit address returned by BitPal as authoritative for a given order — funds are cryptographically committed to your destination.

위 컨트랙트는 입금 주소를 파생하는 factory입니다. 개별 주문에서는 항상 BitPal이 반환한 입금 주소를 기준으로 삼으세요 — 자금은 암호학적으로 판매자의 정산 목적지에 고정되어 있습니다.

Refunds & edge cases환불 & 예외

Payments are push transfers, so a buyer can pay the wrong amount or token. BitPal resolves each case automatically to the buyer's refund address (set at pay time, committed & immutable).

결제는 구매자가 직접 보내는 push 송금이라 금액이나 토큰이 틀릴 수 있습니다. BitPal은 각 경우를 구매자의 환불 주소(결제 시 지정되며 고정·변경 불가)로 자동 처리합니다.

Test mode & faucet테스트 모드 & faucet

• Keys are environment-scoped: bp_test_… on testnets, bp_live_… on mainnet.
• In test mode the hosted page shows a faucet — the buyer mints mock tokens to run a real end-to-end payment. (Gas is separate; the faucet sends tokens only.)

• 키는 환경별로 구분됩니다: bp_test_…는 테스트넷, bp_live_…는 메인넷에서 동작합니다.
• 테스트 모드의 호스티드 결제 페이지에는 faucet이 표시됩니다 — 구매자가 mock 토큰을 받아 실제 end-to-end 결제를 해볼 수 있습니다. (가스는 별도이며, faucet은 토큰만 보내 줍니다.)

엔드포인트별 설명은 API 코드의 OpenAPI 스펙에서 생성되어 영어로 제공됩니다. 필드·파라미터 이름과 예시는 그대로 사용하면 됩니다.

API referenceAPI 레퍼런스

Every public endpoint, generated from the OpenAPI 3.1.0 spec (version 1.0.0). Download it: openapi.json.

모든 공개 엔드포인트를 OpenAPI 3.1.0 스펙(버전 1.0.0)에서 생성했습니다. 스펙 다운로드: openapi.json.

Basics기본 사항

Checkout sessions

Create a session per order, send the buyer to the hosted page (or build your own UI), and track it.

POST /v1/checkout/sessions — Create a checkout session

Creates a session for one order and returns the hosted checkout_url. Line items take either amount (plain decimal string, e.g. "29") or amount_atomic (6-decimal integer string), or reference a price_id. **Minimum amount:** the session total (sum of amount × quantity) must be at least 1.00 in the session currency (USDC/USDT: $1, JPYC: ¥1); a lower total returns 400 CHECKOUT_AMOUNT_TOO_LOW. Some networks also have a higher per-network minimum (Tron: currently $300, testnet included; JPYC: ¥100) — a network whose minimum is above the total is not offered to the buyer, and requesting a deposit address on it returns 400 CHECKOUT_BELOW_MIN_PAYMENT. **Payout wallet:** you need a payout wallet registered in the session's mode (test/live). With pay_chain, a wallet for that network's type (EVM, Tron or Solana) is required. With allowed_pay_chains / allowed_assets, at least one listed network must have a wallet of its type, and the buyer is only offered networks you can receive on. Without any network restriction, any payout wallet is enough: with an EVM wallet the buyer is offered Base USDC as before; without one, the networks of the wallet types you registered (if the total is below the minimum of all of them, 400 CHECKOUT_BELOW_MIN_PAYMENT). No usable payout wallet returns 400 SELLER_WALLET_NOT_CONFIGURED.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (CreateCheckoutSessionRequest)

{
  "line_items": [
    {
      "name": "Pro plan",
      "amount": "29",
      "currency": "USDC"
    }
  ],
  "pay_chain": "eip155:84532",
  "expires_in_minutes": 30,
  "success_url": "https://your.store/thanks?session={CHECKOUT_SESSION_ID}"
}

Response응답 201 — Session created.

{
  "data": {
    "id": "cs_Q2FxKhomCEju_OqvKfrQsTOh",
    "checkout_url": "https://bitpal.io/pay/cs_Q2FxKhomCEju_OqvKfrQsTOh?token=<session_token>",
    "session_token": "<session_token>",
    "status": "created",
    "amount_total": "29000000",
    "currency": "USDC",
    "expires_at": "2026-11-06T07:58:28.776Z",
    "tax": {
      "tax_amount": "0",
      "total_with_tax": "29000000"
    }
  },
  "meta": {
    "mode": "TEST",
    "requestId": "ec091faf-…"
  }
}

Errors:에러: 400 · 401 · 403 · 409 · 422 · 429 — see Errors.에러 참고.

GET /v1/checkout/sessions — List checkout sessions

Newest first, in the API key’s mode (test/live).

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Sessions.

{
  "data": [
    {
      "id": "string",
      "status": "string",
      "mode": "TEST",
      "amount_total": "1000000",
      "amount_received": "string",
      "currency": "string",
      "pay_chain": "string",
      "pay_asset": "string",
      "token_decimals": 0,
      "payment_method": "string",
      "payer_wallet": "string",
      "seller_wallet": "string",
      "tolerance_percent": "string",
      "late_payments": "accept",
      "deposit_address": "string",
      "refund_address": "string",
      "received_token": "string",
      "received_token_symbol": "string",
      "fee_amount": "string",
      "fee_rate": "string",
      "net_amount": "string",
      "fee_amount_token": "string",
      "net_amount_token": "string",
      "tx_hash": "string",
      "deposit_tx_hash": "string",
      "sweep_tx_hash": "string",
      "success_url": "string",
      "cancel_url": "string",
      "metadata": {},
      "payment_source": "string",
      "payment_link_id": "string",
      "expires_at": "2026-11-06T07:00:00.000Z",
      "paid_at": "2026-11-06T07:00:00.000Z",
      "settled_at": "2026-11-06T07:00:00.000Z",
      "created_at": "2026-11-06T07:00:00.000Z",
      "raw_status": "string"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 — see Errors.에러 참고.

GET /v1/checkout/sessions/{id} — Retrieve a checkout session

Server-side source of truth for an order, together with webhooks.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — The session.

{
  "data": {
    "id": "string",
    "status": "string",
    "mode": "TEST",
    "amount_total": "1000000",
    "amount_received": "string",
    "currency": "string",
    "pay_chain": "string",
    "pay_asset": "string",
    "token_decimals": 0,
    "payment_method": "string",
    "payer_wallet": "string",
    "seller_wallet": "string",
    "tolerance_percent": "string",
    "late_payments": "accept",
    "deposit_address": "string",
    "refund_address": "string",
    "received_token": "string",
    "received_token_symbol": "string",
    "fee_amount": "string",
    "fee_rate": "string",
    "net_amount": "string",
    "fee_amount_token": "string",
    "net_amount_token": "string",
    "tx_hash": "string",
    "deposit_tx_hash": "string",
    "sweep_tx_hash": "string",
    "success_url": "string",
    "cancel_url": "string",
    "metadata": {},
    "payment_source": "string",
    "payment_link_id": "string",
    "expires_at": "2026-11-06T07:00:00.000Z",
    "paid_at": "2026-11-06T07:00:00.000Z",
    "settled_at": "2026-11-06T07:00:00.000Z",
    "created_at": "2026-11-06T07:00:00.000Z",
    "line_items": [
      {
        "id": "string",
        "name": "string",
        "amount": "1000000",
        "currency": "string",
        "quantity": 0,
        "price_id": "string",
        "product_id": "string",
        "created_at": "2026-11-06T07:00:00.000Z"
      }
    ]
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 · 404 — see Errors.에러 참고.

GET /v1/checkout/sessions/{id}/status — Get session status

Lightweight status for polling from your server. Requires your API key (N13 — it is not a public endpoint). Buyer-facing pages should use GET /v1/checkout/sessions/{id}/public.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Status.

{
  "data": {
    "status": "awaiting_deposit",
    "paid_at": null
  }
}

Errors:에러: 404 — see Errors.에러 참고.

GET /v1/checkout/sessions/{id}/public — Get the public session view

Buyer-facing view used by the checkout page: payment options, deposit address once issued, refunds. No authentication; CORS-open.

Auth:인증: None — public endpoint없음 — 공개 엔드포인트

Parameters파라미터

Response응답 200 — Public view.

{
  "data": {
    "id": "string",
    "status": "string",
    "token_decimals": 0,
    "pay_amount": "string",
    "mode": "TEST",
    "chain_id": 0,
    "token_address": "string",
    "payment_options": [
      {
        "caip2": "string",
        "chain_id": 0,
        "token_symbol": "string",
        "token_address": "string",
        "decimals": 0,
        "amount_atomic": "string",
        "available": true,
        "unavailable_reason": "coming_soon"
      }
    ],
    "currency": "string",
    "amount_total": "1000000",
    "amount_received": "string",
    "chain": "string",
    "tx_hash": "string",
    "release_tx_hash": "string",
    "expires_at": "2026-11-06T07:00:00.000Z",
    "success_url": "string",
    "cancel_url": "string",
    "fee_amount": "string",
    "fee_rate": "string",
    "net_amount": "string",
    "tax_amount": null,
    "tax_rate": null,
    "pay_chain": "string",
    "pay_asset": "string",
    "deposit_address": "string",
    "deposit_owner": "string",
    "payment_deadline_at": "2026-11-06T07:00:00.000Z",
    "payment_method": "string",
    "payer_wallet": "string",
    "seller_wallet": "string",
    "tolerance_percent": "string",
    "paid_at": "2026-11-06T07:00:00.000Z",
    "settled_at": "2026-11-06T07:00:00.000Z",
    "created_at": "2026-11-06T07:00:00.000Z",
    "line_items": [
      {
        "name": "string",
        "amount": "1000000",
        "currency": "string",
        "quantity": 0
      }
    ],
    "payment_source": "string",
    "refunds": [
      {
        "kind": "string",
        "amount": "string",
        "token_symbol": "string",
        "decimals": 0,
        "tx_hash": "string",
        "caip2": "string"
      }
    ]
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 404 — see Errors.에러 참고.

POST /v1/checkout/sessions/{id}/deposit-address — Issue the deposit address

Fixes the buyer’s network, token and refund address, and returns the one-time deposit address with the exact amount. Calling again returns the same address and keeps the first refund address. Requires the session token (header X-Session-Token or body session_token).

Auth:인증: Session token — X-Session-Token header or session_token body field (no API key)세션 토큰 — X-Session-Token 헤더 또는 session_token 본문 필드 (API 키 없음)

Parameters파라미터

Request body요청 본문 (IssueDepositAddressRequest)

{
  "session_token": "<session_token>",
  "refundAddress": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720",
  "chain": "eip155:84532",
  "token": "USDC"
}

Response응답 200 — Deposit address.

{
  "data": {
    "sessionId": "cs_…",
    "chain": "eip155:84532",
    "depositAddress": "0x6b19e871c934aB52775B6712e110f3e4b0626347",
    "expectedToken": "0x943b94dacf1507f2658f1cfe103ac36ebc13ef65",
    "expectedAmount": "29000000",
    "feeAmount": "435000",
    "refundAddress": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720",
    "deadline": "1793951938",
    "expiresAt": "2026-11-06T07:58:28.776Z",
    "depositOwner": null
  }
}

Errors:에러: 400 · 401 · 404 · 409 · 410 — see Errors.에러 참고.

GET /v1/checkout/sessions/{id}/refunds — List refunds for a session

Refunds recorded for this session: automatic on-chain refunds from the deposit address (overpayment, expired underpayment, wrong token, late deposit) and refunds you sent from your own wallet and recorded in the console (kind: merchant). There is no API to make a refund — BitPal is non-custodial; refund a completed payment from Console → Sessions → session → Refund.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Refunds.

{
  "data": [
    {
      "id": "string",
      "kind": "string",
      "token": "string",
      "token_symbol": "string",
      "amount": "string",
      "amount_display": "string",
      "decimals": 0,
      "refund_address": "string",
      "tx_hash": "string",
      "caip2": "string",
      "block_number": "string",
      "created_at": "2026-11-06T07:00:00.000Z",
      "from_address": "string",
      "reason_code": "string",
      "note": "string",
      "explorer_url": "string"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 · 404 — see Errors.에러 참고.

GET /v1/checkout/fee-preview — Preview the fee for an amount

Pass exactly one of amount or amount_atomic. The response is always atomic.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Fee breakdown.

{
  "data": {
    "amount": "100000000",
    "fee_rate": "0.015",
    "fee_amount": "1500000",
    "net_amount": "98500000"
  }
}

Errors:에러: 400 · 401 — see Errors.에러 참고.

Products & prices

Catalog objects. Prices are immutable.

POST /v1/checkout/products — Create a product

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (CreateProductRequest)

{
  "name": "Pro plan"
}

Response응답 201 — Product created.

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "image_url": "string",
    "status": "active",
    "metadata": {},
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 — see Errors.에러 참고.

GET /v1/checkout/products — List products

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Products.

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "image_url": "string",
      "status": "active",
      "metadata": {},
      "mode": "TEST",
      "created_at": "2026-11-06T07:00:00.000Z",
      "updated_at": "2026-11-06T07:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 — see Errors.에러 참고.

GET /v1/checkout/products/{id} — Retrieve a product

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — The product.

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "image_url": "string",
    "status": "active",
    "metadata": {},
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 404 — see Errors.에러 참고.

PATCH /v1/checkout/products/{id} — Update a product

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (UpdateProductRequest)

Response응답 200 — The updated product.

{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "image_url": "string",
    "status": "active",
    "metadata": {},
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 404 — see Errors.에러 참고.

POST /v1/checkout/products/{id}/prices — Create a price

Prices are immutable: to change an amount, create a new price. Pass exactly one of amount (decimal string) or amount_atomic (6-decimal integer string). The currency is derived from token_symbol.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (CreatePriceRequest)

{
  "amount": "29",
  "token_symbol": "USDC"
}

Response응답 201 — Price created.

{
  "data": {
    "id": "string",
    "product_id": "string",
    "amount_atomic": "1000000",
    "currency": "string",
    "token_symbol": "string",
    "billing_type": "one_time",
    "nickname": "string",
    "lookup_key": "string",
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 404 — see Errors.에러 참고.

GET /v1/checkout/products/{id}/prices — List a product’s prices

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Prices.

{
  "data": [
    {
      "id": "string",
      "product_id": "string",
      "amount_atomic": "1000000",
      "currency": "string",
      "token_symbol": "string",
      "billing_type": "one_time",
      "nickname": "string",
      "lookup_key": "string",
      "mode": "TEST",
      "created_at": "2026-11-06T07:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 404 — see Errors.에러 참고.

GET /v1/checkout/prices/{id} — Retrieve a price

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — The price.

{
  "data": {
    "id": "string",
    "product_id": "string",
    "amount_atomic": "1000000",
    "currency": "string",
    "token_symbol": "string",
    "billing_type": "one_time",
    "nickname": "string",
    "lookup_key": "string",
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 · 404 — see Errors.에러 참고.

PATCH /v1/checkout/prices/{id} — Update a price’s nickname

Only nickname can change. Sending an amount/currency field returns PRICE_IMMUTABLE_FIELD.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (UpdatePriceRequest)

Response응답 200 — The updated price.

{
  "data": {
    "id": "string",
    "product_id": "string",
    "amount_atomic": "1000000",
    "currency": "string",
    "token_symbol": "string",
    "billing_type": "one_time",
    "nickname": "string",
    "lookup_key": "string",
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 404 — see Errors.에러 참고.

Payment links

Shareable hosted URLs for a price.

POST /v1/checkout/payment-links — Create a payment link

A shareable hosted URL for one price. The link ↔ price binding is fixed after creation.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (CreatePaymentLinkRequest)

{
  "price_id": "price_…",
  "allowed_pay_chains": [
    "eip155:8453"
  ]
}

Response응답 201 — Link created.

{
  "data": {
    "id": "string",
    "share_token": "string",
    "price_id": "string",
    "title": "string",
    "description": "string",
    "collect_email": true,
    "email_required": true,
    "allowed_pay_chains": [
      "string"
    ],
    "allowed_assets": [
      {
        "caip2": "string",
        "token": "string"
      }
    ],
    "success_url": "string",
    "cancel_url": "string",
    "status": "active",
    "max_uses": 0,
    "paid_use_count": 0,
    "expires_at": "2026-11-06T07:00:00.000Z",
    "metadata": {},
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 404 — see Errors.에러 참고.

GET /v1/checkout/payment-links — List payment links

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Links.

{
  "data": [
    {
      "id": "string",
      "share_token": "string",
      "price_id": "string",
      "title": "string",
      "description": "string",
      "collect_email": true,
      "email_required": true,
      "allowed_pay_chains": [
        "string"
      ],
      "allowed_assets": [
        {
          "caip2": "string",
          "token": "string"
        }
      ],
      "success_url": "string",
      "cancel_url": "string",
      "status": "active",
      "max_uses": 0,
      "paid_use_count": 0,
      "expires_at": "2026-11-06T07:00:00.000Z",
      "metadata": {},
      "mode": "TEST",
      "created_at": "2026-11-06T07:00:00.000Z",
      "updated_at": "2026-11-06T07:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 — see Errors.에러 참고.

GET /v1/checkout/payment-links/{id} — Retrieve a payment link

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — The link, with product/price summary fields.

{
  "data": {
    "id": "string",
    "share_token": "string",
    "price_id": "string",
    "title": "string",
    "description": "string",
    "collect_email": true,
    "email_required": true,
    "allowed_pay_chains": [
      "string"
    ],
    "allowed_assets": [
      {
        "caip2": "string",
        "token": "string"
      }
    ],
    "success_url": "string",
    "cancel_url": "string",
    "status": "active",
    "max_uses": 0,
    "paid_use_count": 0,
    "expires_at": "2026-11-06T07:00:00.000Z",
    "metadata": {},
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 · 404 — see Errors.에러 참고.

PATCH /v1/checkout/payment-links/{id} — Update a payment link

Operational settings and active ↔ inactive. The price cannot change — create a new link instead. Deactivating (status: "inactive") requires reason_code (user_request, security_concern, rotation, no_longer_needed or other, plus an optional reason_note); without it the request returns 400 REASON_CODE_REQUIRED. Reactivating accepts the same fields optionally. Every status change is recorded in your audit log with its reason.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (UpdatePaymentLinkRequest)

Response응답 200 — The updated link.

{
  "data": {
    "id": "string",
    "share_token": "string",
    "price_id": "string",
    "title": "string",
    "description": "string",
    "collect_email": true,
    "email_required": true,
    "allowed_pay_chains": [
      "string"
    ],
    "allowed_assets": [
      {
        "caip2": "string",
        "token": "string"
      }
    ],
    "success_url": "string",
    "cancel_url": "string",
    "status": "active",
    "max_uses": 0,
    "paid_use_count": 0,
    "expires_at": "2026-11-06T07:00:00.000Z",
    "metadata": {},
    "mode": "TEST",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 404 · 409 — see Errors.에러 참고.

x402

Charge per API call with HTTP 402 and EIP-3009 authorizations.

GET /v1/x402/assets — List x402 assets for this mode

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Response응답 200 — Assets.

{
  "data": {
    "mode": "TEST",
    "assets": [
      {
        "caip2": "string",
        "network": "string",
        "chain_name": "string",
        "symbol": "string",
        "decimals": 0,
        "address": "string"
      }
    ]
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 — see Errors.에러 참고.

POST /v1/x402/requirements — Build the 402 payment requirements

Returns the body your resource server sends with 402 Payment Required, including the fee split. Pass exactly one of amount or amountAtomic.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (X402RequirementsRequest)

{
  "payTo": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "amount": "0.1",
  "resource": "https://api.example.com/report"
}

Response응답 200 — 402 body.

{
  "data": {
    "x402Version": 1,
    "accepts": [
      {
        "scheme": "exact",
        "network": "string",
        "asset": "string",
        "payTo": "string",
        "maxAmountRequired": "1000000",
        "resource": "string",
        "description": "string",
        "mimeType": "string",
        "maxTimeoutSeconds": 0,
        "extra": {
          "name": "string",
          "version": "string",
          "chainId": 0
        },
        "feeBreakdown": {
          "netAmount": "1000000",
          "feeAmount": "1000000",
          "feeBps": 0,
          "feeRecipient": "string"
        }
      }
    ]
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 — see Errors.에러 참고.

POST /v1/x402/verify — Verify an X-PAYMENT header

Checks the EIP-3009 authorization against the requirements. Sends nothing on-chain.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (X402PaymentRequest)

Response응답 200 — Valid.

{
  "data": {
    "valid": true,
    "payment_id": "string",
    "status": "string",
    "idempotent": true
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 409 — see Errors.에러 참고.

POST /v1/x402/settle — Settle an x402 payment

Broadcasts the transfer and waits for the receipt. Serve the resource only when status is confirmed. Settlement is idempotent per authorization — retry with the same body on 5xx.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (X402PaymentRequest)

Response응답 200 — Settlement result.

{
  "data": {
    "success": true,
    "payment_id": "string",
    "status": "string",
    "tx_hash": "string",
    "fee_tx_hash": "string",
    "network": "string",
    "idempotent": true
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 403 · 409 · 503 — see Errors.에러 참고.

GET /v1/x402/payments/{id} — Retrieve an x402 payment

Recovery path when a settle response was lost — check here before settling again.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — The payment.

{
  "data": {
    "id": "string",
    "status": "pending",
    "raw_status": "string",
    "resource": "string",
    "chain": "string",
    "asset": "string",
    "decimals": 0,
    "amount": "1000000",
    "gross_amount": "1000000",
    "payer": "string",
    "pay_to": "string",
    "tx_hash": "string",
    "created_at": "2026-11-06T07:00:00.000Z",
    "settled_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 · 404 — see Errors.에러 참고.

GET /v1/x402/payments — List x402 payments

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Response응답 200 — Payments.

{
  "data": [
    {
      "id": "string",
      "status": "pending",
      "raw_status": "string",
      "resource": "string",
      "chain": "string",
      "asset": "string",
      "decimals": 0,
      "amount": "1000000",
      "gross_amount": "1000000",
      "payer": "string",
      "pay_to": "string",
      "tx_hash": "string",
      "created_at": "2026-11-06T07:00:00.000Z",
      "settled_at": "2026-11-06T07:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 — see Errors.에러 참고.

Webhook endpoints

Manage where BitPal delivers signed events.

POST /v1/webhooks — Create a webhook endpoint

**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403. The response carries the whsec_… signing secret — it is shown only once.

Auth:인증: Console login only — manage this in Console → Developers → Webhooks (API keys get 403)콘솔 로그인 전용 — 콘솔 → 개발자 → 웹훅에서 관리 (API 키는 403)

Parameters파라미터

Request body요청 본문 (CreateWebhookEndpointRequest)

{
  "endpoint_url": "https://your.store/webhooks/bitpal",
  "subscribed_events": [
    "checkout.session.paid"
  ]
}

Response응답 201 — Endpoint created.

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "mode": "TEST",
    "endpoint_url": "string",
    "subscribed_events": [
      "string"
    ],
    "retry_policy": {
      "max_retries": 0,
      "backoff": "exponential"
    },
    "dead_letter_destination": "string",
    "status": "active",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z",
    "secret": "string"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 — see Errors.에러 참고.

GET /v1/webhooks — List webhook endpoints

**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403. Endpoints of the API key’s environment and mode. Note: list items use camelCase keys.

Auth:인증: Console login only — manage this in Console → Developers → Webhooks (API keys get 403)콘솔 로그인 전용 — 콘솔 → 개발자 → 웹훅에서 관리 (API 키는 403)

Parameters파라미터

Response응답 200 — Endpoints, newest first. meta carries total/limit/offset.

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "mode": "TEST",
      "endpoint_url": "string",
      "subscribed_events": [
        "string"
      ],
      "retry_policy": {
        "max_retries": 0,
        "backoff": "exponential"
      },
      "dead_letter_destination": "string",
      "status": "active",
      "created_at": "2026-11-06T07:00:00.000Z",
      "updated_at": "2026-11-06T07:00:00.000Z"
    }
  ],
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 401 — see Errors.에러 참고.

PATCH /v1/webhooks/{id} — Update a webhook endpoint

**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403. Setting status to disabled removes the endpoint and requires reason_code (otherwise 400 REASON_CODE_REQUIRED). It is recorded in the audit log.

Auth:인증: Console login only — manage this in Console → Developers → Webhooks (API keys get 403)콘솔 로그인 전용 — 콘솔 → 개발자 → 웹훅에서 관리 (API 키는 403)

Parameters파라미터

Request body요청 본문 (UpdateWebhookEndpointRequest)

Response응답 200 — The updated endpoint.

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "mode": "TEST",
    "endpoint_url": "string",
    "subscribed_events": [
      "string"
    ],
    "retry_policy": {
      "max_retries": 0,
      "backoff": "exponential"
    },
    "dead_letter_destination": "string",
    "status": "active",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 404 — see Errors.에러 참고.

POST /v1/webhooks/{id}/rotate-secret — Rotate the signing secret

**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403. Takes effect immediately. The new secret is returned once — update your verifier. Requires reason_code (400 REASON_CODE_REQUIRED if missing); recorded in the audit log.

Auth:인증: Console login only — manage this in Console → Developers → Webhooks (API keys get 403)콘솔 로그인 전용 — 콘솔 → 개발자 → 웹훅에서 관리 (API 키는 403)

Parameters파라미터

Request body요청 본문 (RotateWebhookSecretRequest)

{
  "reason_code": "rotation"
}

Response응답 200 — Endpoint with the new secret.

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "mode": "TEST",
    "endpoint_url": "string",
    "subscribed_events": [
      "string"
    ],
    "retry_policy": {
      "max_retries": 0,
      "backoff": "exponential"
    },
    "dead_letter_destination": "string",
    "status": "active",
    "created_at": "2026-11-06T07:00:00.000Z",
    "updated_at": "2026-11-06T07:00:00.000Z",
    "secret": "string"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 404 — see Errors.에러 참고.

POST /v1/developers/webhooks/test — Send a test event

Posts one signed sample event to an endpoint (no retries). The envelope id is prefixed test_, data.test is true and the request carries X-Webhook-Test: true.

Auth:인증: API key — Authorization: Bearer bp_test_… / bp_live_… (server only)API 키 — Authorization: Bearer bp_test_… / bp_live_… (서버 전용)

Parameters파라미터

Request body요청 본문 (SendTestWebhookRequest)

{
  "webhook_id": "00000000-0000-4000-8000-000000000000",
  "event_type": "checkout.session.paid"
}

Response응답 200 — Delivery result.

{
  "data": {
    "delivery_id": "00000000-0000-4000-8000-000000000000",
    "webhook_id": "00000000-0000-4000-8000-000000000000",
    "endpoint_url": "string",
    "event_type": "string",
    "http_status": 0,
    "response_body": "string",
    "error": "string",
    "duration_ms": 0,
    "test": true,
    "sent_at": "2026-11-06T07:00:00.000Z"
  },
  "meta": {
    "mode": "TEST",
    "requestId": "string",
    "total": 0,
    "limit": 0,
    "offset": 0
  }
}

Errors:에러: 400 · 401 · 404 · 409 — see Errors.에러 참고.

Webhook events웹훅 이벤트

Envelope: { id, event, created_at, data }, signed with X-Webhook-Signature-256. Verification and retries: Webhooks.

본문 구조: { id, event, created_at, data }, X-Webhook-Signature-256으로 서명됩니다. 검증과 재시도는 웹훅을 참고하세요.