שילוב שער תשלום קריפטו במסחר אלקטרוני הוא יותר מסתם חיבור SDK. לעיתים קרובות אנו נתקלים במצבים שבהם לאחר יצירת חשבונית, ה-webhook לא מגיע או שהסטטוסים מוכפלים, ומחלקת החשבונאות לא מצליחה להתאים נתונים. BitPay פותר את הבעיות האלה, אך דורש טיפול נכון בסטטוסים ו-idempotency.
אנו משלבים את BitPay בעסק שלך: מגדירים קבלת BTC, ETH, USDC, USDT דרך Ethereum, Polygon, Arbitrum, Base. BitPay דואג לתיעוד המשפטי ולהמרת פייט. הצוות שלנו ביצע 25+ אינטגרציות קריפטו. BitPay מהיר פי 3 להקמה מאשר שער מותאם אישית. נבחן את הפרויקט שלך בחינם — צור קשר.
איך זורם תהליך התשלום?
ה-API עובד דרך חשבוניות: השרת שלך יוצר חשבונית ב-BitPay, מקבל URL להפניית המשתמש, BitPay מקבל את התשלום ומודיע ל-webhook שלך. תיעוד מלא זמין ב-BitPay API Reference.
למה אימות ECDSA מורכב יותר ממפתח API?
BitPay חותם על בקשות עם מפתח פרטי במקום טוקן סטטי. זה מאובטח יותר, אך דורש יצירת זוג מפתחות ECDSA ורישום המפתח הציבורי כטוקן.
עבור רוב האינטגרציות, קל יותר להשתמש ב-SDK הרשמי של BitPay (Node.js, PHP, Python, Ruby, Java) — הוא כולל את חתימת הבקשות.
const BitPaySDK = require('bitpay-sdk'); const fs = require('fs'); // Генерация ключей и получение токена (один раз) async function setupBitPay() { const client = new BitPaySDK.Client( null, // конфиг файл BitPaySDK.Env.Prod, // или Env.Test для testnet fs.readFileSync('./private.key', 'utf8') // ECDSA приватный ключ ); // Токен из BitPay Dashboard → API Tokens await client.authorizeClient('your-pairing-code'); return client; } יצירת חשבונית
const BitPaySDK = require('bitpay-sdk'); async function createInvoice(orderId, amount, currency = 'USD') { const invoice = new BitPaySDK.Models.Invoice(amount, currency); invoice.orderId = orderId; invoice.notificationUrl = `https://yourapp.com/webhooks/bitpay`; invoice.redirectUrl = `https://yourapp.com/orders/${orderId}/success`; invoice.closeUrl = `https://yourapp.com/orders/${orderId}/cancel`; // Метаданные для reconciliation invoice.buyer = new BitPaySDK.Models.Buyer(); invoice.buyer.email = customerEmail; // Опционально: принимать только конкретную монету // invoice.paymentCurrencies = ['BTC', 'USDC']; const created = await client.createInvoice(invoice); return { invoiceId: created.id, paymentUrl: created.url, // редирект пользователя expirationTime: created.expirationTime }; } חשבונית תקפה ל-15 דקות כברירת מחדל — המשתמש חייב לשלם בתוך פרק זמן זה. הסכום בדולרים נקבע לפי שער החליפין של BitPay ברגע יצירת החשבונית.
טיפול ב-Webhook
BitPay שולח IPN (Instant Payment Notification) אל const BitPaySDK = require('bitpay-sdk'); const fs = require('fs'); // Генерация ключей и получение токена (один раз) async function setupBitPay() { const client = new BitPaySDK.Client( null, // конфиг файл BitPaySDK.Env.Prod, // или Env.Test для testnet fs.readFileSync('./private.key', 'utf8') // ECDSA приватный ключ ); // Токен из BitPay Dashboard → API Tokens await client.authorizeClient('your-pairing-code'); return client; } . חשוב לוודא את סטטוס החשבונית דרך ה-API, ולא רק לסמוך על גוף ה-webhook.
const express = require('express'); const router = express.Router(); router.post('/webhooks/bitpay', async (req, res) => { const { id: invoiceId, status } = req.body.data || {}; if (!invoiceId) { return res.status(400).json({ error: 'Missing invoice ID' }); } // ВАЖНО: верифицируем через API, не доверяем телу webhook const invoice = await client.getInvoice(invoiceId); switch (invoice.status) { case 'paid': // Оплачен, но ждём подтверждений (обычно 1-6 блоков) await updateOrderStatus(invoice.orderId, 'paid_unconfirmed'); break; case 'confirmed': // Достаточно подтверждений (обычно 1 для большинства монет) await updateOrderStatus(invoice.orderId, 'confirmed'); break; case 'complete': // Все подтверждения получены, средства зачислены await fulfillOrder(invoice.orderId); break; case 'expired': await updateOrderStatus(invoice.orderId, 'expired'); break; case 'invalid': // Underpayment или другая ошибка await handleInvalidPayment(invoice.orderId, invoice); break; } res.json({ success: true }); }); | סטטוס | תיאור | פעולה |
|---|---|---|
const BitPaySDK = require('bitpay-sdk'); async function createInvoice(orderId, amount, currency = 'USD') { const invoice = new BitPaySDK.Models.Invoice(amount, currency); invoice.orderId = orderId; invoice.notificationUrl = `https://yourapp.com/webhooks/bitpay`; invoice.redirectUrl = `https://yourapp.com/orders/${orderId}/success`; invoice.closeUrl = `https://yourapp.com/orders/${orderId}/cancel`; // Метаданные для reconciliation invoice.buyer = new BitPaySDK.Models.Buyer(); invoice.buyer.email = customerEmail; // Опционально: принимать только конкретную монету // invoice.paymentCurrencies = ['BTC', 'USDC']; const created = await client.createInvoice(invoice); return { invoiceId: created.id, paymentUrl: created.url, // редирект пользователя expirationTime: created.expirationTime }; } | החשבונית נוצרה, ממתין לתשלום | המתן |
notificationUrl | שולם אך לא אושר | הכנס לתור |
const express = require('express'); const router = express.Router(); router.post('/webhooks/bitpay', async (req, res) => { const { id: invoiceId, status } = req.body.data || {}; if (!invoiceId) { return res.status(400).json({ error: 'Missing invoice ID' }); } // ВАЖНО: верифицируем через API, не доверяем телу webhook const invoice = await client.getInvoice(invoiceId); switch (invoice.status) { case 'paid': // Оплачен, но ждём подтверждений (обычно 1-6 блоков) await updateOrderStatus(invoice.orderId, 'paid_unconfirmed'); break; case 'confirmed': // Достаточно подтверждений (обычно 1 для большинства монет) await updateOrderStatus(invoice.orderId, 'confirmed'); break; case 'complete': // Все подтверждения получены, средства зачислены await fulfillOrder(invoice.orderId); break; case 'expired': await updateOrderStatus(invoice.orderId, 'expired'); break; case 'invalid': // Underpayment или другая ошибка await handleInvalidPayment(invoice.orderId, invoice); break; } res.json({ success: true }); }); | אישורים מינימליים (בדרך כלל 1) | זיכוי חלקי |
new | כל האישורים, הכספים זוכו | בצע הזמנה |
paid | המשתמש לא שילם תוך 15 דקות | בטל |
confirmed | תשלום חלקי או שגיאה | החזר |
למימוש ההזמנה, השתמש ב-complete או expired בהתאם לרמת הסיכון שלך. invalid הוא הבטוח ביותר אך יש לו עיכוב ארוך יותר.
החזרים
BitPay דורש כתובת החזרה — יש לבקש אותה מהמשתמש בזמן התשלום או בעת ייזום החזר.
async function createRefund(invoiceId, amount, currency) { const refund = new BitPaySDK.Models.Refund(); refund.invoiceId = invoiceId; refund.amount = amount; refund.currency = currency; // валюта возврата const created = await client.createRefund(refund); // BitPay отправит email пользователю с запросом адреса return created; } סיכונים המכוסים על ידי BitPay
BitPay מטפל באבטחת העסקאות, מבטיח ללא chargebacks (תשלומים בלתי הפיכים), ומספק דוחות מאושרים לחשבונאות. לפי התיעוד הרשמי, הפלטפורמה אינה דורשת אישור רגולטורי נוסף.
השוואה: BitPay מול שער מותאם אישית
| פרמטר | BitPay | שער מותאם אישית |
|---|---|---|
| זמן עד השקה | 2–3 ימים | 2–4 שבועות |
| תמיכה משפטית | תיעוד מוכן | נדרש עורך דין |
| המרת פייט | אוטומטית | נדרשת בורסה |
| אבטחה | ECDSA + PCI-certified | אחריות מלאה |
בעיות אינטגרציה נפוצות
Webhook לא מגיע. BitPay דורש HTTPS עם תעודה תקפה על confirmed. Localhost אינו נגיש — לפיתוח השתמש ב-ngrok או ב-BitPay Testnet עם URL ציבורי.
Webhooks כפולים. BitPay עשוי לשלוח מספר התראות עבור אותו סטטוס (ניסיון חוזר על timeout). השתמש ב-complete כמפתח idempotency: complete.
תשלום חלקי. אם המשתמש משלם פחות, הסטטוס הופך ל-async function createRefund(invoiceId, amount, currency) { const refund = new BitPaySDK.Models.Refund(); refund.invoiceId = invoiceId; refund.amount = amount; refund.currency = currency; // валюта возврата const created = await client.createRefund(refund); // BitPay отправит email пользователю с запросом адреса return created; } . BitPay מחזיר אוטומטית את התשלום החסר אם כתובת האימייל של הקונה זמינה.
אזור זמן ב-expirationTime. השדה מוחזר כחותמת זמן Unix במילישניות. notificationUrl — זכור שזה מילישניות, לא שניות.
בדיקות
BitPay מספק סביבת Testnet (invoiceId) עם ביטקוין לבדיקה. צור חשבונית, שלם עם ארנק testnet — כל התהליך ללא כסף אמיתי. קוד ההתאמה לסביבת הבדיקה נוצר בנפרד בלוח הבקרה.
מה כלול בעבודה
- אינטגרציית BitPay SDK (Node.js, PHP, Python, Ruby, Java)
- הקמת נקודת webhook עם idempotency
- טיפול בסטטוסים ובמקרי קצה (חשבונית שפגה, תשלום חלקי, ניסיון חוזר)
- בדיקות Testnet והעלאה לאוויר
- תיעוד המימוש שלך
- 30 ימי תמיכה לאחר ההשקה
לוח זמנים משוער
2–3 ימים: יום אחד ל-SDK, יום אחד ל-webhook + מכונת מצבים, יום אחד לבדיקות. העלות המדויקת מחושבת באופן אישי לפי מורכבות האינטגרציה. קבל ייעוץ — צור קשר להערכת פרויקט. הזמן אינטגרציית BitPay, ונגדיר קבלת קריפטו תוך 48 שעות.