Skip to content
VPawn

API v1

Checkout API

Send the member to the VPawn checkout window and get the result by webhook or the lookup API. Signing, sign-in and payment all happen on www.vpawn.io. Your page may only open it by redirect or popup; iframes are blocked.

Getting started

  1. Ask a VPawn operator to register your allowed origins (https), webhook URL (https, port 443, public IP) and the collections you sell.
  2. The operator issues API keys (vb_test_… = Amoy test, vb_live_… = Polygon live) and one webhook secret per mode (whsec_…). The plain text is shown once, when it is issued.
  3. Keep keys on your server only. Never put them in a browser or an app.

There is one API address, api.vpawn.io. The key prefix picks the environment: vb_test_ keys run on the test site (www.vpawn.io, Amoy), vb_live_ keys on https://www.vpawn.io. Test checkout and use pages open on www.vpawn.io.

Basics

  • Base URL: https://api.vpawn.io/api/v1 (same for test and live keys)
  • Auth: Authorization: Bearer vb_live_…
  • Requests and responses are JSON. Responses carry Cache-Control: no-store.
  • Amounts are integer strings in USDT minor units (6 decimals). "125000000" = 125 USDT.
  • Addresses and hashes are lowercase 0x…; times are UTC ISO 8601 to the second.
  • Rate limit: 120 per minute per key, 600 per minute per IP. Beyond that: 429 RATE_LIMITED.
  • Errors: {"error": "<code>", "message": "<text>"}

Error codes

400 INVALID_REQUEST
Malformed body (message names the field)
400 INVALID_JSON / INVALID_IDEMPOTENCY_KEY
Not JSON / bad key format
400 INVALID_URL / URL_NOT_ALLOWED
success/cancel URL is not https or its origin is not registered
401 INVALID_API_KEY
Missing, wrong or revoked key
403 MODE_NOT_SERVED
Key of a mode this environment does not serve
403 PARTNER_SUSPENDED
Partner suspended. Only new sessions are blocked
403 COLLECTION_NOT_ALLOWED
Item outside your allowed collections
404 ITEM_NOT_FOUND / SESSION_NOT_FOUND
No such item or session. Another partner's item_id also returns ITEM_NOT_FOUND
409 ITEM_UNAVAILABLE / SOLD_OUT
Sale not open or ended, order expired, or (PARTNER_ITEM) the item is not on sale or the partner paused its sale / not enough left
409 IDEMPOTENCY_KEY_REUSED
Same Idempotency-Key used with a different body
404 TOKEN_NOT_FOUND / 409 ALREADY_USED
Use sessions: no such token or not yours / already used
409 SESSION_PROCESSING / SESSION_FINAL
Payment in progress or already finished, so it cannot be cancelled
413 TOO_LARGE
Body over 16 KB
422 QUANTITY_LIMIT
Over the per-wallet purchase limit (LAUNCHPAD, PARTNER_ITEM)
429 RATE_LIMITED
Rate limit

Create a session

Idempotency-Key header (optional): the same key with the same body returns the first result; a different body returns 409. The same partner_order_id also returns the existing session (201 when created, 200 when existing).

POST /checkout/sessions
{
  "kind": "LAUNCHPAD",
  "event_id": "12",
  "quantity": 1,
  "partner_order_id": "ORD-2026-000123",
  "success_url": "https://partner.example/orders/123/done",
  "cancel_url": "https://partner.example/orders/123",
  "locale": "ko",
  "metadata": { "campaign": "fall" }
}

Fields

kind
LAUNCHPAD (launchpad event), PARTNER_ITEM (partner digital asset) or MARKET (marketplace listing)
event_id, quantity
LAUNCHPAD. event_id is an integer string, quantity is 1–1000 (within the per-wallet limit)
item_id, quantity
PARTNER_ITEM. item_id is the item ID shown in your partner screen (positive integer string), quantity is 1–100 (within the per-wallet limit). The item must be yours and on sale
customer_email
Optional, any kind. Valid email, up to 254 characters, stored lowercase. If set, the customer can pay only with a code sent to that email; other accounts cannot pay this session. If omitted, any signed-in member can pay
order_hash
MARKET. Hash of a live listing (0x + 64 characters)
partner_order_id
Unique within your account. A–Z a–z 0–9 . _ : -, 1–64 characters
success_url, cancel_url
https, exactly one of your registered origins (any path). Ask a VPawn operator to register a new origin
locale
ko (default) or en
metadata
Optional. String values only, up to 20 keys. Do not put personal data in it
{
  "id": "cs_5f0c…",
  "url": "https://www.vpawn.io/checkout/cs_5f0c…",
  "status": "OPEN",
  "currency": "USDT",
  "total_minor": "125000000",
  "expires_at": "2026-11-01T03:30:00Z",
  "mode": "live"
}
  • Unknown fields return 400 INVALID_REQUEST.
  • The price is read from the chain or the order signature and locked when you create the session. total_minor is the most the member can pay. With a tier discount the actual payment (paid_minor) can be lower.
  • A session lasts 30 minutes, or until the listing expires if that comes first (MARKET).
  • Send the member to url (redirect or popup).
  • PARTNER_ITEM: the price is locked as the item's current unit price × quantity.
  • PARTNER_ITEM checkout flow: (1) With customer_email, the customer sees the masked email and signs in with a code sent to it; without it, any signed-in member can pay. (2) Signed in with a different account, the customer is asked to switch. (3) With no wallet, the customer creates one in the checkout window with a password (the recovery code can be saved later). (4) Pay with the wallet's USDT or by card (Wert). The Wert card fee is paid by the customer on top of the amount; your share is the same. Live (Polygon) card payment is off until VPawn enables it. (5) When the chain confirms, the session becomes PAID and the webhook is sent.

