iFrame Integration

Embed VeltoraPay's ready-made payment page into your website with minimal backend work.

Merchant API iFrame Integration H2H Provider

Overview

The iFrame integration lets you create a deposit session on your backend, then redirect or embed the payment page in your frontend. VeltoraPay handles the bank account assignment, payment UI, countdown timer, and status tracking — you just listen for the callback.

Best for: Quick integration with minimal frontend development. The entire payment UI is provided by VeltoraPay.

Integration Flow

Create iFrame Session (Backend)

Your server calls POST /dealer/{name}/iframe/create with user details and amount. Returns iframeUrl and token.

Show Payment Page (Frontend)

Redirect the user to iframeUrl or embed it in an <iframe>. The page shows bank details, countdown timer, and payment instructions.

User Transfers Funds

The customer transfers the exact amount to the displayed bank account via their banking app.

Auto-Match & Callback

VeltoraPay detects the incoming bank transfer, matches it, and sends a callback to your server with status: matched.

Create iFrame Session

POST/dealer/{dealerName}/iframe/create

Creates a new iFrame deposit session. Requires API key authentication.

Request Body

Field	Type	Required	Description
userId	string	Required	Unique customer identifier (max 120 chars). Alias: `customerId`
userName	string	Required	Customer's full name (max 160 chars). Alias: `customerName`
amount	decimal	Required	Deposit amount in TRY (0.01 – 10,000,000)
clientToken	string	Optional	Your unique TX reference (max 200 chars). Alias: `transactionId`
callbackUrl	string	Optional	Override the default callback URL (max 500 chars)
extraFields	object	Optional	Custom key-value metadata (max 10 keys, 2KB total)

Request

POST /dealer/yourmerchant/iframe/create
Content-Type: application/json
X-API-Key: your-api-key
X-API-Secret: your-api-secret

{
  "userId": "user-12345",
  "userName": "Ahmet Yilmaz",
  "amount": 500.00,
  "clientToken": "DEP-20260331-001",
  "extraFields": {
    "gameId": "roulette-42",
    "sessionRef": "abc123"
  }
}

Response — 200 OK

{
  "token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "iframeUrl": "https://api.veltorapay.com/dealer/yourmerchant/iframe/a1b2c3d4e5f6...",
  "expiresAt": "2026-03-31T10:30:00Z",
  "status": "pending",
  "isExisting": false
}

Duplicate Sessions: If the same userId already has an active session, the existing session is returned with "isExisting": true instead of creating a duplicate.

Session Expiry: Sessions expire in 30 minutes. After expiry, the deposit is automatically timed out.

Embed iFrame

Use the iframeUrl from the create response to show the payment page. No authentication needed for this URL.

GET/dealer/{dealerName}/iframe/{token}

Returns the full HTML payment page with bank details, countdown timer, copy-to-clipboard, and real-time status updates.

Status Polling

GET/dealer/{dealerName}/iframe/{token}/status

Poll for session status changes. No authentication required. Recommended polling interval: 3–5 seconds.

Response

{
  "status": "awaiting_payment",
  "amount": 500.00,
  "assignedIban": "TR12 0001 0012 3456 7890 1234 56",
  "assignedAccountName": "VeltoraPay A.S.",
  "assignedBankName": "Ziraat Bankasi",
  "expiresAt": "2026-03-31T10:30:00Z",
  "token": "a1b2c3d4...",
  "clientToken": "DEP-20260331-001"
}

Cancel Session

POST/dealer/{dealerName}/iframe/{token}/cancel

Cancels an active iFrame session. The underlying deposit request will be rejected with user_cancelled reason.

Callbacks

When the deposit status changes, VeltoraPay sends the same callback as the Direct API. See Merchant API — Deposit Callbacks for the full payload structure.

If you provided extraFields when creating the session, those fields are merged into the callback payload.

Callback with Extra Fields

{
  "event": "deposit.status_changed",
  "token": "a1b2c3d4...",
  "clientToken": "DEP-20260331-001",
  "status": "matched",
  "amount": 500.00,
  "senderName": "Ahmet Yilmaz",
  "iban": "TR12...",
  "bank": "Ziraat Bankasi",
  "gameId": "roulette-42",
  "sessionRef": "abc123",
  "timestamp": "2026-03-31T10:15:00Z"
}

Session Statuses

Status	Description
pending	Session created, waiting for bank account assignment
awaiting_payment	Bank account assigned, waiting for customer transfer
completed	Payment received and matched
cancelled	Cancelled by system or admin
user_cancelled	Cancelled by user via cancel button
expired	Session expired (30 min timeout)
maintenance	System is in maintenance mode

Extra Fields

The extraFields object lets you attach custom metadata to a session. This data is stored and returned in callbacks.

Constraint	Limit
Max keys	10
Total size	2 KB
Value types	string, number, boolean

Embed Examples

HTML iFrame Embed

<iframe
  src="https://api.veltorapay.com/dealer/yourmerchant/iframe/TOKEN_HERE"
  width="100%"
  height="700"
  frameborder="0"
  allow="clipboard-write"
  style="border-radius: 12px; border: 1px solid #1e2d4d;"
></iframe>

Redirect (Full Page)

// After creating session on your backend:
window.location.href = response.iframeUrl;

Popup Window

const popup = window.open(
  response.iframeUrl,
  'veltorapay-deposit',
  'width=480,height=720,scrollbars=yes'
);

// Poll for status
const interval = setInterval(async () => {
  const res = await fetch(`/dealer/yourmerchant/iframe/${token}/status`);
  const data = await res.json();
  if (data.status === 'completed' || data.status === 'cancelled') {
    clearInterval(interval);
    popup.close();
    // Handle result
  }
}, 3000);

React Component

function VeltoraPayDeposit({ iframeUrl }) {
  return (
    <iframe
      src={iframeUrl}
      style={{
        width: '100%',
        height: '700px',
        border: 'none',
        borderRadius: '12px'
      }}
      allow="clipboard-write"
    />
  );
}