API and webhooks · Contracts, ownership and asynchronous effects

The 60-second model#

An API test checks an agreed service boundary: request/response, permissions, business invariants and observable effects. A webhook is a server-to-server event notification whose delivery and processing can be delayed, repeated or reordered. Neither HTTP 2xx nor “callback received” alone proves the intended payment effect.

HTTP semantics and useful negatives#

Test required/omitted/null/wrong-type fields, integer amount bounds, unsupported currency, invalid transitions, duplicate keys, role/tenant boundaries, concurrency and side effects. .ok() accepts any 2xx; it cannot prove the payment is CAPTURED. A static DTO assertion does not validate JSON bytes.

A complete create/read/cleanup test#

// tests/api/payment.spec.ts. Hypothetical safe sandbox/test-support contracts.
import { test, expect } from '@playwright/test';
import { randomUUID } from 'node:crypto';
test('created payment has the correct owned amount', async ({ request }, info) => {
  const correlation = randomUUID();
  const created = await request.post('/test-support/payments', {
    data: { amountMinor: 1250, currency: 'GEL', correlation },
  });
  expect(created.status()).toBe(201);
  const body: unknown = await created.json();
  if (!body || typeof body !== 'object' || !('id' in body) || typeof body.id !== 'string') {
    throw new Error('Expected payment id');
  }
  const id = encodeURIComponent(body.id);
  let failed = false;
  try {
    const response = await request.get(`/sandbox/payments/${id}`);
    expect(response.status()).toBe(200);
    expect(await response.json()).toMatchObject({ id: body.id, amountMinor: 1250, currency: 'GEL' });
  } catch (error) { failed = true; throw error; }
  finally {
    try {
      const deleted = await request.delete(`/test-support/payments/${id}`);
      expect(deleted.status()).toBe(204);
    } catch (error) {
      await info.attach('cleanup-failure', { body: String(error), contentType: 'text/plain' });
      if (!failed) throw error;
    }
  }
});

Assumes configured sandbox baseURL/auth and an authorized reset API; real financial records are not casually deleted. Creation may commit before its response is lost: correlation lookup/expiry is still needed to recover unknown owned records. Cleanup is attempted, not guaranteed during outages. Redact diagnostic attachments as needed.

Runtime shape, headers and permissions#

// Scoped inside a Playwright test with request/expect and isolated merchant fixtures.
const invalid = await request.post('/sandbox/payments', {
  data: { amountMinor: -1, currency: 'GEL' },
});
expect(invalid.status()).toBe(422); // hypothetical agreed error contract
expect(invalid.headers()['content-type']).toContain('application/json');
expect(await invalid.json()).toMatchObject({ code: 'INVALID_AMOUNT' });

// Standalone parser, deliberately narrow teaching contract.
export type Payment = { id: string; amountMinor: number; currency: string };
export function parsePayment(value: unknown): Payment {
  if (!value || typeof value !== 'object' || !('id' in value) ||
      typeof value.id !== 'string' || !value.id || !('amountMinor' in value) ||
      typeof value.amountMinor !== 'number' || !Number.isSafeInteger(value.amountMinor) ||
      !('currency' in value) || typeof value.currency !== 'string') throw new Error('Invalid payment');
  return { id: value.id, amountMinor: value.amountMinor, currency: value.currency };
}

Schema validity and business validity are separate: this parser allows a negative integer, so the creation/business-rule test must reject it where required. Add enum/range/ISO-currency checks according to actual requirements or an optional schema validator.

Create payment A as merchant A, then access it through a distinct context/token for B. Assert the specified deny response and no data/effect leakage. Also vary same-merchant read-only versus refund permission, expired tokens and malformed IDs. request is a direct HTTP context; a page.route mock does not intercept these calls.

Idempotency exercise#

// Scoped test body. Backend explicitly supports this header and replay policy.
const key = randomUUID(); // import from node:crypto
const payload = { amountMinor: 1250, currency: 'GEL', methodToken: sandboxToken };
const first = await request.post('/sandbox/payments', {
  headers: { 'Idempotency-Key': key }, data: payload,
});
expect(first.status()).toBe(201);
const original: { id: string } = await first.json();
const replay = await request.post('/sandbox/payments', {
  headers: { 'Idempotency-Key': key }, data: payload,
});
expect(replay.status()).toBe(200); // illustrative replay status, not a PSP standard
expect(await replay.json()).toMatchObject({ id: original.id });

Also verify one intended financial effect via a supported sandbox read, changed payload with same key, simultaneous repeats, key scoping by merchant/operation and documented retention window. Never assume one provider's status/cache/expiry rules apply to another. On timeout, reconcile by the supported original operation identity before replay.

Webhook risk matrix#

Verify signatures with the provider's supported library/protocol, including required raw-body handling. Do not replace it with an invented generic HMAC recipe. Timestamp tolerance, retries, ordering and accepted response codes are provider-specific. Acknowledge only according to the ingestion durability contract: acknowledging before any durable handoff can lose events if the process then crashes.

// Scoped test body: authorized signed-event simulator, not an OMNO endpoint.
const result = await request.post('/test-support/provider-events', {
  data: { paymentId: payment.id, eventId: event.id, status: 'CAPTURED', deliveries: 2 },
});
expect(result.status()).toBe(202);
await expect.poll(async () => {
  const read = await request.get(`/test-support/payments/${payment.id}/effects`);
  expect(read.status()).toBe(200);
  return (await read.json()).captureCount;
}, { timeout: 10_000, intervals: [100, 250, 500] }).toBe(1);

One observed count at one moment is not sufficient to prove no later duplicate: wait for the harness's all deliveries processed barrier or a documented quiescence/watermark, then assert final count. Test both ingestion acknowledgement and resulting business state. A route mock cannot exercise real webhook persistence.

Contract tests versus sandbox integration#

OpenAPI/schema tests check documented shape/status; consumer contracts check an interaction a caller relies on. Neither proves every deployed provider flow. Use controlled provider simulations for rare timeouts/orderings, a small real PSP sandbox suite for actual integration, and UI tests for rendering/user flows. Postman/Swagger support manual discovery; Playwright integrates API/UI fixtures and CI reporting. Test selection follows risk, not tool loyalty.

Interview answer and references#

30 seconds: “I test API status, runtime body, permissions and business effects. For payments I add duplicate/concurrent submission and uncertain-outcome handling. For webhooks I cover signature validation, duplicate and out-of-order delivery, durable ingestion and final state, using authorized simulators plus a focused real sandbox integration suite.”

Memory hook: response + identity + shape + permission + effect. References: Playwright API testing, Stripe webhook guidance, one provider example, HTTP semantics. Next: TypeScript.

Quick practice#