VaultPay API Reference

VaultPay uses API keys to authenticate requests. Include your secret key in the Authorization header as a Bearer token. Keep your secret keys secure. Never expose them in client-side code or public repositories.

curl https://api.vaultpay.com/v2/payments \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "VP-Version: 2024-11-15"

Official client libraries for the most popular languages. Each SDK handles authentication, retries, and serialization automatically.

VaultPay returns conventional HTTP status codes and a structured JSON error body. Errors include a machine-readable code, a human-readable message, and an optional param field pointing to the invalid input.

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "The card was declined. Please try a different payment method.",
    "param": "payment_method",
    "request_id": "req_7xK9mRtL3vN2"
  }
}

HTTP Status Codes

Rate limits are enforced per API key. When you exceed your limit, subsequent requests return 429 Too Many Requests. Use the Retry-After header to determine when to retry.

Webhooks push real-time event notifications to your server via HTTP POST. Configure endpoints in your Dashboard or via the API. All webhook payloads include a VP-Signature header for verification.

Signature Verification

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [timestamp, hash] = signature.split(',');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected))) {
    throw new Error('Invalid webhook signature');
  }

  // Reject timestamps older than 5 minutes to prevent replay attacks
  const age = Date.now() / 1000 - parseInt(timestamp);
  if (age > 300) throw new Error('Webhook too old');

  return JSON.parse(payload);
}

Subscribe to the events you need. Each event includes the full resource object in its data field.

Idempotency prevents duplicate operations when requests are retried. Include an Idempotency-Key header with a unique value (UUIDs work well) on any POST request. If VaultPay receives a request with an already-used key, it returns the original response without re-processing.

curl -X POST https://api.vaultpay.com/v2/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{"amount": 5000, "currency": "usd", ...}'

All list endpoints use cursor-based pagination for consistent results, even when new records are added between requests. The response includes a has_more boolean and a next_cursor string to pass as the cursor query parameter on the next request.

// First page
GET /v2/payments?limit=20

// Next page (use next_cursor from previous response)
GET /v2/payments?limit=20&cursor=cur_xK9mRt3vN2qL

// Continue until has_more is false

VaultPay is built on a security-first foundation. Our infrastructure, processes, and APIs comply with the most stringent global standards for financial data protection, payment security, and regulatory compliance.

Certifications & Standards

Data Residency

VaultPay processes and stores data in the following regions. Specify your preferred region using the VP-Data-Region request header.

Encryption

All data in transit is encrypted using TLS 1.2 or higher. Cardholder data at rest is encrypted with AES-256. VaultPay never stores raw card numbers. All payment methods are tokenized on receipt using HSM-backed key management, reducing your PCI DSS scope to the minimum.

Responsible Disclosure

To report security vulnerabilities, contact security@vaultpay.com. VaultPay operates a coordinated disclosure programme and commits to acknowledging reports within 24 hours.

Use the following test cards and bank accounts in sandbox mode (sk_test_... keys). Test transactions are never processed on real networks and incur no charges.

Test Cards: Successful

Test Cards: Declines and Errors

Test Cards: 3D Secure

Test Bank Accounts (ACH)

A dispute (chargeback) occurs when a cardholder questions a charge with their card issuer. VaultPay notifies you immediately via the dispute.created webhook and provides an API to retrieve disputes and submit evidence. Winning a dispute requires submitting compelling evidence before the respond_by deadline.

Dispute Lifecycle

curl https://api.vaultpay.com/v2/disputes?status=needs_response \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

Every payment processed through VaultPay is automatically evaluated by our real-time fraud engine, powered by machine learning and integrated with NICE Actimize IFM-AI (Intelligent Fraud Management). A risk object is included in all payment responses.

Risk Object Fields

Risk Signal Codes

{
  "id": "pay_3Mq8R7vLkN2xT9",
  "object": "payment",
  "amount": 2500,
  "status": "succeeded",
  "risk": {
    "score": 22,
    "level": "low",
    "signals": [],
    "outcome": "approved"
  }
}

Strong Customer Authentication (SCA) is mandated by the EU's Payment Services Directive 2 (PSD2) for online card payments. VaultPay supports 3D Secure 2 (3DS2) natively. When a card issuer requires authentication, VaultPay returns a requires_action status with a redirect URL the customer must complete.

SCA Authentication Flow

// Step 1: Create payment — receives requires_action if SCA needed
POST /v2/payments → status: "requires_action"
                   next_action.type: "redirect_to_url"
                   next_action.redirect_url: "https://hooks.vaultpay.com/3ds/..."

// Step 2: Redirect the customer to the 3DS URL to authenticate with their bank

// Step 3: Customer completes authentication — VaultPay confirms and captures
POST /v2/payments/{id}/confirm → status: "succeeded"

SCA Exemptions

VaultPay automatically applies PSD2 exemptions where eligible to reduce customer friction:

VaultPay's AML framework is built on NICE Actimize SAM (Suspicious Activity Monitoring), providing real-time and batch transaction surveillance to detect money laundering, structuring, layering, and other financial crimes. All transactions are automatically screened against configurable rule sets aligned with FATF recommendations, FinCEN requirements, and EU AMLD6.

Monitoring Coverage