Documentation

Install the SDK

npm install @vivapay/sdk

Initialize the client

import { VivaPay } from '@vivapay/sdk'

const vp = new VivaPay({
  apiKey: process.env.VIVAPAY_API_KEY,
  environment: 'production', // or 'sandbox'
})

Route a transaction

const result = await vp.route({
  amount: 10000, // in minor units (cents)
  currency: 'EUR',
  merchant: { id: 'merch_123', country: 'DE' },
  beneficiary: { iban: 'DE89370400440532013000' },
  metadata: { orderId: 'order_456' },
})

console.log(result.railSelected) // 'SEPA_DIRECT_DEBIT'
console.log(result.latencyMs)    // 11
console.log(result.transactionId) // 'txn_abc123'

API Keys

All API requests must include your API key in the Authorization header. Keys are scoped to your project and environment.

Authorization: Bearer vp_live_xxxxxxxxxxxxxxxxxxxx

Environments

Use vp_sandbox_ keys for testing and vp_live_ keys for production. Sandbox transactions do not move real money.

Rail Selection Signals

The engine evaluates over 40 real-time signals including:

• check_smallCurrent rail latency (sampled every 500ms)
• check_smallHistorical success rate per merchant category
• check_smallInterbank fees and FX spreads
• check_smallRegulatory restrictions by jurisdiction
• check_smallSettlement finality requirements

Overriding the Engine

You can pin a specific rail by passing the rail parameter:

const result = await vp.route({
  ...transactionData,
  rail: 'SWIFT', // force SWIFT regardless of engine recommendation
})

Event Types

• check_smalltransaction.routed — emitted when a rail is selected
• check_smalltransaction.settled — emitted when funds arrive
• check_smalltransaction.failed — emitted on routing or settlement failure
• check_smalltransaction.refunded — emitted when a refund is processed

Payload Example

{
  "event": "transaction.settled",
  "transactionId": "txn_abc123",
  "rail": "SEPA_DIRECT_DEBIT",
  "amount": 10000,
  "currency": "EUR",
  "settledAt": "2024-03-15T10:23:41Z"
}