Get a session

The create response plus the fields below. item_id is set only for PARTNER_ITEM, and customer_email only if you sent it (otherwise null); event_id and order_hash are null for other kinds. collection is in this response and the webhook, not in the create response.

GET /checkout/sessions/{id}
{
  …,
  "partner_order_id": "ORD-2026-000123",
  "kind": "LAUNCHPAD", "event_id": "12", "quantity": 1, "order_hash": null,
  "collection": "0x…", "token_ids": ["101"],
  "paid_minor": "112500000", "failure_reason": null,
  "tx_hash": "0x…", "recipient_wallet": "0x…", "chain_id": 137,
  "paid_at": "2026-11-01T03:12:44Z", "created_at": "2026-11-01T03:00:00Z",
  "locale": "ko", "metadata": { "campaign": "fall" }
}

status

OPEN
Waiting for payment
PROCESSING
Signed and sent, waiting for the chain
PAID
Confirmed by a chain event (final)
FAILED
Failed (final). failure_reason: PRICE_CHANGED, ITEM_UNAVAILABLE, SOLD_OUT, LIMIT, TX_REVERTED
EXPIRED
Timed out or cancelled by the partner

No response contains a member's email or name, other than the customer_email you sent. recipient_wallet is the receiving address, which is public on chain.

Cancel a session

POST /checkout/sessions/{id}/expire

Only before payment (OPEN, nothing in flight). An already EXPIRED session is returned as it is. The checkout.session.expired webhook is sent.

If the member's transaction was sent at almost the same moment, the session goes from EXPIRED to PAID when that transaction confirms and the completed webhook follows. Always fulfil orders from the latest state.

List items

GET /catalog/items?collection=0x…

Items on sale in your allowed collections. Leave out collection for all of them; a collection outside your list returns 403.

For display only (the indexer can be a few seconds behind). The price is read from the chain again when you create a session.

Webhooks

checkout.session.completed
PAID
checkout.session.failed
FAILED
checkout.session.expired
EXPIRED
item.used
The burn of a used digital asset is confirmed (see Use digital assets)
  • POST <webhook URL>, Content-Type: application/json.
  • VBank-Signature: t=<unix seconds>,v1=<hex> — HMAC-SHA256(webhook secret, "<t>.<raw body>").
  • VBank-Event-Id: evt_… — unique per event and the same on every retry. Use it to drop duplicates.
  • data.total_minor is the amount actually paid (paid_minor). failed adds data.failure_reason.
  • data.item_id (decimal string) is present only when kind is PARTNER_ITEM. data.customer_email is present only if you sent it when creating the session (any kind).
  • Answer with 2xx within 10 seconds. A 3xx is not followed and counts as a failure.
  • On failure we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h (7 tries at most). If all fail, an operator checks.
  • Delivery is at least once and not ordered. You may check the current state with the lookup API before acting.
{
  "id": "evt_…",
  "type": "checkout.session.completed",
  "created_at": "2026-11-01T03:12:44Z",
  "mode": "live",
  "data": {
    "session_id": "cs_…",
    "partner_order_id": "ORD-2026-000123",
    "kind": "LAUNCHPAD",
    "collection": "0x…",
    "token_ids": ["101"],
    "total_minor": "112500000",
    "currency": "USDT",
    "recipient_wallet": "0x…",
    "tx_hash": "0x…",
    "chain_id": 137
  }
}

Verify the signature (Node.js)

