NeoPays Entegrasyon API

NeoPays API, yatırım yapan sitelerin (merchant) yatırım ve çekim işlemlerini programatik olarak NeoPays’e iletmesini, NeoPays’in de işlem durum güncellemelerini webhook ile siteye geri bildirmesini sağlar.

Akış

Site  ──POST /api/v1/deposit──►  NeoPays  ──(operator)──►  Webhook ──►  Site
Site  ──POST /api/v1/withdraw─►  NeoPays  ──(operator)──►  Webhook ──►  Site

İşlemler NeoPays’e PENDING (beklemede) olarak düşer; operatör onayladığında/reddettiğinde site’ın kayıtlı webhook adresine imzalı bir bildirim gönderilir.

Her istek Authorization başlığında site’ye özel API anahtarını taşımalıdır:

Authorization: Bearer npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• API anahtarı NeoPays panelinden site oluşturulurken üretilir ve yalnızca bir kez gösterilir (npk_ öneki + 64 karakter). Kaybolursa panelden “Yenile” ile yeni anahtar üretilir; eski anahtar anında geçersiz olur.
• Anahtar hiçbir zaman URL’de veya istemci (tarayıcı) tarafında bulunmamalı; yalnızca sunucudan sunucuya kullanılmalıdır.

Müşteri siteye yatırım yaptığında, site bunu NeoPays’e bildirir. NeoPays’te DEPOSIT / PENDING kaydı oluşur ve operatör paneline düşer.

İstek gövdesi (JSON)

Örnek istek

curl -X POST https://panel.neopaystr.com/api/v1/deposit \
  -H "Authorization: Bearer npk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2350,
    "currency": "TRY",
    "customerName": "Müşteri Adı",
    "customerRef": "u10234",
    "iban": "TR000000000000000000000000"
  }'

Başarılı yanıt · 200

{
  "ok": true,
  "id": "cmr…",
  "status": "PENDING",
  "awaitingDekont": false
}

Dekontlu yatırım (opsiyonel)

Dekont iki şekilde iletilebilir:

• A) JSON ile URL vererek — gövdeye dekontFileUrl ekleyin.
• B) Dosyayı doğrudan yükleyerek — multipart/form-data:

curl -X POST https://panel.neopaystr.com/api/v1/deposit \
  -H "Authorization: Bearer npk_…" \
  -F "amount=2350" \
  -F "customerRef=u10234" \
  -F "file=@dekont.jpg"

İzinli dosya tipleri: jpg, jpeg, png, webp, pdf.

“Dekont bekleniyor” davranışı

Site ayarında “dekont zorunlu” açıksa ve istekte dekont yoksa, yatırım reddedilmez — PENDING olarak oluşturulur ve awaitingDekont: true işaretlenir:

{
  "ok": true,
  "id": "cmr…",
  "status": "PENDING",
  "awaitingDekont": true,
  "message": "Yatırım alındı — dekont bekleniyor."
}

Dekont sonradan POST /api/v1/dekont ile transactionId alanı verilerek bağlanabilir; bağlanınca awaitingDekont otomatik false olur.

Müşteri siteden çekim istediğinde, site bunu NeoPays’e iletir. NeoPays’te WITHDRAWAL / PENDING kaydı oluşur; operatör onaylayınca ödeme yapılır ve webhook gönderilir.

İstek gövdesi

Örnek istek

curl -X POST https://panel.neopaystr.com/api/v1/withdraw \
  -H "Authorization: Bearer npk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "iban": "TR000000000000000000000000",
    "customerName": "Müşteri Adı",
    "customerRef": "u10234"
  }'

Başarılı yanıt · 200

{
  "ok": true,
  "id": "cmr…",
  "status": "PENDING"
}

İşlemin durumu değiştiğinde (operatör onayı/reddi), NeoPays sitenin kayıtlı webhook adresine imzalı bir POST gönderir. Sitenin durum güncellemesini alması için birincil ve yeterli yöntem budur — ayrıca sorgulama gerekmez.

• Webhook adresi ve imzalama sırrı (whsec_…) NeoPays panelinde site kaydında tanımlanır.
• Her istek gövdenin HMAC-SHA256 imzasını X-Signature başlığında taşır.
• Site HTTP 2xx dönmelidir; aksi halde NeoPays teslimatı başarısız olarak loglar.

Gelen istek

POST https://<sitenizin-webhook-adresi>
Content-Type: application/json
X-Signature: <hmac_sha256_hex>

Gövde (payload)

{
  "event": "transaction.status",
  "id": "cmr…",
  "type": "DEPOSIT",
  "status": "APPROVED",
  "amount": "2350",
  "currency": "TRY",
  "customerRef": "u10234",
  "iban": "TR…",
  "timestamp": "2026-07-18T21:00:00.000Z"
}

İmza doğrulama (zorunlu)

İmza, ham (raw) istek gövdesi üzerinden webhookSecret ile hesaplanır. Gövdeyi yeniden serialize etmeden, geldiği haliyle doğrulayın:

const crypto = require('crypto')

app.post('/api/neopays/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-signature']
    const expected  = crypto
      .createHmac('sha256', process.env.NEOPAYS_WEBHOOK_SECRET)  // whsec_…
      .update(req.body)
      .digest('hex')

    if (signature !== expected) return res.status(401).send('bad signature')

    const data = JSON.parse(req.body.toString())
    // data.id -> find your record, update by data.status
    // APPROVED/COMPLETED -> confirm · REJECTED/CANCELLED -> cancel

    return res.status(200).json({ ok: true })
  }
)

Pratik yorum: APPROVED / MATCHED / COMPLETED → olumlu (para geçerli), REJECTED / CANCELLED → olumsuz.

Hata yanıt formatı

{ "error": "Açıklama", "hint": "Authorization: Bearer <API_KEY>" }

Müşteriye gösterilecek yatırım IBAN’ını NeoPays havuzundan rotasyonla almak için:

POST /api/v1/iban/next
Authorization: Bearer npk_…
Content-Type: application/json

{ "amount": 2350, "customerRef": "u10234" }

Uygun IBAN yoksa 503 ({ "code": "NO_IBAN_AVAILABLE" }) döner.

• Panelden site oluşturuldu, API anahtarı güvenli saklandı (npk_…).
• Webhook adresi ve imza sırrı (whsec_…) panele girildi.
• Yatırım: POST /api/v1/deposit → PENDING kaydı düşüyor.
• Çekim: POST /api/v1/withdraw → geçerli IBAN ile PENDING kaydı düşüyor.
• Webhook: onay/red sonrası X-Signature doğrulanıp durum güncelleniyor, 2xx dönülüyor.
• İmza sırrı bir tarafta değişince diğer taraf da güncelleniyor.