Интеграция с Visa/Mastercard для крипто-карты

Интеграция с Visa/Mastercard для крипто-карты

Прямая интеграция с Visa или Mastercard как principal member — процесс длиной 12-24 месяца с капитальными требованиями от $2M+. Реалистичный путь для стартапа — работа через program manager или directly-connected issuer, которые уже имеют членство в сетях. Эта страница описывает техническую сторону такой интеграции.

Участники экосистемы

Чтобы понять куда интегрироваться, нужно понять структуру:

Visa/Mastercard Network
    ↓
Principal Member Bank (BIN owner)
    ↓
Card Program Manager (Marqeta, Stripe Issuing, Galileo)
    ↓
Your Crypto Platform
    ↓
End User

Principal Member — банк с прямым членством в Visa/MC. Выдаёт BIN-диапазоны. Program Manager — технологический посредник, предоставляет API для выдачи карт, процессинга авторизаций. Берёт на себя технические и частично регуляторные обязательства. Your Platform — обрабатывает крипто-сторону: хранение активов, конвертация, пользовательский интерфейс.

Marqeta — основной путь

Marqeta — лидирующий card issuing API. Используется Cash App, DoorDash, Coinbase Card. Работает как program manager: вы через их API выпускаете карты, они обрабатывают авторизации и через Just-In-Time (JIT) funding запрашивают у вас средства в момент каждой транзакции.

JIT Funding — ключевая концепция

JIT (Just-In-Time) Funding — это механизм, при котором Marqeta не держит баланс пользователя у себя. Вместо этого: в момент каждой карточной авторизации Marqeta делает webhook запрос к вашему API, вы отвечаете approve/decline с суммой. Это позволяет применить вашу бизнес-логику (проверить крипто-баланс, сконвертировать) в реальном времени.

// Ваш JIT Funding endpoint
app.post("/marqeta/jit-funding", async (req, res) => {
  const { token, type, amount, currency_code, card_token } = req.body;
  
  // Это webhook от Marqeta — нужно ответить за 2-3 секунды max
  const userId = await getUserByCardToken(card_token);
  const user = await getUser(userId);
  
  // Конвертируем USD сумму в крипто
  const cryptoAmount = await convertUSDToCrypto(amount, user.preferredAsset);
  
  // Проверяем и резервируем баланс
  const hasBalance = await reserveBalance(userId, cryptoAmount);
  
  if (!hasBalance) {
    return res.json({
      jit_funding: {
        token: token,
        method: "pgfs.authorization",
        user_token: userId,
        amount: 0,
      },
      // decline
    });
  }
  
  return res.json({
    jit_funding: {
      token: token,
      method: "pgfs.authorization",
      user_token: userId,
      amount: amount,
      currency_code: "USD",
    },
  });
});

Marqeta API — выдача карт

import Marqeta from "@marqeta/core-api";

const marqeta = new Marqeta({
  applicationToken: process.env.MARQETA_APP_TOKEN,
  accessToken: process.env.MARQETA_ACCESS_TOKEN,
  baseUrl: "https://sandbox.marqeta.com/v3",
});

// Создание пользователя в Marqeta
async function createMarqetaUser(userId: string, userData: UserData) {
  const marqetaUser = await marqeta.users.create({
    token: userId,
    first_name: userData.firstName,
    last_name: userData.lastName,
    email: userData.email,
    birth_date: userData.birthDate,
    address1: userData.address,
    city: userData.city,
    state: userData.state,
    country: userData.country,
    postal_code: userData.postalCode,
  });
  
  return marqetaUser;
}

// Выдача виртуальной карты
async function issueVirtualCard(userId: string) {
  const card = await marqeta.cards.create({
    user_token: userId,
    card_product_token: process.env.CARD_PRODUCT_TOKEN,
  });
  
  // Получение PAN (номера карты) через secure channel
  const cardDetails = await marqeta.cards.getShowPAN(card.token);
  
  return {
    cardToken: card.token,
    last4: card.last_four,
    expiration: card.expiration,
    pan: cardDetails.pan,        // только для отображения в app
    cvv2: cardDetails.cvv_number, // только для отображения в app
  };
}

