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
- Ask a VPawn operator to register your allowed origins (https), webhook URL (https, port 443, public IP) and the collections you sell.
- 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.
- 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.
