---
name: paymentshub-api
description: Access the local PaymentsHub API for the OrderOps demo. Use when asked to inspect PaymentsHub capabilities, read the live OpenAPI contract, run live payment API requests, create an integration brief, or plan OrderOps payment actions without handling provider authorization manually.
---

# PaymentsHub API

Use this skill when working with the local PaymentsHub API from the
OrderOps demo.

## Workflow

1. Confirm the local PaymentsHub sandbox is running at `http://localhost:4010`.
2. Read the live OpenAPI document directly from:

   ```bash
   curl -fsS http://localhost:4010/openapi.yaml
   ```

3. Run live API requests from `demo-projects/orderops-admin`.
4. Separate confirmed API behavior from assumptions when summarizing findings.
5. Propose OrderOps implementation changes only after checking the live API.

## Auth Boundary

Never send an `Authorization` header manually.

Use the OrderOps helper script for PaymentsHub API requests:

```bash
bun run paymentshub:request -- GET '/payments?externalReference=ORD-1001'
```

The helper uses the fixed demo token unless `PAYMENTSHUB_API_TOKEN` is set in
`.env.local` or the process environment, injects provider auth, and returns the
HTTP status plus response body. Do not print, request, document, or copy the
token.

If a request needs a non-auth header, pass it through the helper:

```bash
bun run paymentshub:request -- POST /payments \
  --header 'X-Request-ID: <uuid>' \
  --body '{"externalReference":"ORD-1007","customerName":"Granite Health","customerEmail":"ap@granite.demo.orderops.local","amountCents":64500,"currency":"EUR","description":"ORD-1007: Premium support upgrade"}'
```

If the helper refuses a manual auth header, remove the header and retry through
the helper.

## Common Requests

Focus on the first demo workflow unless the user asks for more:

- List payments by `externalReference`.
- Create a payment.
- Read a payment by ID.
- Resend a payment request.

Do not propose refunds, reconciliation, webhooks, local provider-payment
persistence, bulk payments, approvals, real payment rails, or real provider
credentials for this demo slice.

## Output

When reporting findings, include:

- OpenAPI capabilities confirmed from `GET /openapi.yaml`.
- Live request evidence: method/path, status code, and relevant response fields.
- Gaps or surprises discovered while calling the API.
- Implementation implications for OrderOps.
- Any assumptions that remain unverified.