Verify against the raw body exactly as received (before parsing) and drop any t older than 5 minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyVPawnWebhook(secret, rawBody, header, nowSec = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(nowSec - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Use digital assets

Using a digital asset burns its NFT, and your service then provides the benefit. There are two starting points: the member uses it from My assets in VPawn, or your service opens a use session and sends the member to its url. The item is the same either way.

POST /use-sessions
{
  "token_id": "101",
  "customer_email": "player@example.com",
  "success_url": "https://partner.example/inventory/done",
  "cancel_url": "https://partner.example/inventory",
  "locale": "en"
}

POST /use-sessions

token_id
Required. Decimal integer string
collection
Optional. Contract address (0x + 40 characters). Left out, your registered collection is used
customer_email
Optional. Valid email, up to 254 characters, stored lowercase. If set, the member signs in with a code sent to that email
success_url, cancel_url
Required. https, exactly one of your registered origins (any path), as in checkout
locale
ko (default) or en
{
  "id": "us_5f0c…",
  "url": "https://www.vpawn.io/use/us_5f0c…",
  "status": "OPEN",
  "mode": "live",
  "collection": "0x…",
  "token_id": "101",
  "item_id": "34",
  "customer_email": "player@example.com",
  "tx_hash": null,
  "used_at": null,
  "expires_at": "2026-11-02T06:11:05Z",
  "created_at": "2026-11-02T05:41:05Z"
}
  • Unknown fields return 400 INVALID_REQUEST. A session lasts 30 minutes. The response (201) has id (us_…), url, status, mode, collection, token_id, item_id, customer_email, tx_hash, used_at, expires_at and created_at.
  • GET /use-sessions/{id} returns the same shape (item_id can be null if the token cannot be read yet). Only your own sessions of the same mode are found.
  • On return, ?use_session_id=us_… is added to success_url. It is not proof of use; confirm from the item.used webhook or a USED lookup.

status

OPEN
Waiting to be used
USED
The token is burned and confirmed, by any path (this session or My assets). tx_hash and used_at are set
EXPIRED
Timed out

Errors

404 TOKEN_NOT_FOUND
No such token, or it is not in your collection (another partner's token also returns this)
409 ALREADY_USED
The token is already burned or used
404 SESSION_NOT_FOUND
No such session (lookup)

What the member sees

  • With customer_email, the member signs in with a code sent to the masked email; otherwise they sign in to VPawn.
  • The token must be in a wallet of that account.
  • A warning says using it burns the NFT and cannot be undone, and the partner provides the benefit. The member must agree.
  • Delivery email: for a token bought through your checkout it is the purchase email only if the checkout session had a customer_email and the buyer still holds the token; otherwise the member enters it. A burn outside VPawn also carries the purchase email under the same rule, else none (null).
  • When the chain confirms the burn, item.used is sent and the member returns to success_url.

item.used webhook

Sent once, after the chain confirms the burn. Signing, headers and retries are the same as above.

{
  "id": "evt_…",
  "type": "item.used",
  "created_at": "2026-11-02T05:41:09Z",
  "mode": "live",
  "data": {
    "use_id": "…",
    "use_session_id": "us_…",
    "item_id": "34",
    "item_name": "Dragon Sword",
    "collection": "0x…",
    "token_id": "101",
    "wallet": "0x…",
    "customer_email": "player@example.com",
    "tx_hash": "0x…",
    "chain_id": 137,
    "used_at": "2026-11-02T05:41:05Z"
  }
}
use_id
ID of this use
use_session_id
Your use session (us_…), or null when it was used from My assets, burned outside VPawn, or used after the token moved
item_id
Item ID (decimal string)
item_name
English item name. Can be an empty string, so key on item_id
collection, token_id
The burned token
wallet
Wallet that burned it
customer_email
Delivery email: the purchase email if the checkout session had a customer_email and the buyer still holds the token; otherwise what the member entered; for burns outside VPawn the purchase email under the same rule, else null
tx_hash, chain_id
The burn transaction
used_at
Burn time (UTC)
  • Drop duplicates by event ID. The same use only comes again with the same ID.
  • Provide the benefit on item.used only, not on the return to success_url.
  • No member name or account ID is included.
  • A delivery that failed all 7 tries (FAILED) can be re-sent by you in the partner Developers screen (recent webhook deliveries) or by a VPawn operator. It keeps the same event ID.
  • Set a webhook URL before you register items (NO_WEBHOOK). Once you have items on chain you can change the URL but not clear it (WEBHOOK_REQUIRED). Without a URL VPawn refuses to start a use (NO_WEBHOOK). A burn outside VPawn while you have no URL is kept as a FAILED delivery (NO_WEBHOOK_URL); set the URL, then re-send it. A re-send goes to the URL set at send time.

How payment is confirmed

  • Returning to success_url is not proof of payment. Confirm an order only from the webhook or a PAID lookup.
  • A session becomes PAID only when the chain event the indexer saw has the hash of the transaction sent for this session, and item, quantity and amount match.
  • It is confirmed after a few blocks (an operator setting) are on top. On Polygon this usually takes 10–15 seconds.
  • If something does not match, nothing is confirmed and an operator checks. After 15 minutes without a matching event the transaction is treated as not a payment.

Test mode

  • vb_test_ key = Polygon Amoy (80002) + TestUSDT0. The checkout window shows a "Test" band.
  • Test and live sessions never see each other, and each mode has its own webhook secret.