Debugging integrations

When a charge fails, a webhook never lands, or a subscription drifts out of sync, the fastest path to a fix is reading what VINR actually saw. This page covers the request log, webhook delivery inspection, idempotency replays, and a repeatable sandbox workflow so you can reproduce and resolve issues without guessing.

Start with the request IDAskCopy

Every API response carries a request ID in the x-vinr-request-id header, and every error body echoes it. Capture and log it on the client side — it is the single fastest way to find the corresponding entry in the Dashboard or to hand to support.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

try {
  const payment = await vinr.payments.create({
    amount: 1000,
    currency: 'EUR',
    customer: 'cust_8sQ2',
  });
  console.log('ok', payment.id);
} catch (err) {
  // VinrError exposes the request ID, HTTP status, and a stable code.
  console.error('vinr error', {
    requestId: err.requestId,
    status: err.status,
    code: err.code,        // e.g. card_declined, idempotency_conflict
    message: err.message,
  });
}

Request logsAskCopy

The Dashboard logs every API request against your account: method, path, status, latency, the request ID, and the redacted request/response bodies. Filter by status code to surface failures, or paste a request ID straight into the search box.

You can also pull the same data programmatically to wire it into your own observability:

curl https://api.vinr.com/v1/request_logs?status=4xx \
  -H "X-Api-Key: $VINR_SECRET_KEY"

Inspecting webhook deliveryAskCopy

Most "the event never arrived" reports are delivery failures you can see and replay. Open the webhook endpoint in the Dashboard to view every attempt, the HTTP status your server returned, the response body, and the next scheduled retry.

// The body MUST be the raw bytes. Re-serializing JSON changes the
// signature and verification will fail.
export async function POST(req: Request) {
  try {
    const event = vinr.webhooks.verify(
      await req.text(),
      req.headers.get('x-vinr-signature'),
    );
    console.log('verified', event.id, event.type);
    return new Response('OK', { status: 200 });
  } catch (err) {
    console.error('signature verification failed', err.message);
    return new Response('bad signature', { status: 400 });
  }
}

Idempotency replaysAskCopy

When you send an idempotency key, VINR returns the original stored response for any retry with the same key. That makes debugging deterministic: replay the exact request and compare. A response carrying x-vinr-idempotent-replay: true means you hit the cache, not a fresh execution.

curl https://sandbox.api.vinr.com/v1/payments \
  -H "X-Api-Key: $VINR_SECRET_KEY" \
  -H "Idempotency-Key: order-4711-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"currency":"EUR","customer":"cust_8sQ2"}'

Common pitfallsAskCopy

Reproducing in sandboxAskCopy

The sandbox mirrors live behavior with deterministic test cards, so you can trigger any branch on demand.

To debug webhooks without a public URL, run the CLI to forward live deliveries to localhost:

vinr listen --forward-to http://localhost:3000/api/webhooks

Next stepsAskCopy