3DS (3D Secure) для онлайн-транзакций

Для онлайн-покупок (без физического POS-терминала) требуется 3DS верификация. Marqeta поддерживает 3DS 2.x через отдельный endpoint:

// 3DS Challenge handler
app.post("/marqeta/3ds-challenge", async (req, res) => {
  const { transaction_token, card_token, merchant } = req.body;
  
  // Отправляем пользователю push/SMS для подтверждения
  await sendOTPToUser(card_token, transaction_token);
  
  // Ответ: запросить OTP (challenge) или approve без challenge (frictionless)
  res.json({
    three_ds_decision: "CHALLENGE",
    otp_required: true,
  });
});

Stripe Issuing — альтернатива

Stripe Issuing проще в интеграции, доступен в 30+ странах. Не поддерживает JIT funding в полной мере — баланс должен быть pre-funded на Stripe счёте. Это значит нужно держать фиатный резерв у Stripe, что усложняет крипто-интеграцию.

Подходит для: B2B expense management карты, корпоративные карты с крипто-балансом. Не оптимален для consumer crypto debit cards.

import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Выдача карты
const card = await stripe.issuing.cards.create({
  cardholder: cardholderId,
  currency: "usd",
  type: "virtual",
  status: "active",
  spending_controls: {
    spending_limits: [{ amount: 50000, interval: "daily" }], // $500/day
  },
});

Authorizations и Settlement

Важно понимать разницу:

Authorization — проверка и блокировка средств. Происходит мгновенно. Ваш JIT endpoint должен отвечать за 2-3 секунды.

Clearing/Settlement — фактическое списание. Происходит через 1-3 рабочих дня. До этого момента сумма «заморожена».

Refund/Reversal — отмена транзакции. Может прийти через несколько дней после authorization. Система должна уметь обрабатывать revert hold.

// Обработка финального settlement
app.post("/marqeta/webhook", async (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case "authorization":
      // Hold: резервируем крипто
      await holdCrypto(event.card_token, event.amount);
      break;
      
    case "authorization.clearing":
      // Settlement: конвертируем и окончательно списываем
      await settleTransaction(event.transaction.token, event.amount);
      break;
      
    case "authorization.reversal":
      // Отмена: освобождаем заблокированную крипто
      await releaseHold(event.transaction.token);
      break;
      
    case "refund":
      // Возврат: зачисляем крипто обратно
      await refundCrypto(event.card_token, event.amount);
      break;
  }
  
  res.status(200).send("OK");
});

Управление курсовым риском

При холде USD суммы в крипто-эквиваленте — есть риск: курс изменится между authorization (T+0) и settlement (T+1..3). Три подхода:

Стейблкоин по умолчанию (USDC/USDT). Нет курсового риска. Пользователи хранят в стейблкоинах, оплата прямолинейна. Минус: нет крипто-апсайда.

Over-reservation. При авторизации резервируем сумму с буфером (+2-3%). При settlement излишек возвращается. Простое решение для небольших объёмов.

FX hedge. При авторизации фиксируем курс через деривативы или быстрый CEX trade. Сложнее, дороже, но точнее. Нужен для крупных объёмов или волатильных активов.

PCI DSS compliance

Работа с номерами карт (PAN) требует PCI DSS сертификации. Уровни:

• SAQ A — если не обрабатываете PAN напрямую (Marqeta хранит, вы только токены): minimal requirements
• SAQ D — если храните/обрабатываете PAN: полный audit, дорого

Рекомендация: используйте card tokenization (Marqeta Token Vault). Ваша система оперирует только card_token, PAN никогда не проходит через ваши серверы.

Регуляторный путь

Минимальный путь для EU: регистрация в Литве + паспортизация. Для остального мира — партнёрство с уже лицензированным эмитентом.

Сроки разработки

• Marqeta интеграция (JIT + card issuance + webhooks): 4-6 недель
• 3DS интеграция: +2-3 недели
• Crypto custody + конвертация: параллельно, 4-8 недель
• KYC/AML: 2-4 недели
• Mobile app: 8-12 недель
• Compliance + тестирование: 4-6 недель
• Итого (технически): 5-7 месяцев