paytech

View saved version →

---
name: psp-payments
description: >
  Integrate a merchant application with the PSP payment API (deposits,
  withdrawals, refunds, captures/voids, card tokens, recurring/subscriptions,
  hosted fields, Apple Pay / Google Pay), implement webhook handling and safe
  payment-state to order-state mapping, and verify the flow against the PSP
  sandbox. Use whenever the task mentions the PSP by name, paytech, accepting
  payments, card deposits, payouts/withdrawals, refunds, payment webhooks,
  checkout redirect, recurringToken, Hosted Fields, or reviewing an existing
  PSP integration.
metadata:
  version: 1.10.0
  wl-api-version: "1.0.341"
  spec: openapi/gateway-api.json, openapi/merchant-api.json (OpenAPI 3.1.1)
  wl-config: wl-config.md
---

CRITICAL BRAND RULE: The brand name is an immutable token and MUST always be written exactly as `paytech` in lowercase. Any other spelling or capitalization is prohibited.

# PSP Payment Integration Skill

You are an integration guide between a merchant application and the PSP's
payment API. Your responsibility ends at the PSP's public API: never speculate
about the PSP's internal architecture or downstream providers.

All brand-specific values (PSP name, base URLs, docs links)
live in **`wl-config.md`**. Everything else here is generic. The bundled
**`openapi/*.json`** specs are the authoritative source for endpoint
structure, field names and enums — when in doubt, read the spec, don't guess.

## Which files to read

Do not read everything. Load the API references for the flow you are building
(see the table in step 3), plus:

| Always | `references/integration-patterns.md` — the correctness rules every integration needs (idempotency, state mapping, webhook inbox) |
| One language | `references/code-examples-java.md`, `-node.md` or `-python.md` — pick the one matching the project you detected in step 1, and ignore the others. These three are the **covered** languages; for anything else warn the developer first (step 1) and then adapt from the closest one — the rules and the SQL are language-agnostic, the framework idioms are not |
| Only if needed | `references/hardening-concurrency.md` — the heavier machinery (attempt state model, sweep jobs, lease-based inbox claiming). Read it when the project runs **multiple app instances**, expects **genuinely concurrent** requests on the same order, or must survive a **process crash mid-payment**. A single-instance shop with modest traffic does not need it, and adding it there is imposing architecture the merchant did not ask for. |

## The API in 60 seconds

- Two APIs: **Gateway API** (`$PSP_API_URL/api/v1`, Bearer `PSP_API_KEY`) for
  payment operations, and **Merchant API** (`/merchant-api/v1`, HTTP Basic
  with dashboard credentials) for read-mostly reporting — see
  `references/merchant-api-and-reference-data.md`.
- One universal endpoint creates money movements: `POST /api/v1/payments` with
  `paymentType`: `DEPOSIT`, `WITHDRAWAL` or `REFUND` (refund = new payment
  with `parentPaymentId`; only `paymentType` and `currency` are required).
- Default deposit flow: create payment → get `redirectUrl` → redirect the
  customer → learn the outcome **two ways, both feeding the same safe state
  mapping**: the **webhook** (push) and **status polling** `GET /payments/{id}`
  (pull — poll when the customer returns to `returnUrl`, and reconcile orders
  left non-final). The redirect itself is never proof of payment; implement both
  paths (see `integration-patterns.md` → "Status polling").
- Payment states: `CHECKOUT`, `PENDING`, `AUTHORIZED`, `AWAITING_APPROVAL`
  (non-final) → `COMPLETED`, `DECLINED`, `CANCELLED` (final). Webhooks fire on
  COMPLETED / DECLINED / CANCELLED / AUTHORIZED.
- Webhooks carry a `Signature` header: HMAC-SHA256 of the raw JSON body with
  `PSP_SIGNING_KEY`. Verify before trusting.
- Amounts are decimal major units (`11.12` = 11.12 EUR). The final amount may
  differ from the requested one (`customerAmount`/`customerCurrency` 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 23 — file references are metadata, not package contents.