🚀 Getting Started

Welcome to VentaConnect! This section will walk you through everything you need to start testing stablecoin payments in your POS system — no blockchain experience required.

Please contact us at [e-mail] and we will guide you through the integration prerequisites and implementation steps.

🔗 Base URL

https://api.venta.xyz/v1

All endpoints are relative to the base URL above.

---

🔐 Authentication

All requests must include an API key in the headers.

Header Example:

x-api-key: <your-api-key>

API keys are tied to your POS account. Keys are rate-limited per minute and can be rotated at any time.

---

📊 Rate Limits

Each API key is limited to 120 requests per minute by default. If you need higher limits, please contact us.

---

🔁 Integration Flow

1. Request Beta Access

2. Register your Partner + get API Key

3. Register Merchant Shop(s)

4. Initiate Checkout Session

5. Generate SolanaPay QR Code

6. Confirm the Payment

7. Manage Keys or Rotate API Keys

---

Step 1: Request Beta Access

To begin, you’ll need a one-time beta code from the Venta team. This code allows you to generate your first API key and register as a partner.

🔐 Beta codes are issued manually. Reach out to your Venta contact or email [e-mail] to request one.

Step 2: Register your Partner + get API Key

Make a POST request to:

POST /partner

Body Parameters:

{
  "partnerName": "Your POS Name",
  "betaCode": "your-beta-code-here"
}

Response:

{
  "success": true,
  "data": {
    "apiKey": "your-new-api-key"
  }
}

⚠️ Save your apiKey. You will use it in all future requests via the x-api-key header.

Step 3: Register a Merchant

Each merchant in your POS system must be registered with Venta to receive a wallet and shop ID.

Once registered, merchant are required to verify email to initialise a checkout session

POST /shop

Headers:

x-api-key: your-api-key

Body:

{
  "name": "Merchant Name",
  "email" "[e-mail]",
  "externalId": "shop-1234",
  "country": "JP"
}

Response:

{
  "success": true,
  "data": {
    "shopId": "internal-uuid"  // Required for checkout
  }
}

Step 4: Initiate Checkout Session

Use the /dev/checkout/session endpoint to simulate a payment.

For production endpoint, remove dev/

Example: https://api.venta.xyz/v1/checkout

GET /dev/checkout/session?shopId={SHOP_ID}&amount=11.47

Headers:

x-api-key: your-api-key

Example:

https://api.venta.xyz/v1/checkout/dev/checkout/session?shopId={SHOP_ID}&amount=11.47

Response:

{
  "success": true,
  "data": {
    "link": "solana:https%3A%2F%2Fapi.venta.xyz%2Fv1%2Fcheckout%3Fref%ref_xyz",
    "ref": "ref_xyz",
    "ws": "wss://api.venta.xyz/ws/ref_xyz"
  }
}

What to do with link

• It is already encodeURIComponent-encoded for safe transport.

• You can display it as a QR code as-is; wallets will decode and open the Solana Pay URL.

• If you need to show a readable URL, decodeURIComponent(link) first.

Link Example

const qrCodeUrl = data.link;

// Example with qrcode library (Node.js or browser)
import QRCode from "qrcode";
QRCode.toCanvas(document.getElementById("canvas"), qrCodeUrl, function (error) {
  if (error) console.error(error);
  console.log("QR code generated!");
});

What to do with ref

• Keep it to correlate status updates.

What to do with ws

• Connect for real-time status updates (confirmed / expired / informational messages).

Connect to the WebSocket

const socket = new WebSocket("wss://api.venta.xyz/ws/ref_xyz");

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  switch (data.status) {
    case "confirmed":
      console.log("✅ Payment confirmed:", data.data?.txSig);
      break;
    case "expired":
      console.warn("⏰ Order expired:", data.code);
      break;
    case "update":
      console.info("ℹ️ Update:", data.code);
      break;
  }
};

✉️ Message Envelope

All WS messages are JSON with this shape:

{
   type: "payment.event";        // fixed
   ref: string;                   // e.g., "ref_xyz"
   status: "confirmed" | "expired" | "update";
   code: "PAYMENT_CONFIRMED" | "ORDER_EXPIRED" | "CONFIRMATION_TIMEOUT" | "TRANSACTION_FAILED" | "RECEIVE_REQUEST" | "TX_BUILD_ERROR" | "INSUFFICIENT_FUNDS";
   ts: number;                    // server ms since epoch
   data?: {
     txSig: string;              // present on confirmed
     explorer: string;           // view transaction information
   };
}

Statuses & Codes

Status	Code(s)	Meaning	Terminal
confirmed	PAYMENT_CONFIRMED	Payment landed, txSig provided	✅ Yes
expired	ORDER_EXPIRED, CONFIRMATION_TIMEOUT, TRANSACTION_FAILED	Payment window elapsed or transaction failed	✅ Yes
update	RECEIVE_REQUEST, TX_BUILD_ERROR, INSUFFICIENT_FUNDS	Informational updates: QR scanned, build failed, or insufficient funds	❌ No

Example Messages

// Confirmed
{
  "type": "payment.event",
  "ref": "ref_xyz",
  "status": "confirmed",
  "code": "PAYMENT_CONFIRMED",
  "ts": 1736370000000,
  "data": { 
    "txSig": "5DX...abc",
    "explorer": "https://explorer.solana.com/tx/4umH...h2NG"
  }
}

// Expired (order timeout)
{
  "type": "payment.event",
  "ref": "ref_xyz",
  "status": "expired",
  "code": "ORDER_EXPIRED",
  "ts": 1736370005000
}

// Update (tx build error)
{
  "type": "payment.event",
  "ref": "ref_xyz",
  "status": "update",
  "code": "TX_BUILD_ERROR",
  "ts": 1736370002000
}

🧼 When to Close the Connection

Once you’ve received a confirmed transaction or after a timeout (e.g. 3 minutes), you should close the WebSocket connection:

🛠 Fallback Strategy

In case the WebSocket disconnects (e.g. unstable network), your POS should periodically poll:

GET /dev/checkout/status?ref=ref_xyz

This ensures resilience and no missed confirmations.

Step 5: Confirm the Payment

Venta monitors the blockchain in real-time using WebSocket. But you can also manually check status:

GET /dev/checkout/status?ref=ref_xyz

Response:

{
  "success": true,
  "data": {
    "ref": "ref_xyz",
    "signature": "...",
    "status": "finalized",
    "confirmed": true
  }
}

✅ That’s it!

You’ve completed a full end-to-end test of VentaConnect.